MATLAB / Octave
One source builds for both MATLAB (R2019b+) and GNU Octave (>= 6).
mwrap generates the binding from a
single treeweave.mw source. The user-facing treeweave.m is a thin
classdef that holds the opaque C handle.
Install (MATLAB)
With mip, from the mip-org/labs channel:
mip install --channel mip-org/labs treeweave
mip load treeweave
Or download the bundle directly. Each release attaches a self-contained
treeweave-matlab-<version>-<platform> bundle (linux-x64, windows-x64,
macos-arm64, macos-x64) on the Releases page. The MEX statically links
the C ABI, so the bundle has no runtime dependencies. Download it, extract it,
and addpath the extracted directory (which holds treeweave.m, the generated
tw_*.m stubs, and treeweave_mex.<ext>).
VER=stable
PLATFORM=linux-x64
URL="https://github.com/DiamonDinoia/treeweave/releases/download/${VER}/treeweave-matlab-${VER}-${PLATFORM}.tar.gz"
curl -fLO "$URL" || wget "$URL"
tar xzf "treeweave-matlab-${VER}-${PLATFORM}.tar.gz"
addpath('treeweave-matlab-stable-linux-x64')
Install (Octave)
Octave has no stable MEX ABI across versions, so there is no prebuilt Octave MEX. Download the source release and build against your local Octave:
VER=stable
URL="https://github.com/DiamonDinoia/treeweave/archive/refs/tags/${VER}.tar.gz"
curl -fL "$URL" -o "treeweave-${VER}-source.tar.gz" || wget -O "treeweave-${VER}-source.tar.gz" "$URL"
tar xzf "treeweave-${VER}-source.tar.gz"
cd "treeweave-${VER}"
cmake --preset bindings-octave
cmake --build build/bindings-octave -j
Build from source
Building is an opt-in CMake option, TREEWEAVE_BUILD_MATLAB. With
mkoctfile (or MATLAB) on PATH,
CMake fetches the mwrap generator, generates the gateway + tw_*.m stubs, and
compiles the MEX:
cmake --preset bindings-octave # or bindings-matlab if building against MATLAB
cmake --build build/bindings-octave -j
ctest --test-dir build/bindings-octave -R matlab_treeweave --output-on-failure
Requirements: MATLAB R2019b+ (tested on R2025a) or GNU Octave with
mkoctfile, plus a C++20 toolchain and CMake >= 3.25.
Minimal example
Add the treeweave.m class directory and the generated MEX directory to the
path, then fit and evaluate:
% example_1d.m: 1-D scalar fit of exp(0.5*x)+sin(3*x) on [0,1]
%
% Before running: the build tree (where treeweave_mex.mex/mexa64 and the
% tw_*.m stubs live) must already be on the MATLAB/Octave path, e.g.:
% addpath('/path/to/build/bindings-matlab/bindings/matlab/mwrap_gen')
% This script adds only the source dir (treeweave.m classdef).
addpath(fileparts(fileparts(mfilename('fullpath')))); % add bindings/matlab/ (treeweave.m)
f = @(x) exp(0.5*x(1)) + sin(3*x(1));
% Fit f(x) on [0, 1] syntax is
% treeweave(callback, lower_bound, upper_bound, tolerance, name/value options).
obj = treeweave(f, 0, 1, 1e-8);
Xtest = linspace(0, 1, 500)';
% Evaluate obj on 500 points and print the maximum error.
Yhat = obj.eval(Xtest);
Yref = exp(0.5*Xtest) + sin(3*Xtest);
fprintf('1D max abs error: %.3e\n', max(abs(Yhat - Yref)));
fprintf('Memory: %.1f KiB\n', obj.memory_usage()/1024);
delete(obj);
The callback receives a 1 x dim row and returns a scalar or a
out_dim x 1 column. The fit domain is [a, b); evaluating exactly at the
upper corner b returns the boundary value (the last cell’s polynomial).
Every other out-of-domain point returns NaN, below a, above b, and
NaN/±Inf inputs alike, uniformly across the scalar, batch and sorted paths.
Evaluation routes
The object is callable directly (or via obj.eval), and two name/value flags
select the fast paths:
X = linspace(2, 10, 1000)'; % N x dim
obj(X) % batch: N x dim -> N x out_dim
obj.eval(X) % identical to obj(X)
obj(X, 'sorted', true) % promise X is non-decreasing, X(i) <= X(i+1) (dim == 1)
obj(X, 'transposed', true) % batch -> out_dim x N (out_dim > 1)
'sorted', true skips treeweave’s internal counting-sort and is ~3-4x faster
when the caller can promise the column is ascending, which covers linspace
grids, quadrature nodes and time series. Nothing checks the promise, and
unsorted input gives wrong values, so use the plain batch call when the order is
unknown.
Multi-dimensional fits
Pass row-vector corners; the callback takes a 1 x dim row and returns an
out_dim x 1 column:
% 2-D input -> 3-D vector output (out_dim inferred by probing the midpoint)
g = @(x) [sin(x(1)+x(2)); cos(x(1)-x(2)); x(1)*x(2)];
obj2 = treeweave(g, [-1 -1], [1 1], 1e-6, 'max_memory_mib', 64);
[gx, gy] = meshgrid(linspace(-1, 1, 50));
Y = obj2([gx(:), gy(:)]); % 2500 x 3
Yt = obj2([gx(:), gy(:)], 'transposed', true); % 3 x 2500 (struct-of-arrays)
fprintf('Memory: %.1f KiB\n', obj2.memory_usage() / 1024);
delete(obj2);
Options
Pass name-value pairs after tol to treeweave(...) to override defaults:
obj = treeweave(f, 2, 10, 1e-10, 'tol_kind', 'absolute_max', 'max_memory_mib', 64);
Available options:
Name |
Default |
Meaning |
|---|---|---|
|
|
Tolerance interpretation. One of |
|
|
Tree-depth ceiling. |
|
|
Memory budget in MiB. |
|
|
Keep non-converged panels at max depth instead of raising. |
|
|
Force uniform refinement to this depth before adaptivity. |
|
|
Path of a plain-text fit file. If the file exists and its header matches the
fit, the fit loads it and never calls |
See the options guide for full descriptions.
Further
Examples: bindings/matlab/examples/
(example_1d.m, example_2d.m, example_vector.m).