Ndpolator Class Reference

This class implements interpolation and extrapolation in n dimensions. More...

Public Member Functions
None	__init__ (self, tuple basic_axes)
	Instantiates an Ndpolator class.
None	register (self, str name, tuple associated_axes, np.ndarray grid)
	Registers an interpolation grid, along with any associated tables, with the ndpolator instance.
tuple	import_query_pts (self, str name, np.ndarray query_pts)
	Imports and processes query points (points of interest).
np.ndarray	find_hypercubes (self, str name, np.ndarray normed_query_pts, np.ndarray indices, np.ndarray flags, tuple associated_axes=None)
	Extracts and populates hypercubes for each query point based on the table reference, indices, flags and any associated axes.
np.ndarray	distance (self, str name, np.ndarray query_pts)
	Computes the squared Euclidean distance from each query point to the nearest hypercube in the interpolation grid.
np.ndarray	ndpolate (self, str name, np.ndarray query_pts, str extrapolation_method='none', str search_algorithm='kdtree')
	Performs n-dimensional interpolation or extrapolation.

Data Fields
	axes = basic_axes
	table = dict()

Properties
	tables = property
	Prints a list of tables attached to the ndpolator instance.

Detailed Description

This class implements interpolation and extrapolation in n dimensions.

Ndpolator wraps around the C extension and provides a user-friendly interface from python.

Attributes

• axes : tuple[ndarray] Basic axes that span the ndpolator grid.
• table : dict Dictionary holding registered interpolation grids and their metadata. Each entry contains associated axes, grid data, and cached C extension capsule.

Constructor & Destructor Documentation

__init__()

None __init__	(		self,
		tuple	basic_axes )

Instantiates an Ndpolator class.

The class relies on basic_axes to span the interpolation hypercubes. Only basic (spanning) axes should be passed here.

Parameters

• basic_axes : tuple of float ndarrays Axes that span the ndpolator grid.

Member Function Documentation

register()

None register	(		self,
		str	name,
		tuple	associated_axes,
		np.ndarray	grid )

Registers an interpolation grid, along with any associated tables, with the ndpolator instance.

It is referenced by the provided table label. The list of tables is held in the top-level table dictionary. Each entry in the list has three elements: a tuple of associated axes, the interpolation grid, and a capsule (initially None) that stores a pointer to the initialized cndpolator structure for caching purposes.

Parameters

• name : str reference label to the interpolation grid
• associated_axes : tuple or None any additional non-basic axes in the interpolation grid
• grid : ndarray interpolation grid; grid shape should be (l(b1), ..., l(bn), l(a1), ..., l(am), l(fv)), where bk are basic axes, ak are associated axes and fv is the function value; l(x) is the length of axis x.

Raises

TypeError if any of passed parameters have an incorrect type.

import_query_pts()

tuple import_query_pts	(		self,
		str	name,
		np.ndarray	query_pts )

Imports and processes query points (points of interest).

This entails finding the enclosing (or adjacent, if at the boundary of the grid) hypercubes for each query point; per query point component flags (whether the component is on grid, on vertex, or out of bounds); and hypercube-normalized query points. Indices identify hypercubes by their superior corner; for example, a (3, 4, 5) x (2, 3, 4) x (1, 2) hypercube would be identified by the (5, 4, 2) corner. Thus, for N query points and M basic axes, all three arrays (indices, flags and hypercube-normalized query points are (N, M)-shaped.

Note

this class method is rarely called directly. The only time it would be called is when the calling function identifies query points within a certain hypercube and then reuses the indices, flags, and hypercube-normalized query points.

Parameters

• name : str reference label to the interpolation grid
• query_pts : ndarray an ndarray of query points; the expected shape is (N, M), where N is the number of query points and M is the number of basic axes.

Returns

tuple[ndarray]

A tuple with three elements: an ndarray of containing hypercube indices, an ndarray of per-component flags, and an ndarray of hypercube-normalized query points.

find_hypercubes()

np.ndarray find_hypercubes	(		self,
		str	name,
		np.ndarray	normed_query_pts,
		np.ndarray	indices,
		np.ndarray	flags,
		tuple	associated_axes = None )

Extracts and populates hypercubes for each query point based on the table reference, indices, flags and any associated axes.

Note

this class method is rarely called directly. The only time it would be called is when the calling function identifies query points within a certain hypercube and then reuses the indices, flags, and hypercube-normalized query points.

Parameters

• name : str reference label to the interpolation grid
• normed_query_pts : ndarray an (N, M)-shaped array of normalized query points
• indices : ndarray an (N, M)-shaped array of superior hypercube corners
• flags : ndarray an (N, M)-shaped array of per-query-point-component flags
• associated_axes : tuple | None, optional A tuple of any associated (non-basic) axes, by default None

Returns

ndarray An (N, M, l(fv))-shaped array of containing (or adjacent, if on the grid boundary) hypercubes identified by their superior corners; N is the number of query points, M is the number of basic axes, and l(fv) is the length of the function values.

distance()

np.ndarray distance	(		self,
		str	name,
		np.ndarray	query_pts )

Computes the squared Euclidean distance from each query point to the nearest hypercube in the interpolation grid.

Points inside the grid have distance 0, while points outside have distance equal to the squared distance to the nearest edge, face, or vertex of the grid.

This method is useful for:

• Determining which query points lie outside the interpolation grid
• Computing distances without performing extrapolation
• Quality control and validation of query point positions

Parameters

• name : str reference label to the interpolation grid
• query_pts : ndarray an ndarray of query points; the expected shape is (N, M), where N is the number of query points and M is the number of basic axes.

Returns

ndarray An (N, 1)-shaped array of squared distances from each query point to the nearest hypercube. Distance is 0 for points inside the grid, and >0 for points outside the grid boundaries.

Examples

>>> ndp = Ndpolator((np.array([0., 1., 2.]), np.array([0., 1., 2.])))
>>> grid = np.random.rand(3, 3, 1)
>>> ndp.register('test', None, grid)
>>> query_pts = np.array([[0.5, 0.5], [2.5, 1.0], [-0.5, -0.5]])
>>> dists = ndp.distance('test', query_pts)
>>> # First point inside grid: distance = 0
>>> # Second point outside (right): distance = 0.25
>>> # Third point outside (diagonal): distance = 0.5

ndpolate()

np.ndarray ndpolate	(		self,
		str	name,
		np.ndarray	query_pts,
		str	extrapolation_method = 'none',
		str	search_algorithm = 'kdtree' )

Performs n-dimensional interpolation or extrapolation.

This is the main "workhorse" of the class and should be considered the default interface to the underlying C-based cndpolator extension. See the top-level README.md file for usage examples.

Parameters

• name : str reference label to the interpolation grid
• query_pts : ndarray an ndarray of query points; the expected shape is (N, M), where N is the number of query points and M is the number of basic axes.
• extrapolation_method : str, optional extrapolation method, one of 'none', 'nearest', 'linear'; by default 'none'
• search_algorithm : str, optional search algorithm, one of 'kdtree', 'linear'; by default 'kdtree'

Returns

dict

• mandatory keys: 'interps'
• optional keys: 'dists'
• interps: ndarray an (N, l(fv))-shaped array of interpolated values, where N is the number of query points and l(fv) is the length of function values.

Raises

ValueError

• raised when the passed extrapolation method is not one of 'none', 'nearest', 'linear'.
• raised when the passed search algorithm is not one of 'kdtree', 'linear'.

Field Documentation

axes

axes = basic_axes

table

table = dict()

Property Documentation

tables

tables = property

static

Prints a list of tables attached to the ndpolator instance.

  Returns
  -------

list[str]

table names (references) attached to the ndpolator