interpn 0.2.4__cp313-cp313-win32.whl

interpn/__init__.py

@@ -0,0 +1,24 @@
+"""
+Python bindings to the `interpn` Rust library
+for N-dimensional interpolation and extrapolation.
+"""
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from .multilinear_regular import MultilinearRegular
+from .multilinear_rectilinear import MultilinearRectilinear
+from .multicubic_regular import MulticubicRegular
+from .multicubic_rectilinear import MulticubicRectilinear
+from interpn import raw
+
+__version__ = version("interpn")
+
+__all__ = [
+    "__version__",
+    "MultilinearRegular",
+    "MultilinearRectilinear",
+    "MulticubicRegular",
+    "MulticubicRectilinear",
+    "raw",
+]

interpn/multicubic_rectilinear.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+from typing import Optional
+from functools import reduce
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import (
+    model_validator,
+    ConfigDict,
+    BaseModel,
+)
+
+from .serialization import Array, ArrayF32, ArrayF64
+
+from ._interpn import (
+    interpn_cubic_rectilinear_f64,
+    interpn_cubic_rectilinear_f32,
+    check_bounds_rectilinear_f64,
+    check_bounds_rectilinear_f32,
+)
+
+
+class MulticubicRectilinear(BaseModel):
+    """
+    Multicubic interpolation on a rectilinear grid in up to 8 dimensions.
+
+    This method uses a symmetrized Hermite spline interpolant,
+    which provides a continuous value and first derivative.
+    Unlike a B-spline, the second derivative is not continuous;
+    however, also unlike a B-spline, the first derivatives are
+    maintained to more exactly match the data as estimated by
+    a central difference.
+
+    If `linearize_extrapolation` is set, dimensions on which extrapolation is occurring
+    (but not other dimensions) are extrapolated linearly from the last
+    two grid points on that dimension.
+
+    All array inputs must be of the same type, either np.float32 or np.float64
+    and must be 1D and contiguous and have size at least 4.
+    """
+
+    # Immutable after initialization checks
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    grids: list[Array]
+    vals: Array
+    linearize_extrapolation: bool
+
+    @classmethod
+    def new(cls, grids: list[NDArray], vals: NDArray, linearize_extrapolation: bool = False) -> MulticubicRectilinear:
+        """
+        Initialize interpolator and check types and dimensions, casting other arrays
+        to the same type as `vals` if they do not match, and flattening and/or
+        reallocating into contiguous storage if necessary.
+
+        This method exists primarily to remove boilerplate introduced by
+        mixing pydantic and numpy.
+
+        Args:
+            grids: 1D arrays of grid coordinate values.
+                   All grids must be monotonically increasing.
+            vals: Values at grid points in C-style ordering,
+                  as obtained from np.meshgrid(..., indexing="ij")
+            linearize_extrapolation: Whether to fall back to a linear
+                interpolant outside the grid
+
+        Returns:
+            A new MultilinearRectilinear interpolator instance.
+        """
+        dtype = vals.dtype
+        arrtype = ArrayF64 if dtype == np.float64 else ArrayF32
+        interpolator = MulticubicRectilinear(
+            grids=[arrtype(data=x) for x in grids],
+            vals=arrtype(data=vals.flatten()),
+            linearize_extrapolation=linearize_extrapolation,
+        )
+
+        return interpolator
+
+    @model_validator(mode="after")
+    def _validate_model(self):
+        """Check that all inputs are contiguous and of the same data type,
+        and that the grid dimensions and values make sense."""
+        dims = self.dims()
+        ndims = self.ndims()
+        assert (
+            ndims <= 8 and ndims >= 1
+        ), "Number of dimensions must be at least 1 and no more than 8"
+        assert self.vals.data.size == reduce(
+            lambda acc, x: acc * x, dims
+        ), "Size of value array does not match grid dims"
+        assert all(
+            [np.all(np.diff(x.data) > 0.0) for x in self.grids]
+        ), "All grids must be monotonically increasing"
+        assert all(
+            [x.data.dtype == self.vals.data.dtype for x in self.grids]
+        ), "All grid inputs must be of the same data type (np.float32 or np.float64)"
+        assert (
+            all([x.data.data.contiguous for x in self.grids])
+            and self.vals.data.data.contiguous
+        ), "Grid data must be contiguous"
+
+        return self
+
+    def ndims(self) -> int:
+        return len(self.grids)
+
+    def dims(self) -> list[int]:
+        return [x.data.size for x in self.grids]
+
+    def eval(self, obs: list[NDArray], out: Optional[NDArray] = None) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array.
+
+        This function does not reallocate inputs, and will error if the
+        inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+            AssertionError: If input data is not contiguous or dimensions do not match
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        # Allocate output if it was not provided,
+        # then check data type and contiguousness
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+        self.eval_unchecked(obs, out_inner)
+
+        return out_inner
+
+    def eval_unchecked(
+        self, obs: list[NDArray], out: Optional[NDArray] = None
+    ) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array,
+        and skipping checks on the dimensionality and contiguousness
+        of the inputs.
+
+        This function does not reallocate inputs, and will error in a lower-level
+        function if the inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        dtype = self.vals.data.dtype
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+
+        if dtype == np.float64:
+            interpn_cubic_rectilinear_f64(
+                [x.data for x in self.grids],
+                self.vals.data,
+                self.linearize_extrapolation,
+                obs,
+                out_inner,
+            )
+        elif dtype == np.float32:
+            interpn_cubic_rectilinear_f32(
+                [x.data for x in self.grids],
+                self.vals.data,
+                self.linearize_extrapolation,
+                obs,
+                out_inner,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out_inner
+
+    def check_bounds(self, obs: list[NDArray], atol: float) -> NDArray[np.bool_]:
+        """
+        Check if the observation points violated the bounds on each dimension.
+
+        This performs a (small) allocation for the output.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            atol: Absolute tolerance on bounds.
+
+        Raises:
+            TypeError: If an unexpected data type is encountered
+
+        Returns:
+            An array of flags for each dimension, each True if that dimension's
+            bounds were violated.
+        """
+        ndims = self.ndims()
+        out = np.array([False] * ndims)
+
+        dtype = self.vals.data.dtype
+        if dtype == np.float64:
+            check_bounds_rectilinear_f64(
+                [x.data for x in self.grids],
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        elif dtype == np.float32:
+            check_bounds_rectilinear_f32(
+                [x.data for x in self.grids],
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out

interpn/multicubic_regular.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from typing import Optional
+from functools import reduce
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import (
+    model_validator,
+    ConfigDict,
+    BaseModel,
+)
+
+from .serialization import Array, ArrayF32, ArrayF64
+
+from ._interpn import (
+    interpn_cubic_regular_f64,
+    interpn_cubic_regular_f32,
+    check_bounds_regular_f64,
+    check_bounds_regular_f32,
+)
+
+
+class MulticubicRegular(BaseModel):
+    """
+    Multicubic interpolation on a regular grid in up to 8 dimensions.
+
+    This method uses a symmetrized Hermite spline interpolant,
+    which provides a continuous value and first derivative.
+    Unlike a B-spline, the second derivative is not continuous;
+    however, also unlike a B-spline, the first derivatives are
+    maintained to more exactly match the data as estimated by
+    a central difference.
+
+    If `linearize_extrapolation` is set, dimensions on which extrapolation is occurring
+    (but not other dimensions) are extrapolated linearly from the last
+    two grid points on that dimension.
+
+    All array inputs must be of the same type, either np.float32 or np.float64
+    and must be 1D and contiguous and have size at least 4.
+    """
+
+    # Immutable after initialization checks
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    dims: list[int]
+    starts: Array
+    steps: Array
+    vals: Array
+    linearize_extrapolation: bool
+
+    @classmethod
+    def new(
+        cls, dims: list[int], starts: NDArray, steps: NDArray, vals: NDArray, linearize_extrapolation: bool = False
+    ) -> MulticubicRegular:
+        """
+        Initialize interpolator and check types and dimensions, casting other arrays
+        to the same type as `vals` if they do not match, and flattening and/or
+        reallocating into contiguous storage if necessary.
+
+        This method exists primarily to remove boilerplate introduced by
+        mixing pydantic and numpy.
+
+        Args:
+            dims: Number of elements on each dimension of the grid
+            starts: Starting point of each dimension of the grid
+            steps: Step size on each dimension of the grid
+            vals: Values at grid points in C-style ordering,
+                  as obtained from np.meshgrid(..., indexing="ij")
+            linearize_extrapolation: Whether to fall back to a linear
+                interpolant outside the grid
+
+        Returns:
+            A new MulticubicRegular interpolator instance.
+        """
+        dtype = vals.dtype
+        arrtype = ArrayF64 if dtype == np.float64 else ArrayF32
+        interpolator = MulticubicRegular(
+            dims=dims,
+            starts=arrtype(data=starts.flatten()),
+            steps=arrtype(data=steps.flatten()),
+            vals=arrtype(data=vals.flatten()),
+            linearize_extrapolation=linearize_extrapolation,
+        )
+
+        return interpolator
+
+    @model_validator(mode="after")
+    def _validate_model(self):
+        """Check that all inputs are contiguous and of the same data type,
+        and that the grid dimensions and values make sense."""
+        ndims = self.ndims()
+        assert (
+            ndims <= 8 and ndims >= 1
+        ), "Number of dimensions must be at least 1 and no more than 8"
+        assert self.starts.data.size == ndims, "Grid dimension mismatch"
+        assert self.steps.data.size == ndims, "Grid dimension mismatch"
+        assert self.vals.data.size == reduce(
+            lambda acc, x: acc * x, self.dims
+        ), "Size of value array does not match grid dims"
+        assert all(
+            [x > 0.0 for x in self.steps.data]
+        ), "All grid steps must be positive and nonzero"
+        assert all(
+            [x.data.dtype == self.vals.data.dtype for x in [self.steps, self.vals]]
+        ), "All grid inputs must be of the same data type (np.float32 or np.float64)"
+        assert all(
+            [x.data.data.contiguous for x in [self.starts, self.steps, self.vals]]
+        ), "Grid data must be contiguous"
+
+        return self
+
+    def ndims(self) -> int:
+        return len(self.dims)
+
+    def eval(self, obs: list[NDArray], out: Optional[NDArray] = None) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array.
+
+        This function does not reallocate inputs, and will error if the
+        inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+            AssertionError: If input data is not contiguous or dimensions do not match
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        # Allocate output if it was not provided
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+        self.eval_unchecked(obs, out_inner)
+
+        return out_inner
+
+    def eval_unchecked(
+        self, obs: list[NDArray], out: Optional[NDArray] = None
+    ) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array,
+        and skipping checks on the dimensionality and contiguousness
+        of the inputs.
+
+        This function does not reallocate inputs, and will error in a lower-level
+        function if the inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        dtype = self.vals.data.dtype
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+
+        if dtype == np.float64:
+            interpn_cubic_regular_f64(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                self.vals.data,
+                self.linearize_extrapolation,
+                obs,
+                out_inner,
+            )
+        elif dtype == np.float32:
+            interpn_cubic_regular_f32(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                self.vals.data,
+                self.linearize_extrapolation,
+                obs,
+                out_inner,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out_inner
+
+    def check_bounds(self, obs: list[NDArray], atol: float) -> NDArray[np.bool_]:
+        """
+        Check if the observation points violated the bounds on each dimension.
+
+        This performs a (small) allocation for the output.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            atol: Absolute tolerance on bounds.
+
+        Raises:
+            TypeError: If an unexpected data type is encountered
+
+        Returns:
+            An array of flags for each dimension, each True if that dimension's
+            bounds were violated.
+        """
+        ndims = self.ndims()
+        out = np.array([False] * ndims)
+
+        dtype = self.vals.data.dtype
+        if dtype == np.float64:
+            check_bounds_regular_f64(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        elif dtype == np.float32:
+            check_bounds_regular_f32(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out

interpn/multilinear_rectilinear.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from typing import Optional
+from functools import reduce
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import (
+    model_validator,
+    ConfigDict,
+    BaseModel,
+)
+
+from .serialization import Array, ArrayF32, ArrayF64
+
+from ._interpn import (
+    interpn_linear_rectilinear_f64,
+    interpn_linear_rectilinear_f32,
+    check_bounds_rectilinear_f64,
+    check_bounds_rectilinear_f32,
+)
+
+
+class MultilinearRectilinear(BaseModel):
+    """
+    Multilinear interpolation on a rectilinear grid in up to 8 dimensions.
+
+    All array inputs must be of the same type, either np.float32 or np.float64
+    and must be 1D and contiguous.
+    """
+
+    # Immutable after initialization checks
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    grids: list[Array]
+    vals: Array
+
+    @classmethod
+    def new(cls, grids: list[NDArray], vals: NDArray) -> MultilinearRectilinear:
+        """
+        Initialize interpolator and check types and dimensions, casting other arrays
+        to the same type as `vals` if they do not match, and flattening and/or
+        reallocating into contiguous storage if necessary.
+
+        This method exists primarily to remove boilerplate introduced by
+        mixing pydantic and numpy.
+
+        Args:
+            grids: 1D arrays of grid coordinate values.
+                   All grids must be monotonically increasing.
+            vals: Values at grid points in C-style ordering,
+                  as obtained from np.meshgrid(..., indexing="ij")
+
+        Returns:
+            A new MultilinearRectilinear interpolator instance.
+        """
+        dtype = vals.dtype
+        arrtype = ArrayF64 if dtype == np.float64 else ArrayF32
+        interpolator = MultilinearRectilinear(
+            grids=[arrtype(data=x) for x in grids],
+            vals=arrtype(data=vals.flatten()),
+        )
+
+        return interpolator
+
+    @model_validator(mode="after")
+    def _validate_model(self):
+        """Check that all inputs are contiguous and of the same data type,
+        and that the grid dimensions and values make sense."""
+        dims = self.dims()
+        ndims = self.ndims()
+        assert (
+            ndims <= 8 and ndims >= 1
+        ), "Number of dimensions must be at least 1 and no more than 8"
+        assert self.vals.data.size == reduce(
+            lambda acc, x: acc * x, dims
+        ), "Size of value array does not match grid dims"
+        assert all(
+            [np.all(np.diff(x.data) > 0.0) for x in self.grids]
+        ), "All grids must be monotonically increasing"
+        assert all(
+            [x.data.dtype == self.vals.data.dtype for x in self.grids]
+        ), "All grid inputs must be of the same data type (np.float32 or np.float64)"
+        assert (
+            all([x.data.data.contiguous for x in self.grids])
+            and self.vals.data.data.contiguous
+        ), "Grid data must be contiguous"
+
+        return self
+
+    def ndims(self) -> int:
+        return len(self.grids)
+
+    def dims(self) -> list[int]:
+        return [x.data.size for x in self.grids]
+
+    def eval(self, obs: list[NDArray], out: Optional[NDArray] = None) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array.
+
+        This function does not reallocate inputs, and will error if the
+        inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+            AssertionError: If input data is not contiguous or dimensions do not match
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        # Allocate output if it was not provided,
+        # then check data type and contiguousness
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+        self.eval_unchecked(obs, out_inner)
+
+        return out_inner
+
+    def eval_unchecked(
+        self, obs: list[NDArray], out: Optional[NDArray] = None
+    ) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array,
+        and skipping checks on the dimensionality and contiguousness
+        of the inputs.
+
+        This function does not reallocate inputs, and will error in a lower-level
+        function if the inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        dtype = self.vals.data.dtype
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+
+        if dtype == np.float64:
+            interpn_linear_rectilinear_f64(
+                [x.data for x in self.grids],
+                self.vals.data,
+                obs,
+                out_inner,
+            )
+        elif dtype == np.float32:
+            interpn_linear_rectilinear_f32(
+                [x.data for x in self.grids],
+                self.vals.data,
+                obs,
+                out_inner,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out_inner
+
+    def check_bounds(self, obs: list[NDArray], atol: float) -> NDArray[np.bool_]:
+        """
+        Check if the observation points violated the bounds on each dimension.
+
+        This performs a (small) allocation for the output.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            atol: Absolute tolerance on bounds.
+
+        Raises:
+            TypeError: If an unexpected data type is encountered
+
+        Returns:
+            An array of flags for each dimension, each True if that dimension's
+            bounds were violated.
+        """
+        ndims = self.ndims()
+        out = np.array([False] * ndims)
+
+        dtype = self.vals.data.dtype
+        if dtype == np.float64:
+            check_bounds_rectilinear_f64(
+                [x.data for x in self.grids],
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        elif dtype == np.float32:
+            check_bounds_rectilinear_f32(
+                [x.data for x in self.grids],
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out

interpn/multilinear_regular.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from typing import Optional
+from functools import reduce
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import (
+    model_validator,
+    ConfigDict,
+    BaseModel,
+)
+
+from .serialization import Array, ArrayF32, ArrayF64
+
+from ._interpn import (
+    interpn_linear_regular_f64,
+    interpn_linear_regular_f32,
+    check_bounds_regular_f64,
+    check_bounds_regular_f32,
+)
+
+
+class MultilinearRegular(BaseModel):
+    """
+    Multilinear interpolation on a regular grid in up to 8 dimensions.
+
+    All array inputs must be of the same type, either np.float32 or np.float64
+    and must be 1D and contiguous.
+    """
+
+    # Immutable after initialization checks
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    dims: list[int]
+    starts: Array
+    steps: Array
+    vals: Array
+
+    @classmethod
+    def new(
+        cls, dims: list[int], starts: NDArray, steps: NDArray, vals: NDArray
+    ) -> MultilinearRegular:
+        """
+        Initialize interpolator and check types and dimensions, casting other arrays
+        to the same type as `vals` if they do not match, and flattening and/or
+        reallocating into contiguous storage if necessary.
+
+        This method exists primarily to remove boilerplate introduced by
+        mixing pydantic and numpy.
+
+        Args:
+            dims: Number of elements on each dimension of the grid
+            starts: Starting point of each dimension of the grid
+            steps: Step size on each dimension of the grid
+            vals: Values at grid points in C-style ordering,
+                  as obtained from np.meshgrid(..., indexing="ij")
+
+        Returns:
+            A new MultilinearRegular interpolator instance.
+        """
+        dtype = vals.dtype
+        arrtype = ArrayF64 if dtype == np.float64 else ArrayF32
+        interpolator = MultilinearRegular(
+            dims=dims,
+            starts=arrtype(data=starts.flatten()),
+            steps=arrtype(data=steps.flatten()),
+            vals=arrtype(data=vals.flatten()),
+        )
+
+        return interpolator
+
+    @model_validator(mode="after")
+    def _validate_model(self):
+        """Check that all inputs are contiguous and of the same data type,
+        and that the grid dimensions and values make sense."""
+        ndims = self.ndims()
+        assert (
+            ndims <= 8 and ndims >= 1
+        ), "Number of dimensions must be at least 1 and no more than 8"
+        assert self.starts.data.size == ndims, "Grid dimension mismatch"
+        assert self.steps.data.size == ndims, "Grid dimension mismatch"
+        assert self.vals.data.size == reduce(
+            lambda acc, x: acc * x, self.dims
+        ), "Size of value array does not match grid dims"
+        assert all(
+            [x > 0.0 for x in self.steps.data]
+        ), "All grid steps must be positive and nonzero"
+        assert all(
+            [x.data.dtype == self.vals.data.dtype for x in [self.steps, self.vals]]
+        ), "All grid inputs must be of the same data type (np.float32 or np.float64)"
+        assert all(
+            [x.data.data.contiguous for x in [self.starts, self.steps, self.vals]]
+        ), "Grid data must be contiguous"
+
+        return self
+
+    def ndims(self) -> int:
+        return len(self.dims)
+
+    def eval(self, obs: list[NDArray], out: Optional[NDArray] = None) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array.
+
+        This function does not reallocate inputs, and will error if the
+        inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+            AssertionError: If input data is not contiguous or dimensions do not match
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        # Allocate output if it was not provided
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+        self.eval_unchecked(obs, out_inner)
+
+        return out_inner
+
+    def eval_unchecked(
+        self, obs: list[NDArray], out: Optional[NDArray] = None
+    ) -> NDArray:
+        """Evaluate the interpolator at a set of observation points,
+        optionally writing the output into a preallocated array,
+        and skipping checks on the dimensionality and contiguousness
+        of the inputs.
+
+        This function does not reallocate inputs, and will error in a lower-level
+        function if the inputs are not contiguous or are of the wrong data type.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            out: Optional preallocated array for output. Defaults to None.
+
+        Raises:
+            TypeError: If data type is not np.float32 or np.float64
+
+        Returns:
+            Array of evaluated values in the same shape and data type as obs[0]
+        """
+        dtype = self.vals.data.dtype
+        out_inner = out if out is not None else np.zeros_like(obs[0])
+
+        if dtype == np.float64:
+            interpn_linear_regular_f64(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                self.vals.data,
+                obs,
+                out_inner,
+            )
+        elif dtype == np.float32:
+            interpn_linear_regular_f32(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                self.vals.data,
+                obs,
+                out_inner,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out_inner
+
+    def check_bounds(self, obs: list[NDArray], atol: float) -> NDArray[np.bool_]:
+        """
+        Check if the observation points violated the bounds on each dimension.
+
+        This performs a (small) allocation for the output.
+
+        Args:
+            obs: [x, y, ...] coordinates of observation points.
+            atol: Absolute tolerance on bounds.
+
+        Raises:
+            TypeError: If an unexpected data type is encountered
+
+        Returns:
+            An array of flags for each dimension, each True if that dimension's
+            bounds were violated.
+        """
+        ndims = self.ndims()
+        out = np.array([False] * ndims)
+
+        dtype = self.vals.data.dtype
+        if dtype == np.float64:
+            check_bounds_regular_f64(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        elif dtype == np.float32:
+            check_bounds_regular_f32(
+                self.dims,
+                self.starts.data,
+                self.steps.data,
+                [x.flatten() for x in obs],
+                atol,
+                out,
+            )
+        else:
+            raise TypeError(f"Unexpected data type: {dtype}")
+
+        return out

interpn/raw.py

@@ -0,0 +1,34 @@
+"""
+Re-exported raw PyO3/Maturin bindings to Rust functions.
+Using these can yield some performance benefit at the expense of ergonomics.
+"""
+
+from ._interpn import (
+    interpn_linear_regular_f64,
+    interpn_linear_regular_f32,
+    interpn_linear_rectilinear_f64,
+    interpn_linear_rectilinear_f32,
+    interpn_cubic_regular_f64,
+    interpn_cubic_regular_f32,
+    interpn_cubic_rectilinear_f64,
+    interpn_cubic_rectilinear_f32,
+    check_bounds_regular_f64,
+    check_bounds_regular_f32,
+    check_bounds_rectilinear_f64,
+    check_bounds_rectilinear_f32,
+)
+
+__all__ = [
+    "interpn_linear_regular_f64",
+    "interpn_linear_regular_f32",
+    "interpn_linear_rectilinear_f64",
+    "interpn_linear_rectilinear_f32",
+    "interpn_cubic_regular_f64",
+    "interpn_cubic_regular_f32",
+    "interpn_cubic_rectilinear_f64",
+    "interpn_cubic_rectilinear_f32",
+    "check_bounds_regular_f64",
+    "check_bounds_regular_f32",
+    "check_bounds_rectilinear_f64",
+    "check_bounds_rectilinear_f32",
+]

interpn/serialization.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from typing import Union, Annotated, Literal, Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import (
+    field_validator,
+    field_serializer,
+    ConfigDict,
+    BaseModel,
+    Field,
+)
+
+
+class ArrayF64(BaseModel):
+    """
+    Serializable wrapper for NDArray[float64].
+    """
+    data: NDArray[np.float64]
+    dtype: Literal["float64"] = "float64"
+
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    @field_validator("data", mode="before")
+    def _validate_x(data: Any) -> NDArray[np.float64]:
+        if isinstance(data, str):
+            y = np.ascontiguousarray(np.array(json.loads(data), dtype=np.float64))
+        elif isinstance(data, np.ndarray):
+            y = np.ascontiguousarray(data.astype(np.float64))
+        elif isinstance(data, list):
+            y = np.array(data, dtype=np.float64)
+        else:
+            raise TypeError
+
+        return y
+
+    @field_serializer("data", return_type=str)
+    def _serialize_x(data: Any) -> str:
+        return json.dumps(data.tolist())
+
+
+class ArrayF32(BaseModel):
+    """
+    Serializable wrapper for NDArray[float32].
+    
+    The data is represented as a list of float64 on disk and in RAM 
+    during serialization and deserialization.
+    """
+    data: NDArray[np.float32]
+    dtype: Literal["float32"] = "float32"
+
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    @field_validator("data", mode="before")
+    def _validate_x(data: Any) -> NDArray[np.float32]:
+        if isinstance(data, str):
+            y = np.ascontiguousarray(np.array(json.loads(data), dtype=np.float32))
+        elif isinstance(data, np.ndarray):
+            y = np.ascontiguousarray(data.astype(np.float32))
+        elif isinstance(data, list):
+            y = np.array(data, dtype=np.float32)
+        else:
+            raise TypeError
+
+        return y
+
+    @field_serializer("data", return_type=str)
+    def _serialize_x(data: Any) -> str:
+        return json.dumps(data.tolist())
+
+
+Array = Annotated[Union[ArrayF32, ArrayF64], Field(discriminator="dtype")]

interpn-0.2.4.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: interpn
+Version: 0.2.4
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Dist: numpy>=2
+Requires-Dist: pydantic>=2.5.2
+Requires-Dist: pytest>=8.0 ; extra == 'test'
+Requires-Dist: coverage>=7.3.2 ; extra == 'test'
+Requires-Dist: ruff>=0.4.10 ; extra == 'test'
+Requires-Dist: pyright==1.1.337 ; extra == 'test'
+Requires-Dist: mktestdocs>=0.2.1 ; extra == 'test'
+Requires-Dist: scipy>=1.11.4 ; extra == 'test'
+Requires-Dist: matplotlib>=3.8 ; extra == 'test'
+Requires-Dist: scipy>=1.11.4 ; extra == 'bench'
+Requires-Dist: matplotlib>=3.8 ; extra == 'bench'
+Requires-Dist: memory-profiler>=0.61.0 ; extra == 'bench'
+Requires-Dist: mkdocs>=1.5.3 ; extra == 'doc'
+Requires-Dist: mkdocstrings-python>=1.7.5 ; extra == 'doc'
+Requires-Dist: mkdocs-material>=9.4.10 ; extra == 'doc'
+Provides-Extra: test
+Provides-Extra: bench
+Provides-Extra: doc
+License-File: LICENSE-APACHE
+License-File: LICENSE-MIT
+Summary: N-dimensional interpolation/extrapolation methods
+Author-email: James Logan <jlogan03@gmail.com>
+Requires-Python: >=3.9, <3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# interpn
+
+Python bindings to the `interpn` Rust library for N-dimensional interpolation and extrapolation. 
+
+[Docs](https://interpnpy.readthedocs.io/en/latest/) |
+[Repo](https://github.com/jlogan03/interpnpy) |
+[Rust Library (github)](https://github.com/jlogan03/interpn) | 
+[Rust Docs (docs.rs)](https://docs.rs/interpn/latest/interpn/)
+
+## Features
+
+| Feature →<br>↓ Interpolant Method | Regular<br>Grid | Rectilinear<br>Grid | Json<br>Serialization |
+|-----------------------------------|-----------------|---------------------|-----------------------|
+| Linear                            |   ✅            |     ✅              | ✅                    |
+| Cubic                             |   ✅            |     ✅              | ✅                    |
+
+The methods provided here, while more limited in scope than scipy's, are
+
+* significantly faster for higher dimensions (1-3 orders of magnitude under most conditions)
+* use almost no RAM (and perform no heap allocations at all)
+* produce significantly improved floating-point error (by 1-2 orders of magnitude)
+* are json-serializable using Pydantic
+* can also be used easily in web and embedded applications via the Rust library
+* are permissively licensed
+
+![ND throughput 1 obs](./docs/throughput_vs_dims_1_obs.svg)
+
+See [here](https://interpnpy.readthedocs.io/en/latest/perf/) for more info about quality-of-fit, throughput, and memory usage.
+
+## Installation
+
+```bash
+pip install interpn
+```
+
+## Example: Available Methods
+
+```python
+import interpn
+import numpy as np
+
+# Build grid
+x = np.linspace(0.0, 10.0, 5)
+y = np.linspace(20.0, 30.0, 4)
+grids = [x, y]
+
+xgrid, ygrid = np.meshgrid(x, y, indexing="ij")
+zgrid = (xgrid + 2.0 * ygrid)  # Values at grid points
+
+# Grid inputs for true regular grid
+dims = [x.size, y.size]
+starts = np.array([x[0], y[0]])
+steps = np.array([x[1] - x[0], y[1] - y[0]])
+
+# Initialize different interpolators
+# Call like `linear_regular.eval([xs, ys])`
+linear_regular = interpn.MultilinearRegular.new(dims, starts, steps, zgrid)
+cubic_regular = interpn.MulticubicRegular.new(dims, starts, steps, zgrid)
+linear_rectilinear = interpn.MultilinearRectilinear.new(grids, zgrid)
+cubic_rectilinear = interpn.MulticubicRectilinear.new(grids, zgrid)
+```
+
+## Example: Multilinear Interpolation on a Regular Grid
+
+```python
+import interpn
+import numpy as np
+
+# Build grid
+x = np.linspace(0.0, 10.0, 5)
+y = np.linspace(20.0, 30.0, 4)
+
+xgrid, ygrid = np.meshgrid(x, y, indexing="ij")
+zgrid = (xgrid + 2.0 * ygrid)  # Values at grid points
+
+# Grid inputs for true regular grid
+dims = [x.size, y.size]
+starts = np.array([x[0], y[0]])
+steps = np.array([x[1] - x[0], y[1] - y[0]])
+
+# Observation points pointed back at the grid
+obs = [xgrid.flatten(), ygrid.flatten()]
+
+# Initialize
+interpolator = interpn.MultilinearRegular.new(dims, starts, steps, zgrid.flatten())
+
+# Interpolate
+out = interpolator.eval(obs)
+
+# Check result
+assert np.allclose(out, zgrid.flatten(), rtol=1e-13)
+
+# Serialize and deserialize
+roundtrip_interpolator = interpn.MultilinearRegular.model_validate_json(
+    interpolator.model_dump_json()
+)
+out2 = roundtrip_interpolator.eval(obs)
+
+# Check result from roundtrip serialized/deserialized interpolator
+assert np.all(out == out2)
+```
+
+
+# License
+
+Licensed under either of
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+

interpn-0.2.4.dist-info/RECORD

@@ -0,0 +1,14 @@
+interpn-0.2.4.dist-info/METADATA,sha256=YNhUnyy5sFfpDfKCCiqx1coCRnt3i84b7Cfso6UeicE,4873
+interpn-0.2.4.dist-info/WHEEL,sha256=eh90R9THiv1HYPhYUCnpm_RAErMfEQKvZWVMxF3uaCM,92
+interpn-0.2.4.dist-info/licenses/LICENSE-APACHE,sha256=vnG2Zpa4ndnPKQhtz4GzjlNyndoyC6HGzYQxqZiloiA,566
+interpn-0.2.4.dist-info/licenses/LICENSE-MIT,sha256=00q7nfKf9L7lT7vXsRm0qTY6L4vT1Fu_q1nGsNlBNLQ,1080
+interpn/multicubic_rectilinear.py,sha256=AYeaidxiY2J-9VofxuRH1FQIpA9XuC703mBNPywFDdE,7997
+interpn/multicubic_regular.py,sha256=FDKWrVTv9pAQCw_DuyQAqWiK1_SXdduiHwdpNRS3ZWI,8326
+interpn/multilinear_rectilinear.py,sha256=BWDY7xH3wxPCrJS2pY7tGvNdTNr63pzLNlyWleUVJS8,7084
+interpn/multilinear_regular.py,sha256=jOsmLAingzmzFh6m5PduST9me6__gjIwCo2ODtCaiOM,7414
+interpn/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+interpn/raw.py,sha256=MhBso4GbnqCmBAyy3E3lGfhwiLhiHSeKGaStWXuFbIo,1034
+interpn/serialization.py,sha256=COnpGVuxstxmKkSMQTvFQ58q1TKYYdMttJKzg9iErOk,2236
+interpn/__init__.py,sha256=Re2WbLtsFqhhmpWszu4AzA_8M5WgpHZFzYDfNXQ-VGI,638
+interpn/_interpn.cp313-win32.pyd,sha256=h2949rnu9NWKFtOm9Yco2gsKjOiV0uINS_fkH4oFZGU,475136
+interpn-0.2.4.dist-info/RECORD,,

interpn-0.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win32

interpn-0.2.4.dist-info/licenses/LICENSE-APACHE

@@ -0,0 +1,13 @@
+Copyright (c) 2023 James Logan
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

interpn-0.2.4.dist-info/licenses/LICENSE-MIT

@@ -0,0 +1,25 @@
+Copyright (c) 2024 James Logan
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.