Enum Interpolator

pub enum Interpolator {
    Interp0D(f64),
    Interp1D(Interp1D),
    Interp2D(Interp2D),
    Interp3D(Interp3D),
    InterpND(InterpND),
}

An interpolator, with different functionality depending on variant.

Interpolation is executed by calling Interpolator::interpolate. The length of the supplied point slice must be equal to the intepolator dimensionality. The interpolator dimensionality can be retrieved by calling Interpolator::ndim.

Note

For interpolators of dimensionality N ≥ 1:

• By design, instantiation must be done via the Interpolator enum’s new_* methods (new_1d, new_2d, new_3d, new_nd). These run a validation step that catches any potential errors early.
  • To set or get field values, use the corresponding named methods (x, set_x, etc.).
• An interpolation Strategy (e.g. linear, left-nearest, etc.) must be specified. Not all interpolation strategies are implemented for every dimensionality. Strategy::Linear is implemented for all dimensionalities.
• An Extrapolate setting must be specified. This controls what happens when a point is beyond the range of supplied coordinates. If you are unsure which variant to choose, Extrapolate::Error is likely what you want.

For 0D (constant-value) interpolators, instantiate directly, e.g. Interpolator::Interp0D(0.5)

Variants

Interp0D(f64)

Useful for returning a constant-value result from an interpolator.

Example:

use ninterp::*;
// 0-D is unique, the value is directly provided in the variant
let const_value = 0.5;
let interp = Interpolator::Interp0D(const_value);
assert_eq!(
    interp.interpolate(&[]).unwrap(), // an empty point is required for 0-D
    const_value
);

Interp1D(Interp1D)

Interpolates in one dimension.

Applicable interpolation strategies:

• Strategy::Linear
• Strategy::LeftNearest
• Strategy::RightNearest
• Strategy::Nearest

Applicable extrapolation strategies:

• Extrapolate::Enable
• Extrapolate::Clamp
• Extrapolate::Error

Example (linear, using Extrapolate::Enable):

use ninterp::prelude::*;
// f(x) = 0.2 * x + 0.2
let interp = Interpolator::new_1d(
    // x
    vec![0., 1., 2.], // x0, x1, x2
    // f(x)
    vec![0.2, 0.4, 0.6], // f(x0), f(x1), f(x2)
    Strategy::Linear, // linear interpolation
    Extrapolate::Enable, // linearly extrapolate when point is out of bounds
)
.unwrap(); // handle data validation results
assert_eq!(interp.interpolate(&[1.5]).unwrap(), 0.5);
assert_eq!(interp.interpolate(&[-1.]).unwrap(), 0.); // extrapolation below grid
assert_eq!(interp.interpolate(&[2.2]).unwrap(), 0.64); // extrapolation above grid

Interp2D(Interp2D)

Interpolates in two dimensions.

Applicable interpolation strategies:

• Strategy::Linear

Applicable extrapolation strategies:

• Extrapolate::Clamp
• Extrapolate::Error

Example (using Extrapolate::Clamp):

use ninterp::prelude::*;
// f(x, y) = 0.2 * x + 0.4 * y
let interp = Interpolator::new_2d(
    // x
    vec![0., 1., 2.], // x0, x1, x2
    // y
    vec![0., 1., 2.], // y0, y1, y2
    // f(x, y)
    vec![
        vec![0.0, 0.4, 0.8], // f(x0, y0), f(x0, y1), f(x0, y2)
        vec![0.2, 0.6, 1.0], // f(x1, y0), f(x1, y1), f(x1, y2)
        vec![0.4, 0.8, 1.2], // f(x2, y0), f(x2, y1), f(x2, y2)
    ],
    Strategy::Linear,
    Extrapolate::Clamp, // restrict point within grid bounds
)
.unwrap();
assert_eq!(interp.interpolate(&[1.5, 1.5]).unwrap(), 0.9);
assert_eq!(
    interp.interpolate(&[-1., 2.5]).unwrap(),
    interp.interpolate(&[0., 2.]).unwrap()
); // point is restricted to within grid bounds

Interp3D(Interp3D)

Interpolates in three dimensions.

Applicable interpolation strategies:

• Strategy::Linear

Applicable extrapolation strategies:

• Extrapolate::Clamp
• Extrapolate::Error

Example (using Extrapolate::Error):

use ninterp::prelude::*;
// f(x, y, z) = 0.2 * x + 0.2 * y + 0.2 * z
let interp = Interpolator::new_3d(
    // x
    vec![1., 2.], // x0, x1
    // y
    vec![1., 2.], // y0, y1
    // z
    vec![1., 2.], // z0, z1
    // f(x, y, z)
    vec![
        vec![
            vec![0.6, 0.8], // f(x0, y0, z0), f(x0, y0, z1)
            vec![0.8, 1.0], // f(x0, y1, z0), f(x0, y1, z1)
        ],
        vec![
            vec![0.8, 1.0], // f(x1, y0, z0), f(x1, y0, z1)
            vec![1.0, 1.2], // f(x1, y1, z0), f(x1, y1, z1)
        ],
    ],
    Strategy::Linear,
    Extrapolate::Error, // return an error when point is out of bounds
)
.unwrap();
assert_eq!(interp.interpolate(&[1.5, 1.5, 1.5]).unwrap(), 0.9);
// out of bounds point with `Extrapolate::Error` fails
assert!(matches!(
    interp.interpolate(&[2.5, 2.5, 2.5]).unwrap_err(),
    ninterp::error::InterpolationError::ExtrapolationError(_)
));

InterpND(InterpND)

Interpolates with any dimensionality.

Applicable interpolation strategies:

• Strategy::Linear

Applicable extrapolation strategies:

• Extrapolate::Clamp
• Extrapolate::Error

Example (using Extrapolate::Error):

use ninterp::prelude::*;
use ndarray::array;
// f(x, y, z) = 0.2 * x + 0.2 * y + 0.2 * z
let interp = Interpolator::new_nd(
    // grid
    vec![
        vec![1., 2.], // x0, x1
        vec![1., 2.], // y0, y1
        vec![1., 2.], // z0, z1
    ],
    // values
    array![
        [
            [0.6, 0.8], // f(x0, y0, z0), f(x0, y0, z1)
            [0.8, 1.0], // f(x0, y1, z0), f(x0, y1, z1)
        ],
        [
            [0.8, 1.0], // f(x1, y0, z0), f(x1, y0, z1)
            [1.0, 1.2], // f(x1, y1, z0), f(x1, y1, z1)
        ],
    ].into_dyn(),
    Strategy::Linear,
    Extrapolate::Error, // return an error when point is out of bounds
)
.unwrap();
assert_eq!(interp.interpolate(&[1.5, 1.5, 1.5]).unwrap(), 0.9);
// out of bounds point with `Extrapolate::Error` fails
assert!(matches!(
    interp.interpolate(&[2.5, 2.5, 2.5]).unwrap_err(),
    ninterp::error::InterpolationError::ExtrapolationError(_)
));

Implementations

impl Interpolator

pub fn new_1d( x: Vec<f64>, f_x: Vec<f64>, strategy: Strategy, extrapolate: Extrapolate, ) -> Result<Self, ValidationError>

pub fn new_2d( x: Vec<f64>, y: Vec<f64>, f_xy: Vec<Vec<f64>>, strategy: Strategy, extrapolate: Extrapolate, ) -> Result<Self, ValidationError>

pub fn new_3d( x: Vec<f64>, y: Vec<f64>, z: Vec<f64>, f_xyz: Vec<Vec<Vec<f64>>>, strategy: Strategy, extrapolate: Extrapolate, ) -> Result<Self, ValidationError>

pub fn new_nd( grid: Vec<Vec<f64>>, values: ArrayD<f64>, strategy: Strategy, extrapolate: Extrapolate, ) -> Result<Self, ValidationError>

pub fn ndim(&self) -> usize

Interpolator dimensionality

impl Interpolator

pub fn strategy(&self) -> Result<&Strategy, Error>

Get strategy field from any interpolator.

pub fn set_strategy(&mut self, strategy: Strategy) -> Result<(), Error>

Set strategy field on any interpolator.

pub fn extrapolate(&self) -> Result<&Extrapolate, Error>

Get extrapolate field from any interpolator.

pub fn set_extrapolate(&mut self, extrapolate: Extrapolate) -> Result<(), Error>

Set extrapolate field on any interpolator.

pub fn x(&self) -> Result<&[f64], Error>

Get x field from 1D/2D/3D interpolator.

pub fn set_x(&mut self, x: Vec<f64>) -> Result<(), Error>

Set x field on 1D/2D/3D interpolator.

pub fn y(&self) -> Result<&[f64], Error>

Get y field from 2D/3D interpolator.

pub fn set_y(&mut self, y: Vec<f64>) -> Result<(), Error>

Set y field on 2D/3D interpolator.

pub fn z(&self) -> Result<&[f64], Error>

Get z field from 3D interpolator.

pub fn set_z(&mut self, z: Vec<f64>) -> Result<(), Error>

Set z field on 3D interpolator.

pub fn f_x(&self) -> Result<&[f64], Error>

Get f_x field from 1D interpolator.

pub fn set_f_x(&mut self, f_x: Vec<f64>) -> Result<(), Error>

Set f_x field on 1D interpolator.

pub fn f_xy(&self) -> Result<&[Vec<f64>], Error>

Get f_xy field from 2D interpolator.

pub fn set_f_xy(&mut self, f_xy: Vec<Vec<f64>>) -> Result<(), Error>

Set f_xy field on 2D interpolator.

pub fn f_xyz(&self) -> Result<&[Vec<Vec<f64>>], Error>

Get f_xyz field from 3D interpolator.

pub fn set_f_xyz(&mut self, f_xyz: Vec<Vec<Vec<f64>>>) -> Result<(), Error>

Set f_xyz field on 3D interpolator.

pub fn grid(&self) -> Result<&[Vec<f64>], Error>

Get grid field from ND interpolator.

pub fn set_grid(&mut self, grid: Vec<Vec<f64>>) -> Result<(), Error>

Set grid field on ND interpolator.

pub fn values(&self) -> Result<&ArrayD<f64>, Error>

Get values field from ND interpolator.

pub fn set_values(&mut self, values: ArrayD<f64>) -> Result<(), Error>

Set values field on ND interpolator.

Trait Implementations

impl Clone for Interpolator

fn clone(&self) -> Interpolator

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Interpolator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl InterpMethods for Interpolator

fn interpolate(&self, point: &[f64]) -> Result<f64, InterpolationError>

Interpolate at supplied point, after checking point validity. Length of supplied point must match interpolator dimensionality.

fn validate(&self) -> Result<(), ValidationError>

Validate data stored in Self

impl PartialEq for Interpolator

fn eq(&self, other: &Interpolator) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Interpolator