1.2.3. Functions and Interpolators¶

1.2.3.1. Functions Returning a Float¶

class raysect.core.math.function.float.function1d.base.Function1D¶

Cython optimised class for representing an arbitrary 1D function returning a float.

Using __call__() in cython is slow. This class provides an overloadable cython cdef evaluate() method which has much less overhead than a python function call.

For use in cython code only, this class cannot be extended via python.

To create a new function object, inherit this class and implement the evaluate() method. The new function object can then be used with any code that accepts a function object.

__call__()¶

Evaluate the function f(x)

Parameters: x (float) – function parameter x
Return type: float

class raysect.core.math.function.float.function1d.constant.Constant1D¶

Bases: raysect.core.math.function.float.function1d.base.Function1D

Wraps a scalar constant with a Function1D object.

This class allows a numeric Python scalar, such as a float or an integer, to interact with cython code that requires a Function1D object. The scalar must be convertible to double. The value of the scalar constant will be returned independent of the arguments the function is called with.

This class is intended to be used to transparently wrap python objects that are passed via constructors or methods into cython optimised code. It is not intended that the users should need to directly interact with these wrapping objects. Constructors and methods expecting a Function1D object should be designed to accept a generic python object and then test that object to determine if it is an instance of Function1D. If the object is not a Function1D object it should be wrapped using this class for internal use.

1.2.3.2. Functions Returning a Vector3D¶

class raysect.core.math.function.vector3d.function1d.base.Function1D¶

Cython optimised class for representing an arbitrary 1D vector function.

Using __call__() in cython is slow. This class provides an overloadable cython cdef evaluate() method which has much less overhead than a python function call.

For use in cython code only, this class cannot be extended via python.

To create a new function object, inherit this class and implement the evaluate() method. The new function object can then be used with any code that accepts a function object returning a Vector3D.

__call__()¶

Evaluate the function f(x)

Parameters: x (float) – function parameter x
Return type: float

class raysect.core.math.function.vector3d.function1d.constant.Constant1D¶

Bases: raysect.core.math.function.vector3d.function1d.base.Function1D

Wraps a Vector3D object with a Function1D object.

This class allows a constant vector object to interact with cython code that requires a vector3d.Function1D object. The object must be convertible to a Vector3D. The value of the Vector3D constant will be returned independent of the arguments the function is called with.

This class is intended to be used to transparently wrap python objects that are passed via constructors or methods into cython optimised code. It is not intended that the users should need to directly interact with these wrapping objects. Constructors and methods expecting a vector3d.function1D object should be designed to accept a generic python object and then test that object to determine if it is an instance of vector3d.Function1D. If the object is not a vector3d.Function1D object it should be wrapped using this class for internal use.

1.2.3.3. Interpolators¶

1.2.3.3.1. 1D interpolators¶

class raysect.core.math.function.float.function1d.interpolate.Interpolator1DArray¶

Bases: raysect.core.math.function.float.function1d.base.Function1D

A configurable interpolator for 1D arrays.

Coordinate array (x) and data array (f) are sorted and transformed into Numpy arrays. The resulting Numpy arrays are stored as read only. I.e. writeable flag of self.x and self.f is set to False. Alteration of the flag may result in unwanted behaviour.

Parameters

x (object) – 1D array-like object of real values storing the x spline knot positions.
f (object) – 1D array-like object of real values storing the spline knot function value at x.
interpolation_type (str) – Type of interpolation to use. Options are: linear: Interpolates the data using piecewise linear interpolation. cubic: Interpolates the data using piecewise cubic interpolation.
extrapolation_type (str) – Type of extrapolation to use. Options are: none: Attempt to access data outside of x’s range will yield ValueError. nearest: Extrapolation results is the nearest position x value in the interpolation domain. linear: Extrapolate bilinearly the interpolation function. quadratic: Extrapolate quadratically the interpolation function. Constrains the function at the edge, and the derivative both at the edge and 1 spline knot from the edge.
extrapolation_range (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (x).

>>> from raysect.core.math.function.float.function1d.interpolate import Interpolator1DArray
>>>
>>> x = np.linspace(-1., 1., 20)
>>> f = np.exp(-x**2)
>>> interpolator1D = Interpolate1DArray(x, f, 'cubic', 'nearest', 1.0)
>>> # Interpolation
>>> interpolator1D(0.2)
0.9607850606581484
>>> # Extrapolation
>>> interpolator1D(1.1)
0.36787944117144233
>>> # Extrapolation out of bounds
>>> interpolator1D(2.1)
ValueError: The specified value (x=2.1) is outside of extrapolation range.

Note: All input derivatives used in calculations use the previous and next indices in the spline knot arrays. At the edge of the spline knot arrays the index of the edge of the array is is used instead.
Note: x and f arrays must be of equal length.
Note: x must be a monotonically increasing array.

1.2.3.3.2. 2D interpolators¶

class raysect.core.math.function.float.function2d.interpolate.interpolator2darray.Interpolator2DArray¶

Bases: raysect.core.math.function.float.function2d.base.Function2D

A configurable interpolator for 2D arrays.

Coordinate array (x), array (y) and data array (f) are sorted and transformed into Numpy arrays. The resulting Numpy arrays are stored as read only. I.e. writeable flag of self.x, self.y and self.f is set to False. Alteration of the flag may result in unwanted behaviour.

Parameters

x (object) – 1D array-like object of real values storing the x spline knot positions.
y (object) – 1D array-like object of real values storing the y spline knot positions.
f (object) – 2D array-like object of real values storing the spline knot function value at x, y.
interpolation_type (str) – Type of interpolation to use. Options are: linear: Interpolates the data using piecewise bilinear interpolation. cubic: Interpolates the data using piecewise bicubic interpolation.
extrapolation_type (str) – Type of extrapolation to use. Options are: none: Attempt to access data outside of x’s and y’s range will yield ValueError. nearest: Extrapolation results is the nearest position x and y value in the interpolation domain. linear: Extrapolate bilinearly the interpolation function.
extrapolation_range_x (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (x).
extrapolation_range_y (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (y).

>>> from raysect.core.math.function.float.function2d.interpolate.interpolator2darray import Interpolator2DArray
>>>
>>> x = np.linspace(-1., 1., 20)
>>> y = np.linspace(-1., 1., 20)
>>> x_array, y_array = np.meshgrid(x, y)
>>> f = np.exp(-(x_array**2 + y_array**2))
>>> interpolator2D = Interpolator2DArray(x, y, f, 'cubic', 'nearest', 1.0, 1.0)
>>> # Interpolation
>>> interpolator2D(1.0, 0.2)
0.35345307120078995
>>> # Extrapolation
>>> interpolator2D(1.0, 1.1)
0.1353352832366128
>>> # Extrapolation out of bounds
>>> interpolator2D(1.0, 2.1)
ValueError: The specified value (y=2.1) is outside of extrapolation range.

Note: All input derivatives used in calculations use the previous and next indices in the spline knot arrays. At the edge of the spline knot arrays the index of the edge of the array is is used instead.
Note: x, y arrays must be equal in shape to f in the first and second dimension respectively.
Note: x and y must be monotonically increasing arrays.

class raysect.core.math.function.float.function2d.interpolate.interpolator2dmesh.Interpolator2DMesh¶

Bases: raysect.core.math.function.float.function2d.base.Function2D

Linear interpolator for data on a 2d ungridded tri-poly mesh.

The mesh is specified as a set of 2D vertices supplied as an Nx2 numpy array or a suitably sized sequence that can be converted to a numpy array.

The mesh triangles are defined with a Mx3 array where the three values are indices into the vertex array that specify the triangle vertices. The mesh must not contain overlapping triangles. Supplying a mesh with overlapping triangles will result in undefined behaviour.

A data array of length N, containing a value for each vertex, holds the data to be interpolated across the mesh.

By default, requesting a point outside the bounds of the mesh will cause a ValueError exception to be raised. If this is not desired the limit attribute (default True) can be set to False. When set to False, a default value will be returned for any point lying outside the mesh. The value return can be specified by setting the default_value attribute (default is 0.0).

To optimise the lookup of triangles, the interpolator builds an acceleration structure (a KD-Tree) from the specified mesh data. Depending on the size of the mesh, this can be quite slow to construct. If the user wishes to interpolate a number of different data sets across the same mesh - for example: temperature and density data that are both defined on the same mesh - then the user can use the instance() method on an existing interpolator to create a new interpolator. The new interpolator will shares a copy of the internal acceleration data. The vertex_data, limit and default_value can be customised for the new instance. See instance(). This will avoid the cost in memory and time of rebuilding an identical acceleration structure.

Parameters

vertex_coords (ndarray) – An array of vertex coordinates (x, y) with shape Nx2.
vertex_data (ndarray) – An array containing data for each vertex of shape Nx1.
triangles (ndarray) – An array of vertex indices defining the mesh triangles, with shape Mx3.
limit (bool) – Raise an exception outside mesh limits - True (default) or False.
default_value (float) – The value to return outside the mesh limits if limit is set to False.

instance()¶

Creates a new interpolator instance from an existing interpolator instance.

The new interpolator instance will share the same internal acceleration data as the original interpolator. The vertex_data, limit and default_value settings of the new instance can be redefined by setting the appropriate attributes. If any of the attributes are set to None (default) then the value from the original interpolator will be copied.

This method should be used if the user has multiple sets of vertex_data that lie on the same mesh geometry. Using this methods avoids the repeated rebuilding of the mesh acceleration structures by sharing the geometry data between multiple interpolator objects.

Parameters

instance (Interpolator2DMesh) – Interpolator2DMesh object.
vertex_data (ndarray) – An array containing data for each vertex of shape Nx1 (default None).
limit (bool) – Raise an exception outside mesh limits - True (default) or False (default None).
default_value (float) – The value to return outside the mesh limits if limit is set to False (default None).

Returns

An Interpolator2DMesh object.

Return type

Interpolator2DMesh

class raysect.core.math.function.float.function2d.interpolate.discrete2dmesh.Discrete2DMesh¶

Bases: raysect.core.math.function.float.function2d.base.Function2D

Discrete interpolator for data on a 2d ungridded tri-poly mesh.

The mesh is specified as a set of 2D vertices supplied as an Nx2 numpy array or a suitably sized sequence that can be converted to a numpy array.

The mesh triangles are defined with a Mx3 array where the three values are indices into the vertex array that specify the triangle vertices. The mesh must not contain overlapping triangles. Supplying a mesh with overlapping triangles will result in undefined behaviour.

A data array of length M, containing a value for each triangle, holds the data to be interpolated across the mesh.

By default, requesting a point outside the bounds of the mesh will cause a ValueError exception to be raised. If this is not desired the limit attribute (default True) can be set to False. When set to False, a default value will be returned for any point lying outside the mesh. The value return can be specified by setting the default_value attribute (default is 0.0).

To optimise the lookup of triangles, the interpolator builds an acceleration structure (a KD-Tree) from the specified mesh data. Depending on the size of the mesh, this can be quite slow to construct. If the user wishes to interpolate a number of different data sets across the same mesh - for example: temperature and density data that are both defined on the same mesh - then the user can use the instance() method on an existing interpolator to create a new interpolator. The new interpolator will shares a copy of the internal acceleration data. The triangle_data, limit and default_value can be customised for the new instance. See instance(). This will avoid the cost in memory and time of rebuilding an identical acceleration structure.

Parameters

vertex_coords (ndarray) – An array of vertex coordinates (x, y) with shape Nx2.
triangles (ndarray) – An array of vertex indices defining the mesh triangles, with shape Mx3.
triangle_data (ndarray) – An array containing data for each triangle of shape Mx1.
limit (bool) – Raise an exception outside mesh limits - True (default) or False.
default_value (float) – The value to return outside the mesh limits if limit is set to False.

instance()¶

Creates a new interpolator instance from an existing interpolator instance.

The new interpolator instance will share the same internal acceleration data as the original interpolator. The triangle_data, limit and default_value settings of the new instance can be redefined by setting the appropriate attributes. If any of the attributes are set to None (default) then the value from the original interpolator will be copied.

This method should be used if the user has multiple sets of triangle_data that lie on the same mesh geometry. Using this methods avoids the repeated rebuilding of the mesh acceleration structures by sharing the geometry data between multiple interpolator objects.

Parameters

instance (Discrete2DMesh) – Discrete2DMesh object.
triangle_data (ndarray) – An array containing data for each triangle of shape Mx1 (default None).
limit (bool) – Raise an exception outside mesh limits - True (default) or False (default None).
default_value (float) – The value to return outside the mesh limits if limit is set to False (default None).

Returns

An Discrete2DMesh object.

Return type

Discrete2DMesh

1.2.3.3.3. 3D interpolators¶

class raysect.core.math.function.float.function3d.interpolate.interpolator3darray.Interpolator3DArray¶

Bases: raysect.core.math.function.float.function3d.base.Function3D

A configurable interpolator for 3D arrays.

Coordinate array (x), array (y), array (z) and data array (f) are sorted and transformed into Numpy arrays. The resulting Numpy arrays are stored as read only. I.e. writeable flag of self.x, self.y, self.z and self.f is set to False. Alteration of the flag may result in unwanted behaviour.

Parameters

x (object) – 1D array-like object of real values storing the x spline knot positions.
y (object) – 1D array-like object of real values storing the y spline knot positions.
z (object) – 1D array-like object of real values storing the z spline knot positions.
f (object) – 3D array-like object of real values storing the spline knot function value at x, y, z.
interpolation_type (str) – Type of interpolation to use. Options are: linear: Interpolates the data using piecewise trilinear interpolation. cubic: Interpolates the data using piecewise tricubic interpolation.
extrapolation_type (str) – Type of extrapolation to use. Options are: none: Attempt to access data outside of x’s and y’s range will yield ValueError. nearest: Extrapolation results is the nearest position x and y value in the interpolation domain. linear: Extrapolate bilinearly the interpolation function.
extrapolation_range_x (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (x).
extrapolation_range_y (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (y).
extrapolation_range_z (double) – Limits the range where extrapolation is permitted. Requesting data beyond the extrapolation range results in ValueError. Extrapolation range will be applied as padding symmetrically to both ends of the interpolation range (z).

>>> from raysect.core.math.function.float.function3d.interpolate.interpolator3darray import Interpolator3DArray
>>>
>>> x = np.linspace(-1., 1., 20)
>>> y = np.linspace(-1., 1., 20)
>>> z = np.linspace(-1., 1., 20)
>>> x_array, y_array, z_array = np.meshgrid(x, y, z, indexing='ij')
>>> f = np.exp(-(x_array**2 + y_array**2 + z_array**2))
>>> interpolator3D = Interpolator3DArray(x, y, z, f, 'cubic', 'nearest', 1.0, 1.0, 1.0)
>>> # Interpolation
>>> interpolator3D(1.0, 1.0, 0.2)
0.1300281183136766
>>> # Extrapolation
>>> interpolator3D(1.0, 1.0, 1.1)
0.0497870683678659
>>> # Extrapolation out of bounds
>>> interpolator3D(1.0, 1.0, 2.1)
ValueError: The specified value (z=2.1) is outside of extrapolation range.

Note: All input derivatives used in calculations use the previous and next indices in the spline knot arrays. At the edge of the spline knot arrays the index of the edge of the array is is used instead.
Note: x, y, z arrays must be equal in shape to f in the first, second and third dimension respectively.
Note: x, y and z must be monotonically increasing arrays.

class raysect.core.math.function.float.function3d.interpolate.discrete3dmesh.Discrete3DMesh¶

Bases: raysect.core.math.function.float.function3d.base.Function3D

Discrete interpolator for data on a 3d ungridded tetrahedra mesh.

The mesh is specified as a set of 3D vertices supplied as an Nx3 numpy array or a suitably sized sequence that can be converted to a numpy array.

The mesh tetrahedra are defined with a Mx4 array where the four values are indices into the vertex array that specify the tetrahedra vertices. The mesh must not contain overlapping tetrahedra. Supplying a mesh with overlapping tetrahedra will result in undefined behaviour.

A data array of length M, containing a value for each tetrahedra, holds the data to be interpolated across the mesh.

By default, requesting a point outside the bounds of the mesh will cause a ValueError exception to be raised. If this is not desired the limit attribute (default True) can be set to False. When set to False, a default value will be returned for any point lying outside the mesh. The value return can be specified by setting the default_value attribute (default is 0.0).

To optimise the lookup of tetrahedra, the interpolator builds an acceleration structure (a KD-Tree) from the specified mesh data. Depending on the size of the mesh, this can be quite slow to construct. If the user wishes to interpolate a number of different data sets across the same mesh - for example: temperature and density data that are both defined on the same mesh - then the user can use the instance() method on an existing interpolator to create a new interpolator. The new interpolator will shares a copy of the internal acceleration data. The tetrahedra_data, limit and default_value can be customised for the new instance. See instance(). This will avoid the cost in memory and time of rebuilding an identical acceleration structure.

Parameters

vertex_coords (ndarray) – An array of vertex coordinates (x, y, z) with shape Nx3.
tetrahedra (ndarray) – An array of vertex indices defining the mesh tetrahedra, with shape Mx4.
tetrahedra_data (ndarray) – An array containing data for each tetrahedra of shape Mx1.
limit (bool) – Raise an exception outside mesh limits - True (default) or False.
default_value (float) – The value to return outside the mesh limits if limit is set to False.

instance()¶

Creates a new interpolator instance from an existing interpolator instance.

The new interpolator instance will share the same internal acceleration data as the original interpolator. The tetrahedra_data, limit and default_value settings of the new instance can be redefined by setting the appropriate attributes. If any of the attributes are set to None (default) then the value from the original interpolator will be copied.

This method should be used if the user has multiple sets of tetrahedra_data that lie on the same mesh geometry. Using this methods avoids the repeated rebuilding of the mesh acceleration structures by sharing the geometry data between multiple interpolator objects.

Parameters

instance (Discrete3DMesh) – Discrete3DMesh object.
tetrahedra_data (ndarray) – An array containing data for each tetrahedra of shape Mx1 (default None).
limit (bool) – Raise an exception outside mesh limits - True (default) or False (default None).
default_value (float) – The value to return outside the mesh limits if limit is set to False (default None).

Returns

An Discrete3DMesh object.

Return type

Discrete3DMesh