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.