C
libtreeweave_c is the installable C library. It ships the treeweave.h
header, a shared library and a static library. The prebuilt binary dispatches
across the x86 SIMD ladder at runtime, so a source build runs no faster for a C
consumer.
Prefer the binary; build from source only when no binary covers the target
platform. Open an issue to request a prebuilt binary for another platform.
See Runtime ISA dispatch.
Install
Direct tarball
Download the Linux x86-64 tarball from the Releases page, then compile:
VER=stable
PLATFORM=linux-x86_64
URL="https://github.com/DiamonDinoia/treeweave/releases/download/${VER}/treeweave-${VER}-${PLATFORM}.tar.gz"
curl -fLO "$URL" || wget "$URL"
tar xzf "treeweave-${VER}-${PLATFORM}.tar.gz" # extracts include/ lib/ into ./
gcc examples/C/simple.c -Iinclude -Llib -ltreeweave_c -lm -o simple
LD_LIBRARY_PATH=lib ./simple
Other platforms: linux-aarch64, macos-arm64, macos-x86_64, windows-x64
(zip). The tarball includes include/treeweave.h, lib/libtreeweave_c, and a
find_package(treeweave) CMake package.
To pin a release, use the numeric version (e.g. 0.0.6) in the asset name and prefix
the tag with v: .../releases/download/v0.0.6/treeweave-0.0.6-linux-x86_64.tar.gz.
CMake package
find_package(treeweave REQUIRED)
target_link_libraries(my_app PRIVATE treeweave::treeweave_c)
Source build
git clone https://github.com/DiamonDinoia/treeweave.git
cd treeweave
cmake --preset dev-release
cmake --build build/dev-release --target treeweave_c -j
Minimal example
/* simple.c: minimal treeweave C API usage, compiled as C11 (not C++).
*
* Doubles as the ABI smoke test: if this links and runs, the header is
* C-clean and no C++ exception escaped the boundary. */
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <treeweave.h>
/* f(x) = exp(x) on [0, 1]. input_dim == output_dim == 1, so x and y each
* point at a single value. */
static void kernel(const double *x, double *y, void *data) {
(void)data;
y[0] = exp(x[0]);
}
int main(void) {
const double a = 0.0;
const double b = 1.0;
/* Fit exp(x) on [0, 1] syntax is
treeweave_fit(callback, input_dim, output_dim, lower, upper, tolerance, context, options). */
treeweave_t fn =
treeweave_fit(kernel,
/*input_dim=*/1, /*output_dim=*/1, &a, &b, /*tol=*/1e-10, /*context=*/NULL, /*opts=*/NULL);
if (fn == NULL) {
fprintf(stderr, "treeweave_fit failed: %s\n", treeweave_last_error());
return EXIT_FAILURE;
}
printf("dtype=%d input_dim=%d output_dim=%d memory=%zu bytes\n", (int)treeweave_dtype(fn), treeweave_input_dim(fn),
treeweave_output_dim(fn), treeweave_memory_usage(fn));
/* Evaluate fn on points in [0, 1] and print the maximum error. */
/* Scalar eval at a few points; compare to the exact value. The by-value
treeweave_eval_1d returns the result directly, with no output pointer, which
is the ergonomic form for a 1D->1D fit (y = f(x)). */
double max_abs_err = 0.0;
for (int i = 0; i <= 10; ++i) {
const double x = (double)i / 10.0;
const double y = treeweave_eval_1d(fn, x);
const double err = fabs(y - exp(x));
if (err > max_abs_err)
max_abs_err = err;
}
printf("max |approx - exp| over 11 points: %.3e\n", max_abs_err);
/* Closed upper endpoint: evaluating exactly at the upper corner b returns
the boundary value (not NaN). The lower corner a is in-domain too. */
printf("f(a=%.1f) approx = %.12f (exact %.12f)\n", a, treeweave_eval_1d(fn, a), exp(a));
printf("f(b=%.1f) approx = %.12f (exact %.12f)\n", b, treeweave_eval_1d(fn, b), exp(b));
/* Batch (AoS) eval. */
double xs[5] = {0.05, 0.25, 0.5, 0.75, 0.95};
double ys[5] = {0};
treeweave_batch(fn, xs, ys, 5);
printf("exp(0.5) approx = %.12f (exact %.12f)\n", ys[2], exp(0.5));
fn = treeweave_free(fn);
return (max_abs_err < 1e-8) ? EXIT_SUCCESS : EXIT_FAILURE;
}
Evaluation entry points
libtreeweave_c is the stable C interface every non-C++ binding builds on.
Precision lives in the prefix, FINUFFT/FFTW style: treeweave_* entry points
operate on double and treeweavef_* twins operate on float.
Type-erased queries (dtype, dims, memory, free) take the opaque handle and stay
single-prefix.
Handle and callbacks
typedef struct treeweave_function *treeweave_t;
typedef void (*treeweave_func_t)(const double *x, double *y, void *context);
typedef void (*treeweavef_func_t)(const float *x, float *y, void *context);
Fit
treeweave_t treeweave_fit (treeweave_func_t f, int input_dim, int output_dim,
const double *a, const double *b, double tol,
void *context, const treeweave_opts *opts);
treeweave_t treeweavef_fit(treeweavef_func_t f, int input_dim, int output_dim,
const float *a, const float *b, double tol,
void *context, const treeweave_opts *opts);
context carries optional callback state; opts is NULL for defaults.
Options take no degree argument. The leaf has 6 coefficients per axis in 1D
and 7 in 2D and 3D, on every CPU. On failure, fit returns NULL and sets the
thread-local treeweave_last_error().
Evaluate
void treeweave_eval (treeweave_t f, const double *x, double *y);
void treeweave_batch (treeweave_t f, const double *x, double *res, size_t n);
void treeweave_sorted (treeweave_t f, const double *x, double *res, size_t n);
void treeweave_transposed(treeweave_t f, const double *x, double *const *soa, size_t n);
eval: one point.batch:npoints, array-of-structs (interleaved) layout.sorted: 1-D fast path for ascending inputs.transposed: struct-of-arrays output for multi-output fits.
Each has a treeweavef_* float twin.
Every eval path handles out-of-domain input the same way. A point exactly at
the upper corner b returns the boundary value. Points below a, points
above b, and NaN or ±Inf inputs all yield NaN. The batch hot path
stays branchless, because the domain test compiles to a SIMD mask.
By-value scalar eval
For the common y = f(x) case on a scalar-output handle
(output_dim == 1), thin wrappers take coordinates by value and return the
result. The _1d/_2d/_3d suffix is the call arity and must match the
handle’s input_dim:
double treeweave_eval_1d(treeweave_t f, double x0);
double treeweave_eval_2d(treeweave_t f, double x0, double x1);
double treeweave_eval_3d(treeweave_t f, double x0, double x1, double x2);
float treeweavef_eval_1d(treeweave_t f, float x0);
float treeweavef_eval_2d(treeweave_t f, float x0, float x1);
float treeweavef_eval_3d(treeweave_t f, float x0, float x1, float x2);
On a dimension mismatch (the handle’s input_dim/output_dim does not match
the call arity / scalar output), they set treeweave_last_error() and return
NaN. Vector-output handles keep the pointer API (treeweave_eval /
treeweave_transposed).
Introspection and teardown
treeweave_dtype_t treeweave_dtype (treeweave_t f); /* TREEWEAVE_F64 / TREEWEAVE_F32 */
int treeweave_input_dim (treeweave_t f);
int treeweave_output_dim (treeweave_t f);
size_t treeweave_memory_usage(treeweave_t f);
void treeweave_print_stats (treeweave_t f); /* print fit/eval stats to stdout */
treeweave_t treeweave_free (treeweave_t f); /* returns NULL */
const char *treeweave_last_error (void); /* thread-local */
Options
Pass a treeweave_opts* as the last argument (or NULL for defaults):
treeweave_opts opts;
treeweave_default_opts(&opts);
opts.tol_kind = TREEWEAVE_ABSOLUTE_MAX;
opts.max_memory_mib = 64;
treeweave_t fn = treeweave_fit(kernel, 1, 1, &a, &b, 1e-10, NULL, &opts);
A zero-filled struct (treeweave_opts opts = {0}; or memset to 0) is
the same as treeweave_default_opts: a zero field is its default.
max_depth = 0 is auto (50) and max_memory_mib = 0 is auto
(4/32/256 MiB in 1D/2D/3D).
treeweave_tol_kind_t values: TREEWEAVE_RELATIVE_MAX (default),
TREEWEAVE_ABSOLUTE_MAX, TREEWEAVE_RELATIVE_L2, TREEWEAVE_ABSOLUTE_L2,
TREEWEAVE_RELATIVE_TAIL, TREEWEAVE_ABSOLUTE_TAIL, TREEWEAVE_RELATIVE_POINTWISE.
Set opts.filename to a path to save the fit to a plain-text file. The next
fit with the same arguments loads the file and does not call the callback.
treeweave_default_opts sets it to NULL (no file). A malformed file or an
unwritable path makes the fit return NULL. treeweave_last_error() gives
the reason.
opts.filename = "kernel.fit";
treeweave_t fn = treeweave_fit(kernel, 1, 1, &a, &b, 1e-10, NULL, &opts);
See Fit options for the full description of each field.
Multi-arch dispatch
On x86, build with -DTREEWEAVE_C_MULTIARCH=ON and a baseline of
-DTREEWEAVE_ARCH=x86-64. The library compiles a portable baseline plus
wider variants and selects one at runtime via CPU detection, so a single binary
runs everywhere. GCC/Clang use SSE4.2 / AVX2 / AVX-512 variants; MSVC uses AVX /
AVX2 / AVX-512.
Thread safety
Once treeweave_fit returns a handle, its eval functions are safe to call
concurrently from many threads. treeweave_last_error() is thread-local.
Further
Runnable C sources: examples/C/.