CHSPy (Cubic Hermite Splines for Python)

This module provides Python tools for cubic Hermite splines with one argument (time) and multiple values (\(ℝ→ℝ^n\)). It was branched of from JiTCDDE, which uses it for representing the past of a delay differential equation. CHSPy is not optimised for efficiency, however it should be faily effective for high-dimensionally valued splines.

Each spline (CubicHermiteSpline) is stored as a series of anchors (using the Anchor class) each of which contains:

  • a time point (time),
  • an \(n\)-dimensional state (state),
  • an \(n\)-dimensional temporal derivative (diff).

Between such anchors, the spline is uniquely described by a polynomial of third degree. With other words, the spline is a piecewise Cubic Hermite interpolant of its anchors.

Command Reference

class Anchor(*args)

Class for a single anchor. Behaves mostly like a tuple, except that the respective components can also be accessed via the attributes time, state, and diff, and some copying and checks are performed upon creation.

interpolate(t, i, anchors)

Returns the i-th value of a cubic Hermite interpolant of the anchors at time t.

interpolate_vec(t, anchors)

Returns all values of a cubic Hermite interpolant of the anchors at time t.

interpolate_diff(t, i, anchors)

Returns the i-th component of the derivative of a cubic Hermite interpolant of the anchors at time t.

interpolate_diff_vec(t, anchors)

Returns the derivative of a cubic Hermite interpolant of the anchors at time t.

norm_sq_interval(anchors, indices)

Returns the squared norm of the interpolant of anchors for the indices.

norm_sq_partial(anchors, indices, start)

Returns the sqared norm of the interpolant of anchors for the indices, but only taking into account the time after start.

scalar_product_interval(anchors, indices_1, indices_2)

Returns the scalar product of the interpolants of anchors for indices_1 (one side of the product) and indices_2 (other side).

scalar_product_partial(anchors, indices_1, indices_2, start)

Returns the scalar product of the interpolants of anchors for indices_1 (one side of the product) and indices_2 (other side), but only taking into account the time after start.

class Extrema(n)

Class for containing the extrema and their positions in n dimensions. These can be accessed via the attributes minima, maxima, arg_min, and arg_max.

update(self, times, values, condition=True)

Updates the extrema if values are more extreme.

Parameters:
condition : boolean or array of booleans

Only the components where this is True are updated.

extrema_from_anchors(anchors, beginning=None, end=None, target=None)

Finds minima and maxima of the Hermite interpolant for the anchors.

Parameters:
beginning : float or None

Beginning of the time interval for which extrema are returned. If None, the time of the first anchor is used.

end : float or None

End of the time interval for which extrema are returned. If None, the time of the last anchor is used.

target : Extrema or None

If an Extrema instance, this one is updated with the newly found extrema and also returned (which means that newly found extrema will be ignored when the extrema in target are more extreme).

Returns:
extrema: Extrema object

An Extrema instance containing the extrema and their positions.

class CubicHermiteSpline(n=None, anchors=())

Class for a cubic Hermite Spline of one variable (time) with n values. This behaves like a list with additional functionalities and checks. Note that the times of the anchors must always be in ascending order.

Parameters:
n : integer

Dimensionality of the values. If None, the following argument must be an instance of CubicHermiteSpline.

anchors : iterable of triplets

Contains all the anchors with which the spline is initiated. If n is None and this is an instance of CubicHermiteSpline, all properties are copied from it.

append(self, anchor)

Append object to the end of the list.

extend(self, anchors)

Extend list by appending elements from the iterable.

copy(self)

Return a shallow copy of the list.

insert(self, key, item)

Insert object before index.

sort(self)

Stable sort IN PLACE.

add(self, anchor)

Inserts anchor at the appropriate time.

clear_from(self, n)

Removes all anchors with an index of n or higher.

clear(self)

Remove all items from list.

reverse(self)

Reverse IN PLACE.

t

The time of the last anchor. This may be overwritten in subclasses.

last_index_before(self, time)

Returns the index of the last anchor before time. Returns the first anchor if time is before the first anchor.

constant(self, state, time=0)

makes the spline constant, removing possibly previously existing anchors.

Parameters:
state : iterable of floats
time : float

The time of the last point.

from_function(self, function, times_of_interest=None, max_anchors=100, tol=5)

makes the spline interpolate a given function at heuristically determined points.More precisely, starting with times_of_interest, anchors are added until either:

  • anchors are closer than the tolerance
  • the value of an anchor is approximated by the interpolant of its neighbours within the tolerance
  • the maximum number of anchors is reached.

This removes possibly previously existing anchors.

Parameters:
function : callable or iterable of SymPy/SymEngine expressions

The function to be interpolated. If callable, this is interpreted like a regular function. If an iterable of expressions, each expression represents the respective component of the function.

times_of_interest : iterable of numbers

Initial set of time points considered for the interpolation. All created anhcors will between the minimal and maximal timepoint.

max_anchors : positive integer

The maximum number of anchors that this routine will create (including those for the times_of_interest).

tol : integer

This is a parameter for the heuristics, more precisely the number of digits considered for tolerance in several places.

get_anchors(self, time)

Find the two anchors neighbouring time. If time is outside the ranges of times covered by the anchors, return the two nearest anchors.

get_state(self, time)

Get the state of the spline at time. If time lies outside of the anchors, the state will be extrapolated.

get_recent_state(self, t)

Interpolate the state at time t from the last two anchors. This usually only makes sense if t lies between the last two anchors.

forget(self, delay)

Remove all anchors that are “out of reach” of the delay with respect to self.t.

extrema(self, beginning=None, end=None)

Returns the positions and values of the minima and maxima of the spline (for each component) within the specified time interval.

Parameters:
beginning : float or None

Beginning of the time interval for which extrema are returned. If None, the time of the first anchor is used.

end : float or None

End of the time interval for which extrema are returned. If None, the time of the last anchor is used.

Returns:
extrema: Extrema object

An Extrema instance containing the extrema and their positions.

norm(self, delay, indices)

Computes the norm of the spline for the given indices taking into account the time between self.tdelay and self.t.

scalar_product(self, delay, indices_1, indices_2)

Computes the scalar product of the spline between indices_1 (one side of the product) and indices_2 (other side) taking into account the time between self.tdelay and self.t.

scale(self, indices, factor)

Scales the spline for indices by factor.

subtract(self, indices_1, indices_2, factor)

Substract the spline for indices_2 multiplied by factor from the spline for indices_1.

truncate(self, time)

Interpolates an anchor at time and removes all later anchors.