Fortran
The Fortran binding is a thin iso_c_binding module (treeweave) over the C
ABI. Callbacks are bind(C) procedures; c_funloc yields the C-callable
pointer and context carries runtime parameters via c_loc / c_f_pointer.
Install
Prebuilt C ABI
Fortran calls the C ABI, so the release C archive is enough alongside an existing Fortran wrapper or build setup:
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"
Source build
Build the treeweave_fortran target using the CMake preset:
git clone https://github.com/DiamonDinoia/treeweave.git
cd treeweave
cmake --preset bindings-fortran
cmake --build build/bindings-fortran -j
Without a Fortran compiler, CMake skips the Fortran targets. The build writes
the generated treeweave module into the build tree.
Minimal example
! example.f90: fit exp(x) and evaluate from Fortran via the treeweave C ABI.
! Mirrors examples/C/simple.c: plain bind(C) callback, scalar eval, batch eval.
! For the context pattern see README.md § "The context pattern".
! Callbacks must be bind(C) procedures so c_funloc() yields a C-callable
! pointer; module procedures are the cleanest way to provide them.
module example_kernels
use, intrinsic :: iso_c_binding
implicit none
contains
subroutine kernel_exp(x, y, context) bind(C)
real(c_double), intent(in) :: x(*)
real(c_double), intent(out) :: y(*)
type(c_ptr), value :: context
y(1) = exp(x(1))
end subroutine kernel_exp
end module example_kernels
program treeweave_example
use, intrinsic :: iso_c_binding
use treeweave
use example_kernels
implicit none
type(c_ptr) :: h
real(c_double) :: a(1), b(1), tol
real(c_double) :: xs(11), res(11)
real(c_double) :: exact, err, max_err
integer :: i
a(1) = 0.0_c_double
b(1) = 1.0_c_double
tol = 1.0e-10_c_double
! Fit exp(x) on [0, 1] syntax is
! treeweave_fit(callback, input_dim, output_dim, lower, upper, tolerance, context, options).
h = treeweave_fit(c_funloc(kernel_exp), 1_c_int, 1_c_int, a, b, tol, &
c_null_ptr, c_null_ptr)
if (.not. c_associated(h)) then
write (*, '(2A)') "treeweave_fit failed: ", treeweave_error_message()
error stop 1
end if
write (*, '(A,I0,A,I0,A,I0,A)') "fit exp(x): input_dim=", treeweave_input_dim(h), &
" output_dim=", treeweave_output_dim(h), " memory=", treeweave_memory_usage(h), " bytes"
! treeweave_eval reads the dims off the handle: a scalar argument is a
! point, an array argument is a batch. No call site picks the batch route.
write (*, '(A,F0.12,A,F0.12)') "exp(0.5) approx=", treeweave_eval(h, 0.5_c_double), &
" exact=", exp(0.5_c_double)
! Batch eval over 11 points on [0, 1].
do i = 1, 11
xs(i) = real(i - 1, c_double) / 10.0_c_double
end do
res = treeweave_eval(h, xs)
max_err = 0.0_c_double
do i = 1, 11
exact = exp(xs(i))
err = abs(res(i) - exact)
if (err > max_err) max_err = err
end do
write (*, '(A,ES10.3)') "batch exp(x): max |approx - exact| = ", max_err
if (max_err > 1.0e-8_c_double) then
write (*, '(A)') "error too large"
error stop 1
end if
h = treeweave_free(h)
write (*, '(A)') "OK"
end program treeweave_example
Carrying parameters through context:
type, bind(C) :: params_t
real(c_double) :: amplitude, frequency
end type params_t
! ... in the callback:
type(params_t), pointer :: p
call c_f_pointer(context, p)
y(1) = p%amplitude * sin(p%frequency * x(1))
! ... at the call site: pass c_loc(params) as the context argument.
Batch & sorted eval
real(c_double) :: xs(1000), res(1000)
integer(c_size_t) :: n = 1000_c_size_t
call treeweave_batch(h, xs, res, n) ! batch: many points, any order
call treeweave_sorted(h, xs, res, n) ! promise xs(i) <= xs(i+1), 1-D; ~3-4x faster
treeweave_sorted requires 1-D input (input_dim == 1). The caller
promises ascending order, and treeweave does not verify it.
Options
Pass an options struct via the last argument (or c_null_ptr for defaults):
use treeweave
type(treeweave_opts) :: opts
opts = treeweave_default_opts()
opts%tol_kind = TREEWEAVE_ABSOLUTE_MAX
opts%max_memory_mib = 64
h = treeweave_fit(c_funloc(kernel), 1_c_int, 1_c_int, a, b, 1.0e-10_c_double, &
c_null_ptr, c_loc(opts))
Fit file
The filename component of treeweave_opts names a plain-text fit file.
It is c_null_ptr by default, which means no file. treeweave_set_filename
copies a Fortran string into a null-terminated buffer and points filename
at it. The caller keeps the buffer allocated until the fit returns. If the file
exists and its header matches the dtype, dimensions, domain, tol and
options, the fit loads the file and does not call the kernel. Otherwise the fit
runs and writes the file. A malformed file with a matching header makes the fit
return a null handle. The file does not identify the kernel.
character(kind=c_char), allocatable, target :: buf(:)
call treeweave_set_filename(opts, "kernel.tw", buf)
h = treeweave_fit(c_funloc(kernel), 1_c_int, 1_c_int, a, b, 1.0e-10_c_double, &
c_null_ptr, c_loc(opts))
See Fit options for the full description of each field and tolerance kind.
Further
cmake --preset bindings-fortran
cmake --build build/bindings-fortran -j
ctest --test-dir build/bindings-fortran -R fortran_treeweave
Without a Fortran compiler, CMake skips the Fortran targets. Full example: bindings/fortran/example.f90.