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: n points, 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/.