Julia
Install
The package resolves libtreeweave_c in this order: the LIBTREEWEAVE_C
environment variable, then a sibling build*/ directory for developers, then
a prebuilt download from the GitHub Release.
The normal install uses the prebuilt release binary:
using Pkg
Pkg.add(url="https://github.com/DiamonDinoia/treeweave", subdir="bindings/julia/Treeweave")
On first build, Julia downloads the matching libtreeweave_c from the GitHub
Release and caches it. Override the release source repo with TREEWEAVE_REPO,
or point LIBTREEWEAVE_C at a local C ABI build.
Minimal example
# Example: 1D scalar function approximation.
using Treeweave
f = x -> exp(0.5x) + sin(3x)
a, b_val = 0.0, 2.0
println("Fitting f(x) = exp(0.5x) + sin(3x) on [$a, $b_val] ...")
# Fit f(x) on [0, 2] syntax is fit(callback, lower_bound, upper_bound, tolerance).
approx = fit(f, a, b_val, 1e-10)
println(" ", approx) # show() prints dtype, dim, out_dim and bytes
println("\nPoint-by-point check:")
for x in 0.0:0.25:2.0 # b_val is evaluable too (returns the boundary value)
exact = f(x)
# Evaluate approx on x and print the result.
approx_val = approx(x)
err = abs(approx_val - exact)
println(" x=$x exact=$(round(exact,digits=8)) approx=$(round(approx_val,digits=8)) err=$(round(err,sigdigits=3))")
end
# Batch eval: the handle is called directly. The fit domain is [a, b_val);
# the upper corner b_val is evaluable too (it returns the boundary value).
xs = collect(range(a, b_val; length=1001))
# Evaluate approx on a batch and print the maximum error.
R = approx(xs)
max_err = maximum(abs.(R .- f.(xs)))
println("\nMax error over 1000 points: $(max_err)")
fit infers the dimensions from the callable, so the common case is
fit(f, a, b, tol). Call the fitted object directly, with a point or with a
batch. Tune the fit with TreeweaveOptions (see Fit options).
fit takes the callable first, so do-block syntax fits a function
defined at the call site. That is the Julia counterpart of the Python
decorator:
approx = fit(2.0, 10.0, 1e-10) do s
sum(k -> k^(-s), 1:1000)
end
Evaluation routes
Calling the handle dispatches on its argument, and two keyword flags select the fast paths:
approx(3.5) # single point -> scalar (or Vector)
approx(xs) # batch (Vector) -> Vector / n×out_dim
approx(xs; sorted = true) # promise xs is non-decreasing, xs[i] <= xs[i+1] (dim == 1)
approx(xs; transposed = true) # batch -> out_dim×n (requires out_dim > 1)
sorted = true skips treeweave’s internal bin-sort and is ~3-4x faster when
the caller can promise xs is ascending, which covers range grids,
quadrature nodes and time series. Nothing checks the promise, and unsorted input
gives wrong values, so use the plain batch path when the order is unknown.
sorted is 1-D only. transposed = true returns each output component in
its own contiguous row.
Every path handles out-of-domain input the same way. A point exactly at b
returns the boundary value. Points below a, points above b, and NaN
or ±Inf inputs all return NaN.
Multi-dimensional fits
Pass vector corners; the callback takes dim scalar arguments and returns a
scalar or a length-out_dim tuple:
# 2-D input -> 3-D vector output (out_dim inferred by probing the midpoint)
approx = fit((x, y) -> (sin(x) * cos(y), x + y, x * y), [0.0, 0.0], [1.0, 1.0], 1e-8)
approx([0.3, 0.7]) # single point -> length-3 Vector
X = rand(100, 2)
approx(X) # batch -> 100×3 Matrix
approx(X; transposed = true) # batch -> 3×100 Matrix
Options
Pass a TreeweaveOptions as the fifth argument to fit:
using Treeweave
opts = TreeweaveOptions(tol_kind="absolute_max", max_depth=30, max_memory_mib=64)
approx = fit(f, 2.0, 10.0, 1e-10, opts)
Available fields (all keyword-only, all have defaults):
Field |
Default |
Meaning |
|---|---|---|
|
|
Tolerance interpretation. One of |
|
|
Tree-depth ceiling. |
|
|
Memory budget in MiB. |
|
|
Keep non-converged panels at max depth instead of throwing. |
|
|
Force uniform refinement to this depth before adaptivity. |
Fit file
The filename keyword of fit names a plain-text fit file. If the file
exists and its header matches the dimensions, domain, tol, options and
dtype, fit loads the file and does not call f. Otherwise fit runs
and writes the file. A malformed file with a matching header makes fit
throw. The file does not identify f, so delete it when f changes. Pass
out_dim explicitly, because the default probe calls f once.
approx = fit(f, 2.0, 10.0, 1e-10; out_dim = 1, filename = "f.tw") # fits and writes
approx = fit(f, 2.0, 10.0, 1e-10; out_dim = 1, filename = "f.tw") # loads, 0 calls of f
See Fit options for a full description of each option and the tolerance kinds.
Further
Build from source only when working on the binding or testing an unreleased
change. Build the C ABI in a checkout, then develop the package against the
sibling build:
git clone https://github.com/DiamonDinoia/treeweave.git
cd treeweave
cmake --preset bindings-julia
cmake --build build/bindings-julia -j --target treeweave_c
using Pkg
Pkg.develop(path="bindings/julia/Treeweave")
Pkg.build("Treeweave")
ctest --test-dir build/bindings-julia -R julia_treeweave
Examples: bindings/julia/Treeweave/examples/.