API reference

class Axis

Describes one monotonic coordinate axis of a tabulated grid.

An axis can either be represented as uniformly spaced coordinates or as an explicit list of strictly increasing coordinates.

Public Functions

inline Axis()

Construct a single-point uniform axis at coordinate zero.

inline axis_kind kind() const

Return the representation used by this axis.

Returns:

Axis storage representation.

inline std::size_t size() const

Return the number of support points on the axis.

Returns:

Number of support points.

inline double min() const

Return the smallest coordinate value on the axis.

Returns:

Smallest coordinate value.

inline double max() const

Return the largest coordinate value on the axis.

Returns:

Largest coordinate value.

inline double coordinate(std::size_t index) const

Return one coordinate value by index.

Uniform axes generate the coordinate analytically. Explicit axes return the stored value.

Parameters:

index – Zero-based coordinate index.

Returns:

Coordinate value at the requested index.

inline std::vector<double> coordinates() const

Return the full coordinate list for this axis.

For uniform axes this materializes the coordinates on demand.

Returns:

Full coordinate list in ascending order.

inline bool equivalent(const Axis &other) const

Check whether two axes describe the same grid support.

Parameters:

other – Axis to compare against.

Returns:

true if both axes represent the same support points.

inline std::pair<std::size_t, double> bracket(double value, bounds_policy policy = bounds_policy::clamp) const

Locate the interpolation interval and upper weight for a query.

Values outside the axis range are clamped to the nearest interval endpoint by default, or rejected when policy is bounds_policy::throw_error. The returned pair is (lower_index, upper_weight).

Parameters:

• value – Coordinate value to bracket.

• policy – Bounds handling behavior for out-of-domain values.

Returns:

Pair of lower interval index and upper interpolation weight.

Public Static Functions

static inline Axis uniform(double min_value, double max_value, std::size_t size)

Construct a uniformly spaced axis.

For a single-point axis, max_value is ignored and the lone coordinate is stored as min_value.

Parameters:

• min_value – Smallest coordinate on the axis.

• max_value – Largest coordinate on the axis for multi-point axes.

• size – Number of support points on the axis.

Returns:

Uniform axis descriptor.

static inline Axis from_coordinates(const std::vector<double> &coordinates)

Construct an axis from explicit coordinates.

The coordinates must be strictly increasing.

Parameters:

coordinates – Explicit coordinate list in ascending order.

Returns:

Axis descriptor using explicit coordinates.

template<std::size_t Dim>
class Grid

N-dimensional grid metadata with stride and query preparation logic.

A grid is defined by one axis descriptor per dimension. It provides the logic to prepare interpolation stencils for query points and to validate compatibility with field groups.

Template Parameters:

Dim – Number of dimensions.

Public Functions

inline Grid()

Construct an empty grid descriptor.

The default-constructed grid has zero points and is mainly useful as a placeholder before assigning a fully constructed grid.

inline explicit Grid(const std::array<Axis, Dim> &axes)

Construct a grid from one axis descriptor per dimension.

Parameters:

axes – Axis descriptors in dimension order.

inline const std::array<Axis, Dim> &axes() const

Return all axis descriptors.

Returns:

Axis descriptors in dimension order.

inline const Axis &axis(std::size_t index) const

Return one axis descriptor by dimension index.

Parameters:

index – Dimension index.

Returns:

Axis descriptor for the selected dimension.

inline const std::array<std::size_t, Dim> &extents() const

Return the extent of each dimension.

Returns:

Grid extents in dimension order.

inline std::size_t extent(std::size_t index) const

Return the extent by dimension index.

Parameters:

index – Dimension index.

Returns:

Number of support points along the selected dimension.

inline const std::array<std::size_t, Dim> &strides() const

Return the flat-memory strides of each dimension.

Returns:

Flat-memory strides in dimension order.

inline std::size_t stride(std::size_t index) const

Return the flat-memory stride by dimension index.

Parameters:

index – Dimension index.

Returns:

Flat-memory stride for the selected dimension.

inline std::size_t point_count() const

Return the total number of support points in the grid.

Returns:

Total point count across all dimensions.

inline bool equivalent(const Grid &other) const

Check whether another grid uses the same axes.

Parameters:

other – Grid to compare against.

Returns:

true if all axes are equivalent.

inline LinearStencil<Dim> prepare_linear(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Precompute the multilinear interpolation stencil for one query point.

This is the key operation to reuse when several fields share a grid.

Parameters:

• coordinates – Query coordinates in axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Linear stencil containing point indices and weights.

inline CubicStencil<Dim> prepare_cubic(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Precompute a local tensor-product cubic Lagrange interpolation stencil for one query point.

This method builds a local interpolation stencil using four support points per axis. Along each axis, the one-dimensional weights are the cubic Lagrange basis weights for the selected four axis coordinates:

L_i(x) = prod_{j != i} (x - x_j) / (x_i - x_j)

The multidimensional stencil is formed as the tensor product of these one-dimensional Lagrange weights. Consequently, the stencil contains 4^Dim table values.

The basis weights are computed from the actual axis coordinates, so non-uniform axes are supported. Near domain boundaries, the four-point support window is shifted/clamped so that it remains inside the table. This makes the cubic stencil one-sided near boundaries.

Cubic interpolation is intended as an experimental higher-order path. The linear path remains the recommended default for performance-critical high-dimensional table lookup.

Parameters:

• coordinates – Query coordinates in axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Throws:

std::invalid_argument – if any axis contains fewer than four points.

Returns:

Cubic stencil containing flattened table point indices and tensor-product weights.

Public Static Attributes

static constexpr std::size_t dimensions = Dim

Number of dimensions.

template<std::size_t Dim, std::size_t PointsPerAxis>
class TensorStencil

Fixed-size tensor-product interpolation stencil for one query point.

A stencil stores linearized point indices and corresponding weights for one interpolation point so that multiple fields on the same grid can reuse the same lookup work.

Template Parameters:

• Dim – Number of dimensions.

• PointsPerAxis – Number of interpolation points along each axis.

Public Functions

inline const std::array<std::size_t, points> &point_indices() const

Return the flat storage indices of all interpolation points.

Returns:

Flat point indices for all interpolation points.

inline std::size_t point_index(std::size_t index) const

Return the flat storage index by stencil point index.

Parameters:

index – Stencil point index.

Returns:

Flat point index of the selected stencil point.

inline const std::array<double, points> &weights() const

Return the interpolation weights of all stencil points.

Returns:

Interpolation weights for all stencil points.

inline double weight(std::size_t index) const

Return the interpolation weight by stencil point index.

Parameters:

index – Stencil point index.

Returns:

Interpolation weight for the selected stencil point.

Public Static Attributes

static constexpr std::size_t dimensions = Dim

Number of dimensions.

static constexpr std::size_t points_per_axis = PointsPerAxis

Number of stencil points along each axis.

static constexpr std::size_t points = detail::pow_size(PointsPerAxis, Dim)

Total number of interpolation points in the tensor-product stencil.

template<std::size_t Dim>
using ndtbl::LinearStencil = TensorStencil<Dim, 2>

Multilinear interpolation stencil with two points per axis.

template<std::size_t Dim>
using ndtbl::CubicStencil = TensorStencil<Dim, 4>

Local tensor-product cubic Lagrange interpolation stencil with four points per axis.

template<std::size_t Dim, class Stored>
class FieldGroup

One grid plus one or more named fields stored in interleaved flat memory.

The storage layout is point-major in row-major grid order: point0.field0, point0.field1, ..., point1.field0, ... where the last grid axis varies fastest before stepping to the next field tuple. One prepared interpolation stencil can accumulate all fields together.

Template Parameters:

• Dim – Grid dimensionality of the group.

• Stored – Scalar payload type stored in the group.

Public Functions

inline FieldGroup(const Grid<Dim> &grid, const std::vector<std::string> &field_names, const std::vector<Stored> &interleaved_values)

Construct a field group on a shared grid.

Parameters:

• grid – Shared interpolation grid.

• field_names – Logical names of the stored fields.

• interleaved_values – Flat point-major payload.

inline FieldGroup(const Grid<Dim> &grid, const std::vector<std::string> &field_names, std::vector<Stored> &&interleaved_values)

Construct a field group from owned payload storage.

Parameters:

• grid – Shared interpolation grid.

• field_names – Logical names of the stored fields.

• interleaved_values – Flat point-major payload whose ownership is moved into the group.

inline FieldGroup(const Grid<Dim> &grid, const std::vector<std::string> &field_names, const PayloadView<Stored> &interleaved_values, std::shared_ptr<const std::uint8_t> payload_owner)

Construct a field group from externally managed payload storage.

Parameters:

• grid – Shared interpolation grid.

• field_names – Logical names of the stored fields.

• interleaved_values – View over a contiguous point-major payload.

• payload_owner – Shared owner keeping the viewed payload alive.

inline const Grid<Dim> &grid() const

Return the shared grid metadata.

Returns:

Shared interpolation grid.

inline std::size_t field_count() const

Return the number of stored fields.

Returns:

Number of named fields.

inline const std::vector<std::string> &field_names() const

Return all field names in storage order.

Returns:

Field names in payload order.

inline std::size_t point_count() const

Return the number of support points in the shared grid.

Returns:

Number of grid support points.

inline PayloadView<Stored> interleaved_values() const

Return a read-only view of the raw interleaved field payload.

Returns:

Point-major interleaved payload view.

inline std::size_t field_index(const std::string &name) const

Resolve a field name to its local field index.

Parameters:

name – Field name to look up.

Returns:

Zero-based field index in storage order.

template<class Stencil>
inline std::vector<Stored> evaluate_all(const Stencil &stencil) const

Evaluate all fields using a previously prepared interpolation stencil.

See also

Grid::prepare_linear

See also

Grid::prepare_cubic

See also

evaluate_all_linear(const std::array<double, Dim>&)

Template Parameters:

Stencil – Fixed-size interpolation stencil type.

Parameters:

stencil – Prepared stencil to reuse across fields.

Returns:

Interpolated field values in storage order.

template<class Output, class Stencil>
inline std::vector<Output> evaluate_all_as(const Stencil &stencil) const

Evaluate all fields using a previously prepared interpolation stencil and caller-selected output precision.

See also

evaluate_all(const Stencil&)

Template Parameters:

• Output – Floating-point type produced by interpolation.

• Stencil – Fixed-size interpolation stencil type.

Parameters:

stencil – Prepared stencil to reuse across fields.

Returns:

Interpolated field values in storage order.

template<class Stencil>
inline void evaluate_all_into(const Stencil &stencil, Stored *results) const

Evaluate all fields using a previously prepared interpolation stencil into caller-provided storage.

See also

evaluate_all(const Stencil&)

Template Parameters:

Stencil – Fixed-size interpolation stencil type.

Parameters:

• stencil – Prepared stencil to reuse across fields.

• results – Output buffer with space for field_count() values.

template<class Output, class Stencil>
inline void evaluate_all_into_as(const Stencil &stencil, Output *results) const

Evaluate all fields using a previously prepared interpolation stencil into caller-provided storage with caller-selected output precision.

See also

evaluate_all_into(const Stencil&, Stored*)

Template Parameters:

• Output – Floating-point type produced by interpolation.

• Stencil – Fixed-size interpolation stencil type.

Parameters:

• stencil – Prepared stencil to reuse across fields.

• results – Output buffer with space for field_count() values.

inline std::vector<Stored> evaluate_all_linear(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using multilinear interpolation.

See also

evaluate_all(const Stencil&)

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Interpolated field values in storage order.

template<class Output>
inline std::vector<Output> evaluate_all_linear_as(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using multilinear interpolation and caller-selected output precision.

See also

evaluate_all_linear(const std::array<double, Dim>&, bounds_policy)

Template Parameters:

Output – Floating-point type produced by interpolation.

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Interpolated field values in storage order.

inline void evaluate_all_linear_into(const std::array<double, Dim> &coordinates, Stored *results, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using multilinear interpolation into caller-provided storage.

See also

evaluate_all_into(const Stencil&, Stored*)

Parameters:

• coordinates – Query coordinates in grid axis order.

• results – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

template<class Output>
inline void evaluate_all_linear_into_as(const std::array<double, Dim> &coordinates, Output *results, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using multilinear interpolation into caller-provided storage with caller-selected output precision.

See also

evaluate_all_linear_into(const std::array<double, Dim>&, Stored*,

bounds_policy)

Template Parameters:

Output – Floating-point type produced by interpolation.

Parameters:

• coordinates – Query coordinates in grid axis order.

• results – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

inline std::vector<Stored> evaluate_all_cubic(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using local cubic interpolation.

Cubic interpolation uses four support points per axis and is therefore intended for experiments where the additional cost and possible overshoot are acceptable.

See also

Grid::prepare_cubic

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Cubically interpolated field values in storage order.

template<class Output>
inline std::vector<Output> evaluate_all_cubic_as(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using local cubic interpolation and caller-selected output precision.

See also

evaluate_all_cubic(const std::array<double, Dim>&, bounds_policy)

Template Parameters:

Output – Floating-point type produced by interpolation.

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Cubically interpolated field values in storage order.

inline void evaluate_all_cubic_into(const std::array<double, Dim> &coordinates, Stored *results, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using local cubic interpolation into caller-provided storage.

See also

evaluate_all_cubic

Parameters:

• coordinates – Query coordinates in grid axis order.

• results – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

template<class Output>
inline void evaluate_all_cubic_into_as(const std::array<double, Dim> &coordinates, Output *results, bounds_policy policy = bounds_policy::clamp) const

Evaluate all fields directly from query coordinates using local cubic interpolation into caller-provided storage with caller-selected output precision.

See also

evaluate_all_cubic_into(const std::array<double, Dim>&, Stored*,

bounds_policy)

Template Parameters:

Output – Floating-point type produced by interpolation.

Parameters:

• coordinates – Query coordinates in grid axis order.

• results – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

template<std::size_t Dim, class Output = double>
class RuntimeFieldGroup

Runtime-erased wrapper around a typed FieldGroup<Dim, Stored>.

The dimensionality remains part of the type. Only the stored scalar payload type is selected from file metadata at runtime.

Template Parameters:

• Dim – Grid dimensionality of the group.

• Output – Floating-point type produced by interpolation calls.

Public Functions

inline RuntimeFieldGroup()

Construct an empty runtime-erased group handle.

template<class Stored>
inline explicit RuntimeFieldGroup(const FieldGroup<Dim, Stored> &group)

Construct a runtime-erased wrapper from a typed field group.

See also

FieldGroup

Template Parameters:

Stored – Scalar payload type stored in the source group.

Parameters:

group – Typed field group to wrap.

inline bool empty() const

Check whether this wrapper currently holds a group instance.

Returns:

true if no group is loaded, otherwise false.

inline std::size_t field_count() const

Return the number of fields stored per grid point.

Returns:

Number of named fields in the wrapped group.

inline scalar_type value_type() const

Return the scalar payload type of the wrapped group.

Returns:

Runtime payload type tag.

inline std::vector<std::string> field_names() const

Return field names in storage order.

Returns:

Copy of the field name list.

inline std::array<Axis, Dim> axes() const

Return the axis descriptors of the wrapped grid.

Returns:

One axis descriptor per dimension.

inline std::size_t field_index(const std::string &field_name) const

Resolve a field name to its storage index.

Parameters:

field_name – Field name to look up.

Returns:

Zero-based field index in storage order.

inline std::vector<Output> evaluate_all_linear(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all stored fields at one coordinate tuple using multilinear interpolation.

See also

evaluate_all_linear_into

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Interpolated field values converted to Output.

inline void evaluate_all_linear_into(const std::array<double, Dim> &coordinates, Output *values, bounds_policy policy = bounds_policy::clamp) const

Evaluate all stored fields using multilinear interpolation into caller-provided output storage.

See also

evaluate_all_linear

Parameters:

• coordinates – Query coordinates in grid axis order.

• values – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

inline std::vector<Output> evaluate_all_cubic(const std::array<double, Dim> &coordinates, bounds_policy policy = bounds_policy::clamp) const

Evaluate all stored fields at one coordinate tuple using local cubic interpolation.

Cubic interpolation is an explicit opt-in because it uses 4^Dim table values and can overshoot.

See also

evaluate_all_cubic_into

Parameters:

• coordinates – Query coordinates in grid axis order.

• policy – Bounds handling behavior for out-of-domain coordinates.

Returns:

Cubically interpolated field values converted to Output.

inline void evaluate_all_cubic_into(const std::array<double, Dim> &coordinates, Output *values, bounds_policy policy = bounds_policy::clamp) const

Evaluate all stored fields using local cubic interpolation into caller-provided output storage.

See also

evaluate_all_cubic

Parameters:

• coordinates – Query coordinates in grid axis order.

• values – Output buffer with space for field_count() values.

• policy – Bounds handling behavior for out-of-domain coordinates.

inline void write(std::ostream &os) const

Write the wrapped group to an already opened binary stream.

See also

write_group_stream

Parameters:

os – Destination stream in binary mode.

struct GroupMetadata

Lightweight description of one serialized ndtbl field group.

This metadata is sufficient to inspect the file layout, reconstruct a typed grid, and validate payload sizes before reading values.

Public Members

scalar_type value_type

Scalar payload type stored in the file.

std::size_t dimension

Number of dimensions.

std::size_t field_count

Number of named fields stored per grid point.

std::size_t point_count

Total number of support points in the grid.

std::vector<Axis> axes

One axis descriptor per dimension.

std::vector<std::string> field_names

Field names in payload storage order.

std::uint8_t format_version = current_format_version

ndtbl binary file format version.

enum class ndtbl::axis_kind : std::uint8_t

Describes how one interpolation axis is represented.

Values:

enumerator uniform

Axis coordinates are generated from minimum, maximum, and size.

enumerator explicit_coordinates

Axis coordinates are stored explicitly in ascending order.

enum class ndtbl::scalar_type : std::uint8_t

Scalar payload type stored in a table file.

Values:

enumerator float32

IEEE-754 single-precision floating-point payload values.

enumerator float64

IEEE-754 double-precision floating-point payload values.

enum class ndtbl::bounds_policy : std::uint8_t

Controls how interpolation queries outside the grid domain behave.

Values:

enumerator clamp

Clamp out-of-domain interpolation queries to the table bounds.

enumerator throw_error

Reject out-of-domain interpolation queries with an exception.

inline GroupMetadata ndtbl::read_group_metadata(const std::string &path)

Read only the metadata header of an ndtbl file.

This function validates the file header and axis descriptors without reading the field payload.

See also

read_field_group

See also

read_runtime_field_group

Parameters:

path – Input file path.

Returns:

Parsed metadata describing the stored group.

template<std::size_t Dim, class Stored>
inline FieldGroup<Dim, Stored> ndtbl::read_field_group(const std::string &path)

Read an ndtbl file into a typed field group.

The file dimension and scalar payload type must match the compile-time Dim and Stored arguments.

See also

read_group_metadata

See also

FieldGroup

Template Parameters:

• Dim – Expected grid dimensionality of the file.

• Stored – Expected scalar payload type stored in the file.

Parameters:

path – Input file path.

Returns:

Typed field group with payload storage of type Stored.

template<std::size_t Dim, class Output = double>
inline RuntimeFieldGroup<Dim, Output> ndtbl::read_runtime_field_group(const std::string &path)

Read an ndtbl file into a runtime-erased field group.

The file dimension must match the compile-time Dim argument. The scalar payload type is selected from file metadata at runtime.

See also

read_field_group

See also

read_group_metadata

See also

RuntimeFieldGroup

Template Parameters:

• Dim – Expected grid dimensionality of the file.

• Output – Output type used by runtime-erased interpolation.

Parameters:

path – Input file path.

Returns:

Runtime-erased field group with either float or double payload storage and Output interpolation results.