interpolators

Functions for performing numerical interpolation using various algorithms. More details on the usage of these functions is given in the user guide.

Functions

linear_interpolation(lookup_scheme, ...)

Function to create settings for linear interpolation.

piecewise_constant_interpolation(...)

Function to create settings for piecewise constant interpolation.

cubic_spline_interpolation(lookup_scheme, ...)

Function to create settings for cubic spline interpolation.

hermite_spline_interpolation(lookup_scheme, ...)

Function to create settings for cubic Hermite spline interpolation.

lagrange_interpolation(number_of_points, ...)

Function to create settings for cubic Lagrange interpolation.

create_one_dimensional_scalar_interpolator(...)

Function to create an interpolator for scalar dependent variables.

create_one_dimensional_vector_interpolator(...)

Function to create an interpolator for vector dependent variables.

create_one_dimensional_matrix_interpolator(...)

Function to create an interpolator for matrix dependent variables.

linear_interpolation(lookup_scheme: tudatpy.kernel.math.interpolators.AvailableLookupScheme = <AvailableLookupScheme.hunting_algorithm: 1>, boundary_interpolation: tudatpy.kernel.math.interpolators.BoundaryInterpolationType = <BoundaryInterpolationType.extrapolate_at_boundary_with_warning: 4>) tudatpy.kernel.math.interpolators.InterpolatorSettings

Function to create settings for linear interpolation.

Function to create settings for linear interpolation, where the interpolator defines a linear curve between each two subsequent intervals of the independent variable input data.

Parameters:
  • lookup_scheme (AvailableLookupScheme, default = hunting_algorithm) – Algorithm used to find the nearest neighbor in the independent variable input data when the interpolation scheme is called

  • boundary_interpolation (BoundaryInterpolationType, default=extrapolate_at_boundary_with_warning) – Interpolator behaviour that is to be used beyond the upper and lower boundaries of the independent variable input data

Returns:

Linear interpolation settings object

Return type:

InterpolatorSettings

piecewise_constant_interpolation(lookup_scheme: tudatpy.kernel.math.interpolators.AvailableLookupScheme = <AvailableLookupScheme.hunting_algorithm: 1>, boundary_interpolation: tudatpy.kernel.math.interpolators.BoundaryInterpolationType = <BoundaryInterpolationType.extrapolate_at_boundary_with_warning: 4>) tudatpy.kernel.math.interpolators.InterpolatorSettings

Function to create settings for piecewise constant interpolation.

Function to create settings for piecewise constant interpolation. If interpolator is to return the value at \(t\), and \(t_{i}\le t < t_{i+1}\), the interpolator returns \(\mathbf{x}_{i}\)

Parameters:
  • lookup_scheme (AvailableLookupScheme, default = hunting_algorithm) – Algorithm used to find the nearest neighbor in the independent variable input data when the interpolation scheme is called

  • boundary_interpolation (BoundaryInterpolationType, default = extrapolate_at_boundary_with_warning) – Interpolator behaviour that is to be used beyond the upper and lower boundaries of the independent variable input data

Returns:

Piecewise constant interpolation settings object

Return type:

InterpolatorSettings

cubic_spline_interpolation(lookup_scheme: tudatpy.kernel.math.interpolators.AvailableLookupScheme = <AvailableLookupScheme.hunting_algorithm: 1>, boundary_interpolation: tudatpy.kernel.math.interpolators.BoundaryInterpolationType = <BoundaryInterpolationType.extrapolate_at_boundary_with_warning: 4>) tudatpy.kernel.math.interpolators.InterpolatorSettings

Function to create settings for cubic spline interpolation.

Function to create settings for cubic spline interpolation, where the interpolator defines a cubic curve polynomial curve between each two subsequent intervals of the independent variable input data. The curve has continuous value, first derivative and second derivate between subsequent intervals. As boundary condition, the spline has a zero second derivative imposed at the upper and lower boundaries of the interpolation domain.

Parameters:
  • lookup_scheme (AvailableLookupScheme, default = hunting_algorithm) – Algorithm used to find the nearest neighbor in the independent variable input data when the interpolation scheme is called

  • boundary_interpolation (BoundaryInterpolationType, default = extrapolate_at_boundary_with_warning) – Interpolator behaviour that is to be used beyond the upper and lower boundaries of the independent variable input data

Returns:

Cubic spline settings object

Return type:

InterpolatorSettings

hermite_spline_interpolation(lookup_scheme: tudatpy.kernel.math.interpolators.AvailableLookupScheme = <AvailableLookupScheme.hunting_algorithm: 1>, boundary_interpolation: tudatpy.kernel.math.interpolators.BoundaryInterpolationType = <BoundaryInterpolationType.extrapolate_at_boundary_with_warning: 4>) tudatpy.kernel.math.interpolators.InterpolatorSettings

Function to create settings for cubic Hermite spline interpolation.

Function to create settings for piecewise cubic Hermite spline interpolation. To use this interpolator, a key-value container of values, and a key-value container of first derivatives, must be provided to the function creating an interpolator (create_one_dimensional_scalar_interpolator(), create_one_dimensional_vector_interpolator(), create_one_dimensional_matrix_interpolator()). The resulting spline uses the value and first derivatives (four piece of information for each interval) at two subsequent nodes to construct a cubic polynomial between each two subsequent nodes. The resulting spline has constant values and first derivatives

Parameters:
  • lookup_scheme (AvailableLookupScheme, default = hunting_algorithm) – Algorithm used to find the nearest neighbor in the independent variable input data when the interpolation scheme is called

  • boundary_interpolation (BoundaryInterpolationType, default = extrapolate_at_boundary_with_warning) – Interpolator behaviour that is to be used beyond the upper and lower boundaries of the independent variable input data

Returns:

Hermite spline interpolation settings object

Return type:

InterpolatorSettings

lagrange_interpolation(number_of_points: int, lookup_scheme: tudatpy.kernel.math.interpolators.AvailableLookupScheme = <AvailableLookupScheme.hunting_algorithm: 1>, boundary_interpolation: tudatpy.kernel.math.interpolators.BoundaryInterpolationType = <BoundaryInterpolationType.extrapolate_at_boundary_with_warning: 4>, lagrange_boundary_handling: tudatpy.kernel.math.interpolators.LagrangeInterpolatorBoundaryHandling = <LagrangeInterpolatorBoundaryHandling.???: 0>) tudatpy.kernel.math.interpolators.InterpolatorSettings

Function to create settings for cubic Lagrange interpolation.

Function to create settings for piecewise cubic Lagrange interpolation. This is typically the interpolator of highest accuracy that is available. The Lagrange interpolator uses \(m\) consecutive points (input to this function) from the input independent variables \([t_{0}...t_{N}]\) to create the polynomial of order \(m-1\) that interpolates these points. From here on, we assume \(m\) is even. The algorithm that is used (see here for mathematical details on interpolating Lagrange polynomials) works as follows:

  • The nearest lower neighbor of the data point \(t\) at which the state \(\mathbf{x}\) is to be interpolated is determined, and denoted \(t_{i}\).

  • An interpolating Lagrange polynomial is constructed from the consecutive data points \([t_{i-(m/2-1)}...t_{i+m}]\)

  • This resulting interpolating polynomial is only used in the interval \([t_{i}...t_{i+1}]\), to prevent Runge’s phenomenon.

For instance, if \(m=8\) we use a \(7^{th}\) order polynomial that interpolates a contiguous set of 8 data points out of the full data set. Normally, the interpolating polynomial is only used between the \(4^{th}\) and \(5^{th}\) data point, where it will typically be of good accuracy. Consequently, a separate interpolating polynomial (using data over a span of \(m\) consecutive points) is used for each single interval \([t_{i}...t_{i+1}]\) (with the exception of the boundaries, see below).

Warning

Issues can occur if the data point \(t\) at which the interpolation is to be performed is close to \(t_{0}\) or \(t_{N}\). In those case, there is not sufficient data to construct the interpolating polynomial and to only use this interpolating polynomial between the middle two data points that were used to it. In these cases, the user has a number of options (all defined by an entry of the LagrangeInterpolatorBoundaryHandling variable, used as input to this function). In short, interpolation between the first and last \(m/2\) data points will lead to degraded results, warnings, or termination.

Parameters:
  • number_of_points (int) – Number of consecutive data points that are used to construct a single interpolating polynomial.

  • lookup_scheme (AvailableLookupScheme, default = hunting_algorithm) – Algorithm used to find the nearest neighbor in the independent variable input data when the interpolation scheme is called

  • boundary_interpolation (BoundaryInterpolationType, default = extrapolate_at_boundary_with_warning) – Interpolator behaviour that is to be used beyond the upper and lower boundaries of the independent variable input data

  • lagrange_boundary_handling (LagrangeInterpolatorBoundaryHandling, default = lagrange_cubic_spline_boundary_interpolation) – Interpolator behaviour that is to be used at the boundaries of the domain, where the regular algorithm cannot be executed.

Returns:

Lagrange interpolation settings object

Return type:

LagrangeInterpolatorSettings

create_one_dimensional_scalar_interpolator(data_to_interpolate: dict[float, float], interpolator_settings: tudatpy.kernel.math.interpolators.InterpolatorSettings, data_first_derivatives: list[float] = []) tudat::interpolators::OneDimensionalInterpolator<double, double>

Function to create an interpolator for scalar dependent variables.

Function to create an interpolator for scalar dependent variables, with a single independent variable. This function takes the interpolator settings, and the data that is to be interpolated, as input to create the object that can perform the actual interpolation

Parameters:
  • data_to_interpolate (dict[float, float]) – Key-value container with pairs of independent variables (key) and dependent variables (value) from which the interpolation is to be performed

  • interpolator_settings (InterpolatorSettings) – Settings that define the type of interpolator that is to be used

  • data_first_derivatives (dict[float, float] = dict()) – Key-value container with pairs of independent variables (key) and first derivative dependent variables w.r.t. independent variable (value) from which the interpolation is to be performed. This input is only required if the requested interpolation algorithm requires first derivatives as input (such as the Hermite spline interpolator

Returns:

Interpolator object

Return type:

OneDimensionalInterpolatorScalar

create_one_dimensional_vector_interpolator(data_to_interpolate: dict[float, numpy.ndarray[numpy.float64[m, 1]]], interpolator_settings: tudatpy.kernel.math.interpolators.InterpolatorSettings, data_first_derivatives: list[numpy.ndarray[numpy.float64[m, 1]]] = []) tudat::interpolators::OneDimensionalInterpolator<double, Eigen::Matrix<double, -1, 1, 0, -1, 1> >

Function to create an interpolator for vector dependent variables.

As create_one_dimensional_scalar_interpolator(), but with vectors as dependent variables

Parameters:
  • data_to_interpolate (dict[float, np.array]) – Key-value container with pairs of independent variables (key) and dependent variables (value) from which the interpolation is to be performed

  • interpolator_settings (InterpolatorSettings) – Settings that define the type of interpolator that is to be used

  • data_first_derivatives (dict[float, np.array] = dict()) – Key-value container with pairs of independent variables (key) and first derivative dependent variables w.r.t. independent variable (value) from which the interpolation is to be performed. This input is only required if the requested interpolation algorithm requires first derivatives as input (such as the Hermite spline interpolator).

Returns:

Interpolator object

Return type:

OneDimensionalInterpolatorVector

create_one_dimensional_matrix_interpolator(data_to_interpolate: dict[float, numpy.ndarray[numpy.float64[m, n]]], interpolator_settings: tudatpy.kernel.math.interpolators.InterpolatorSettings, data_first_derivatives: list[numpy.ndarray[numpy.float64[m, n]]] = []) tudat::interpolators::OneDimensionalInterpolator<double, Eigen::Matrix<double, -1, -1, 0, -1, -1> >

Function to create an interpolator for matrix dependent variables.

As create_one_dimensional_scalar_interpolator(), but with matrices (2-dimensional arrays) as dependent variables

Parameters:
  • data_to_interpolate (dict[float, np.array]) – Key-value container with pairs of independent variables (key) and dependent variables (value) from which the interpolation is to be performed

  • interpolator_settings (InterpolatorSettings) – Settings that define the type of interpolator that is to be used

  • data_first_derivatives (dict[float, np.array] = dict()) – Key-value container with pairs of independent variables (key) and first derivative dependent variables w.r.t. independent variable (value) from which the interpolation is to be performed. This input is only required if the requested interpolation algorithm requires first derivatives as input (such as the Hermite spline interpolator

Returns:

Interpolator object

Return type:

OneDimensionalInterpolatorMatrix

Enumerations

BoundaryInterpolationType

Enumeration of types of behaviour to be used beyond the edges of the interpolation domain.

AvailableLookupScheme

Enumeration of types of behaviour to be used beyond the edges of the interpolation domain.

LagrangeInterpolatorBoundaryHandling

Enumeration of types of behaviour to be used close to the edges of the interpolation domain, for the Lagrange interpolator.

class BoundaryInterpolationType

Enumeration of types of behaviour to be used beyond the edges of the interpolation domain.

Enumeration of types of behaviour to be used beyond the edges of the interpolation domain. For independent variable data in the range \([t_{0}...t_{N}]\), this enum is used to define the behaviour of the interpolator at \(t<t_{0}\) and \(t>t_{N}\)

Members:

throw_exception_at_boundary :

The program will terminate with an error message when the interpolator is interrogated beyond the range \([t_{0}...t_{N}]\)

use_boundary_value :

The value \(\mathbf{x}_{0}\) is returned for \(t<t_{0}\) (and \(\mathbf{x}_{N}\) if \(t>t_{N}\))

use_boundary_value_with_warning :

Same as use_boundary_value, but a warning is printed to the terminal

extrapolate_at_boundary :

The interpolation scheme is extended beyond the range \(t_{0}...t_{N}\) without any warning. That is, the mathematical equation used to compute the value of \(x\) in the range \([t_{0}...t_{1}]\) is used without any checks for \(t<t_{0}\) (and equivalently for \(t>t_{N}\)). Warning, using this setting can result in divergent/unrealistic behaviour

extrapolate_at_boundary_with_warning :

Same as extrapolate_at_boundary, but a warning is printed to the terminal

property name
class AvailableLookupScheme

Enumeration of types of behaviour to be used beyond the edges of the interpolation domain.

When the interpolation is performed, the interpolator scheme will typically start by finding the nearest neighbor of the requested value of the independent variable \(t\) in the data set \([t_{0}...t_{N}]\). The choice of lookup scheme can have a significant influence on computational efficiency for large data sets and/or simple interpolation algorithms

Members:

hunting_algorithm :

With this option, the interpolator ‘remembers’ which value of \(t_{i}\) was the nearest neighbor during the previous call to the interpolate function, and starts looking at/near this entry of the data set \([t_{i}]\) to find the nearest neighbor.

binary_search :

With this option, the algorithm uses a binary search algorithm to find the nearest neighbor, initially starting with the full data range \([t_{0}...t_{N}]\).

property name
class LagrangeInterpolatorBoundaryHandling

Enumeration of types of behaviour to be used close to the edges of the interpolation domain, for the Lagrange interpolator.

Enumeration of types of behaviour to be used close to the edges of the interpolation domain, for the Lagrange interpolator. As explained for lagrange_interpolation(), the algorithm for the Lagrange interpolation breaks down at the edges of the interpolation domain. This enum provides the available options a user has to deal with this.

Members:

lagrange_cubic_spline_boundary_interpolation :

A cubic-spline interpolator is created from the first and last \(\max(m/2-1,4)\) data points of the full data set, and these cubic spline interpolators are used when an interpolation at \(t<t_{(m/2-1)}\) or \(t<t_{N-(m/2)}\) is called

lagrange_no_boundary_interpolation :

The program will terminate with an exception when the Lagrange interpolator is interrogated beyond its valid range

property name

Classes

InterpolatorSettings

Base class to define settings for an interpolator.

LagrangeInterpolatorSettings

InterpolatorSettings-derived class to define settings for a Lagrange interpolator.

OneDimensionalInterpolatorScalar

Object that performs interpolation for scalar independent, and scalar dependent variables.

OneDimensionalInterpolatorVector

Object that performs interpolation for vector independent, and vector dependent variables.

OneDimensionalInterpolatorMatrix

Object that performs interpolation for matrix independent, and matrix dependent variables.

class InterpolatorSettings

Base class to define settings for an interpolator.

class LagrangeInterpolatorSettings

InterpolatorSettings-derived class to define settings for a Lagrange interpolator.

class OneDimensionalInterpolatorScalar

Object that performs interpolation for scalar independent, and scalar dependent variables.

Object that performs interpolation for scalar independent, and scalar dependent variables. This object is not created manually, but is set up using the create_one_dimensional_scalar_interpolator() function.

interpolate(self: tudatpy.kernel.math.interpolators.OneDimensionalInterpolatorScalar, independent_variable_value: float) float

This function performs the interpolation at the requested independent variable value.

Parameters:

independent_variable_value (float) – Value of independent variable at which the interpolation is to bse performed.

Returns:

Interpolated dependent variable value, using implemented algorithm at requested independent variable value

Return type:

float

class OneDimensionalInterpolatorVector

Object that performs interpolation for vector independent, and vector dependent variables.

Object that performs interpolation for vector independent, and vector dependent variables. This object is not created manually, but is set up using the create_one_dimensional_vector_interpolator() function.

interpolate(self: tudatpy.kernel.math.interpolators.OneDimensionalInterpolatorVector, independent_variable_value: float) numpy.ndarray[numpy.float64[m, 1]]

This function performs the interpolation at the requested independent variable value.

Parameters:

independent_variable_value (float) – Value of independent variable at which the interpolation is to be performed.

Returns:

Interpolated dependent variable value, using implemented algorithm at requested independent variable value

Return type:

np.array

class OneDimensionalInterpolatorMatrix

Object that performs interpolation for matrix independent, and matrix dependent variables.

Object that performs interpolation for matrix independent, and matrix dependent variables. This object is not created manually, but is set up using the create_one_dimensional_matrix_interpolator() function.

interpolate(self: tudatpy.kernel.math.interpolators.OneDimensionalInterpolatorMatrix, independent_variable_value: float) numpy.ndarray[numpy.float64[m, n]]

This function performs the interpolation at the requested independent variable value.

Parameters:

independent_variable_value (float) – Value of independent variable at which the interpolation is to be performed.

Returns:

Interpolated dependent variable value, using implemented algorithm at requested independent variable value

Return type:

np.array