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

'tol_kind'

'relative_max'

Tolerance interpretation. One of 'relative_max', 'absolute_max', 'relative_l2', 'absolute_l2', 'relative_tail', 'absolute_tail', 'relative_pointwise'.

'max_depth'

0 (auto)

Tree-depth ceiling. 0 = auto, 50; -1 = the root panel only.

'max_memory_mib'

0 (auto)

Memory budget in MiB. 0 = auto (4/32/256 MiB for dim 1/2/3); -1 = no cap.

'allow_max_depth_leaves'

false

Keep non-converged panels at max depth instead of raising.

'min_uniform_depth'

0

Force uniform refinement to this depth before adaptivity.

'filename'

'' (none)

Path of a plain-text fit file. If the file exists and its header matches the fit, the fit loads it and never calls f. Otherwise the fit runs and writes the file. Set 'out_dim' to skip the probe call of f.

See the options guide for full descriptions.

Further

Examples: bindings/matlab/examples/ (example_1d.m, example_2d.m, example_vector.m).