Interpolation

Interpolation helpers convert solver profiles from the path domain into arrival times t(s) and sampled inverse trajectories s(t).

Second Order

copp_py.interpolation.a_to_b_topp2(s, a)

Compute the segment acceleration-like profile b from a TOPP2/COPP2 node profile a.

For each segment [s[k], s[k + 1]], this returns b[k] = 0.5 * (a[k + 1] - a[k]) / (s[k + 1] - s[k]). In the TOPP2/COPP2 convention, a stores ds/dt squared at station nodes, while b stores dds/dt on path segments.

Parameters:

  • s (ArrayLike) – One-dimensional station grid convertible to float64. Must be strictly increasing and contain at least two entries.

  • a (ArrayLike) – One-dimensional node profile convertible to float64 with len(a) == len(s). Values must be finite.

Returns:

Segment profile with length len(s) - 1.

Return type:

numpy.ndarray[numpy.float64]

Raises:

  • ValueError – If an input cannot be converted to a one-dimensional float64 array.

  • CoppError – If the COPP core rejects the grid or profile, for example because lengths differ, s is not strictly increasing, or values are not finite.

Examples

>>> import numpy as np
>>> import copp_py as copp
>>> s = np.array([0.0, 0.5, 1.0], dtype=np.float64)
>>> a = np.array([1.0, 1.0, 1.0], dtype=np.float64)
>>> copp.a_to_b_topp2(s, a)
array([0., 0.])
copp_py.interpolation.s_to_t_topp2(s, a, t0=0.0)

Integrate a TOPP2/COPP2 node profile a(s) into cumulative arrival times t(s).

The returned array t_s satisfies t_s[i] == t(s[i]) and starts from t_s[0] == t0. The scalar t_final is equal to t_s[-1].

Parameters:

  • s (ArrayLike) – One-dimensional station grid convertible to float64. Must be strictly increasing and contain at least two entries.

  • a (ArrayLike) – One-dimensional node profile convertible to float64 with len(a) == len(s). Values must be finite and non-negative. Each interval must have a positive finite speed denominator.

  • t0 (float, default=0.0) – Initial time assigned to s[0].

Returns:

(t_final, t_s) where t_s has the same length as s.

Return type:

tuple[float, numpy.ndarray[numpy.float64]]

Raises:

  • ValueError – If an input cannot be converted to a one-dimensional float64 array.

  • CoppError – If the COPP core rejects the grid, profile, or time initial condition.

Notes

This routine uses the same deterministic trapezoid-like TOPP2 timing model as the Rust API. It does not resample the trajectory; it only computes the arrival time at the provided station nodes.

copp_py.interpolation.t_to_s_topp2_uniform(s, a, t_s, dt, *, t0=0.0, include_final=True)

Sample the inverse TOPP2/COPP2 mapping s(t) on a uniform time grid.

This explicit entry point is preferred over the compatibility wrapper [t_to_s_topp2] when the query grid is generated from a time step.

copp_py.interpolation.t_to_s_topp2_samples(s, a, t_s, t_sample)

Sample the inverse TOPP2/COPP2 mapping s(t) at explicit query times.

This explicit entry point is preferred over the compatibility wrapper [t_to_s_topp2] when the query grid is supplied by the caller.

copp_py.interpolation.t_to_s_topp2(s, a, t_s, *, t0=0.0, dt=None, include_final=True, t_sample=None)

Compatibility wrapper for sampling inverse TOPP2/COPP2 mappings.

New code should prefer [t_to_s_topp2_uniform] or [t_to_s_topp2_samples], which avoid mutually exclusive keyword modes.

Exactly one sampling mode must be selected:

  • pass dt for a uniform time grid starting at t0;

  • pass t_sample for an explicit strictly increasing nonuniform time grid.

Out-of-range query times are returned as NaN by the COPP core.

Parameters:

  • s (ArrayLike) – One-dimensional station grid convertible to float64. Values must be strictly increasing.

  • a (ArrayLike) – One-dimensional TOPP2/COPP2 node profile convertible to float64. Must have the same length as s.

  • t_s (ArrayLike) – One-dimensional arrival-time profile convertible to float64, usually returned by s_to_t_topp2. Must have the same length as s and be strictly increasing.

  • t0 (float, default=0.0) – Start time for uniform-grid sampling. Ignored when t_sample is provided.

  • dt (float | None, default=None) – Positive uniform time step. Mutually exclusive with t_sample.

  • include_final (bool, default=True) – When using dt, append s[-1] if the generated uniform grid does not already include the final station.

  • t_sample (ArrayLike | None, default=None) – Explicit nonuniform query times. Must be one-dimensional, finite, non-empty, and strictly increasing. Mutually exclusive with dt.

Returns:

Sampled station values s(t).

Return type:

numpy.ndarray[numpy.float64]

Raises:

  • ValueError – If inputs cannot be converted to one-dimensional float64 arrays, if neither sampling mode is selected, or if both dt and t_sample are provided.

  • CoppError – If the COPP core rejects the grid, profile, arrival times, or sampling parameters.

Examples

>>> import numpy as np
>>> import copp_py as copp
>>> s = np.array([0.0, 0.5, 1.0], dtype=np.float64)
>>> a = np.array([1.0, 1.0, 1.0], dtype=np.float64)
>>> _, t_s = copp.s_to_t_topp2(s, a)
>>> copp.t_to_s_topp2_uniform(s, a, t_s, 0.25)
array([0.  , 0.25, 0.5 , 0.75, 1.  ])

Third Order

class copp_py.interpolation.Profile3rd(a, b, num_stationary=(0, 0))

Bases: object

Python-owned third-order TOPP/COPP profile.

The object stores node profiles a = (ds/dt)^2 and b = dds/dt, plus stationary boundary interval counts. It owns copies of the input arrays so later mutation of user-provided NumPy arrays cannot silently change solver inputs.

a

Return a copy of the node profile a = (ds/dt)^2.

b

Return a copy of the node profile b = dds/dt.

len

Return the number of station nodes in the profile.

num_stationary

Return stationary boundary interval counts as (start, end).

num_stationary_end

Return the number of stationary intervals at the end boundary.

num_stationary_start

Return the number of stationary intervals at the start boundary.

copp_py.interpolation.s_to_t_topp3(s, profile, t0=0.0)

Integrate a TOPP3/COPP3 profile into cumulative arrival times t(s).

The input profile is node-based: both profile.a and profile.b must have the same length as s. The returned array t_s satisfies t_s[i] == t(s[i]) and starts from t_s[0] == t0. The scalar t_final is equal to t_s[-1].

Parameters:

  • s (ArrayLike) – One-dimensional station grid convertible to float64. Values must be strictly increasing.

  • profile (Profile3rd) – Third-order profile containing node samples of a = (ds/dt)^2 and b = dds/dt plus stationary boundary counts.

  • t0 (float, default=0.0) – Initial time assigned to s[0].

Returns:

(t_final, t_s) where t_s has the same length as s.

Return type:

tuple[float, numpy.ndarray[numpy.float64]]

Raises:

  • ValueError – If s cannot be converted to a one-dimensional float64 array.

  • CoppError – If the COPP core rejects the grid, profile, stationary counts, or time initial condition.

copp_py.interpolation.t_to_s_topp3_uniform(s, profile, t_s, dt, *, t0=0.0, include_final=True)

Sample the inverse TOPP3/COPP3 mapping s(t) on a uniform time grid.

This explicit entry point is preferred over the compatibility wrapper [t_to_s_topp3] when the query grid is generated from a time step.

copp_py.interpolation.t_to_s_topp3_samples(s, profile, t_s, t_sample)

Sample the inverse TOPP3/COPP3 mapping s(t) at explicit query times.

This explicit entry point is preferred over the compatibility wrapper [t_to_s_topp3] when the query grid is supplied by the caller.

copp_py.interpolation.t_to_s_topp3(s, profile, t_s, *, t0=0.0, dt=None, include_final=True, t_sample=None)

Compatibility wrapper for sampling inverse TOPP3/COPP3 mappings.

New code should prefer [t_to_s_topp3_uniform] or [t_to_s_topp3_samples], which avoid mutually exclusive keyword modes.

Exactly one sampling mode must be selected:

  • pass dt for a uniform time grid starting at t0;

  • pass t_sample for an explicit strictly increasing nonuniform time grid.

Out-of-range query times are returned as NaN by the COPP core.

Parameters:

  • s (ArrayLike) – One-dimensional station grid convertible to float64. Values must be strictly increasing.

  • profile (Profile3rd) – Third-order profile used to integrate and invert the time mapping.

  • t_s (ArrayLike) – One-dimensional arrival-time profile convertible to float64, usually returned by s_to_t_topp3. Must have the same length as s and be strictly increasing.

  • t0 (float, default=0.0) – Start time for uniform-grid sampling. Ignored when t_sample is provided.

  • dt (float | None, default=None) – Positive uniform time step. Mutually exclusive with t_sample.

  • include_final (bool, default=True) – When using dt, append s[-1] if the generated uniform grid does not already include the final station.

  • t_sample (ArrayLike | None, default=None) – Explicit nonuniform query times. Must be one-dimensional, finite, non-empty, and strictly increasing. Mutually exclusive with dt.

Returns:

Sampled station values s(t).

Return type:

numpy.ndarray[numpy.float64]

Raises:

  • ValueError – If inputs cannot be converted to one-dimensional float64 arrays, if neither sampling mode is selected, or if both dt and t_sample are provided.

  • CoppError – If the COPP core rejects the grid, profile, arrival times, or sampling parameters.