derivkit.derivatives.tabulated_model.one_d module#

Interpolation utilities for 1D tabulated functions.

Provides a lightweight wrapper around numpy.interp for interpolating tabulated y(x) data, supporting scalar as well as vector- and tensor-valued outputs.

Two common entry points are:

  • Direct construction with (x, y) arrays of shape (N,) and (N, ...).

  • derivkit.tabulated_model.one_d.tabulated1d_from_table() for simple 2D tables containing x and one or more y components in columns.

class derivkit.derivatives.tabulated_model.one_d.Tabulated1DModel(x: ArrayLike, y: ArrayLike, *, extrapolate: bool = False, fill_value: float | None = None)#

Bases: object

1D interpolator for tabulated data.

Interpolates a tabulated function y(x) using numpy.interp.

Here x is a one-dimensional grid of length N, and the first dimension of y must also have length N. All remaining dimensions of y are treated as the output shape.

For example:

  • x has shape (N,) and y has shape (N,) -> scalar output

  • x has shape (N,) and y has shape (N, M) -> vector output of length M

  • x has shape (N,) and y has shape (N, d1, d2) -> tensor output with shape (d1, d2)

This class handles interpolation for functions of a single scalar input x. Support for tabulated functions with multi-dimensional inputs would require a different interface and can be added in a future extension.

x#

Tabulated x grid, strictly increasing.

y_flat#

Flattened tabulated values with shape (N, n_out_flat).

_out_shape#

Original trailing output shape of y.

extrapolate#

Whether evaluation outside the tabulated x range is allowed.

fill_value#

Value used for out-of-range evaluation when extrapolation is off.

Example

>>> import numpy as np
>>> from derivkit.derivatives.tabulated_model.one_d import Tabulated1DModel
>>>
>>> x_tab = np.array([0.0, 1.0, 2.0, 3.0])
>>> y_tab = np.array([[0.0, 0.0],
...                   [1.0, 1.0],
...                   [4.0, 8.0],
...                   [9.0, 27.0]])  # shape (4, 2)
>>> # Create model with extrapolation disabled and fill_value = -1.0
>>> model = Tabulated1DModel(x_tab, y_tab,
...                          extrapolate=False, fill_value=-1.0)
>>> # Evaluate at new points
>>> x_new = np.array([-1.0, 0.5, 1.5, 2.5, 4.0])
>>> y_new = model(x_new)
>>> expected = np.array([
...     [-1.0, -1.0],
...     [0.5, 0.5],
...     [2.5, 4.5],
...     [6.5, 17.5],
...     [-1.0, -1.0],
... ])
>>> np.allclose(y_new, expected)
True

Initializes a tabulated 1D interpolation model.

Parameters:

  • x – Strictly increasing tabulated x values with shape (N,).

  • y – Tabulated y values with shape (N,) (scalar) or (N, ...) (vector/tensor). The first dimension must match x.

  • extrapolate – Whether to allow evaluation outside the x range. Default is False.

  • fill_value – Value for out-of-bounds evaluation when extrapolation is disabled. If None, a ValueError is raised instead.

derivkit.derivatives.tabulated_model.one_d.tabulated1d_from_table(table: ArrayLike, *, extrapolate: bool = False, fill_value: float | None = None) → Tabulated1DModel#

Creates a Tabulated1DModel from a simple 2D (x, y) table.

This helper covers the common case where data are stored in a 2D array or text file with x in one column and one or more y components in the remaining columns.

Supported layouts:

  • (N, 2): column 0 = x, column 1 = scalar y.

  • (N, M+1): column 0 = x, columns 1..M = components of y.

  • (2, N): row 0 = x, row 1 = scalar y.

For multi-component tables, the resulting y has shape (N, M). Higher-rank outputs (for example matrices or tensors associated with each x) are not encoded via this table format. Such data must be loaded and reshaped prior to constructing a derivkit.tabulated_model.one_d.Tabulated1DModel directly from (x, y).

Parameters:

  • table – 2D array containing x and y columns.

  • extrapolate – Whether to allow evaluation outside the tabulated x range. If False (default), any x outside [x.min(), x.max()] either raises a ValueError (when fill_value is None) or is set to fill_value. If True, out-of-range x are handled using numpy.interp’s standard edge behaviour.

  • fill_value – Value for out-of-range evaluation when extrapolation is disabled.

Returns:

A derivkit.tabulated_model.one_d.Tabulated1DModel constructed from the parsed table.