API reference¶

This page documents the supported Python API for InterpolatePy 3.2.1. Import these objects from interpolatepy unless a module-qualified exception is shown.

Backend-dependent class identity

MkDocs renders the Python implementation docstrings. The package root may resolve computation-heavy names to native adapter classes when HAS_CPP=True. The adapters align the primary construction and evaluation workflows, but some diagnostic and convenience methods remain Python-only; see Architecture for current limitations.

Package information¶

interpolatepy.__version__ contains the installed version and interpolatepy.HAS_CPP reports backend selection.

Scalar splines¶

CubicSpline¶

interpolatepy.CubicSpline ¶

CubicSpline(
    t_points: list[float] | ndarray,
    q_points: list[float] | ndarray,
    v0: float = 0.0,
    vn: float = 0.0,
    debug: bool = False,
)

Cubic spline trajectory planning implementation.

The piecewise-cubic trajectory passes through the supplied waypoints, matches the requested endpoint velocities, and maintains continuous velocity and acceleration at interior knots.

Parameters:

Name	Type	Description	Default
`t_points`	`list or ndarray`	List or array of time points (t0, t1, ..., tn)	required
`q_points`	`list or ndarray`	List or array of position points (q0, q1, ..., qn)	required
`v0`	`float`	Initial velocity at t0. Default is 0.0	`0.0`
`vn`	`float`	Final velocity at tn. Default is 0.0	`0.0`
`debug`	`bool`	Whether to print debug information. Default is False	`False`

Attributes:

Name	Type	Description
`t_points`	`ndarray`	Array of time points
`q_points`	`ndarray`	Array of position points
`v0`	`float`	Initial velocity
`vn`	`float`	Final velocity
`debug`	`bool`	Debug flag
`n`	`int`	Number of segments (n = len(t_points) - 1)
`t_intervals`	`ndarray`	Time intervals between consecutive points
`velocities`	`ndarray`	Velocities at each waypoint
`coefficients`	`ndarray`	Polynomial coefficients for each segment

Notes

The cubic spline ensures C2 continuity (continuous position, velocity, and acceleration) across all waypoints.

Examples:

>>> import numpy as np
>>> # Define waypoints
>>> t_points = [0, 1, 2, 3]
>>> q_points = [0, 1, 0, 1]
>>> # Create spline
>>> spline = CubicSpline(t_points, q_points)
>>> # Evaluate at specific time
>>> spline.evaluate(1.5)
>>> # Plot the trajectory
>>> spline.plot()

Parameters:

Name	Type	Description	Default
`t_points`	`list or ndarray`	List or array of time points (t0, t1, ..., tn)	required
`q_points`	`list or ndarray`	List or array of position points (q0, q1, ..., qn)	required
`v0`	`float`	Initial velocity at t0. Default is 0.0	`0.0`
`vn`	`float`	Final velocity at tn. Default is 0.0	`0.0`
`debug`	`bool`	Whether to print debug information. Default is False	`False`

Raises:

Type	Description
`ValueError`	If t_points and q_points have different lengths If t_points are not strictly increasing

evaluate ¶

evaluate(t: float | ndarray) -> float | ndarray

Evaluate the spline at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Position(s) at the specified time(s)

Examples:

>>> # Evaluate at a single time point
>>> spline.evaluate(1.5)
>>> # Evaluate at multiple time points
>>> spline.evaluate(np.linspace(0, 3, 100))

evaluate_velocity ¶

evaluate_velocity(t: float | ndarray) -> float | ndarray

Evaluate the velocity at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Velocity at the specified time(s)

Examples:

>>> # Evaluate velocity at a single time point
>>> spline.evaluate_velocity(1.5)
>>> # Evaluate velocity at multiple time points
>>> spline.evaluate_velocity(np.linspace(0, 3, 100))

evaluate_acceleration ¶

evaluate_acceleration(
    t: float | ndarray,
) -> float | ndarray

Evaluate the acceleration at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Acceleration at the specified time(s)

Examples:

>>> # Evaluate acceleration at a single time point
>>> spline.evaluate_acceleration(1.5)
>>> # Evaluate acceleration at multiple time points
>>> spline.evaluate_acceleration(np.linspace(0, 3, 100))

plot ¶

plot(num_points: int = 1000) -> None

Plot the spline trajectory along with its velocity and acceleration profiles.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to use for plotting. Default is 1000	`1000`

Returns:

Type	Description
`None`	Displays the plot using matplotlib

Notes

This method creates a figure with three subplots showing: 1. Position trajectory with waypoints 2. Velocity profile 3. Acceleration profile

The original waypoints are marked with red circles on the position plot.

CubicSmoothingSpline¶

interpolatepy.CubicSmoothingSpline ¶

CubicSmoothingSpline(
    t_points: list[float],
    q_points: list[float],
    mu: float = 0.5,
    weights: list[float] | None = None,
    v0: float = 0.0,
    vn: float = 0.0,
    debug: bool = False,
)

Cubic smoothing spline trajectory planning with control over the smoothness versus waypoint accuracy trade-off.

The algorithm minimizes a weighted combination of waypoint residuals and curve roughness. The parameter μ controls the trade-off between smoothness and waypoint accuracy.

Parameters:

Name	Type	Description	Default
`t_points`	`list[float] or array_like`	Time points [t₀, t₁, t₂, ..., tₙ] for the spline knots.	required
`q_points`	`list[float] or array_like`	Position points [q₀, q₁, q₂, ..., qₙ] at each time point.	required
`mu`	`float`	Trade-off parameter between accuracy (μ=1) and smoothness (μ=0). Must be in range (0, 1]. Default is 0.5.	`0.5`
`weights`	`list[float] or array_like`	Individual point weights [w₀, w₁, ..., wₙ]. Higher values enforce closer approximation at corresponding points. Default is None (equal weights of 1.0 for all points).	`None`
`v0`	`float`	Initial velocity constraint at t₀. Default is 0.0.	`0.0`
`vn`	`float`	Final velocity constraint at tₙ. Default is 0.0.	`0.0`
`debug`	`bool`	Whether to print debug information. Default is False.	`False`

Attributes:

Name	Type	Description
`t`	`ndarray`	Time points array.
`q`	`ndarray`	Original position points array.
`s`	`ndarray`	Approximated position points array.
`mu`	`float`	Smoothing parameter value.
`lambd`	`float`	Lambda parameter derived from μ: λ = (1-μ)/(6μ).
`omega`	`ndarray`	Acceleration values at each time point.
`coeffs`	`ndarray`	Polynomial coefficients for each segment.

Raises:

Type	Description
`ValueError`	If time and position arrays have different lengths. If fewer than 2 points are provided. If time points are not strictly increasing. If parameter μ is outside the valid range (0, 1]. If weights array length doesn't match time and position arrays.

Notes

For μ=1, the spline performs exact interpolation. For μ approaching 0, the spline becomes increasingly smooth. Setting weight to infinity for a point forces exact interpolation at that point.

The implementation solves the banded smoothing-spline system directly, then reconstructs one cubic polynomial per time interval.

Parameters:

Name	Type	Description	Default
`t_points`	`list[float] or array_like`	Time points [t₀, t₁, t₂, ..., tₙ] for the spline knots.	required
`q_points`	`list[float] or array_like`	Position points [q₀, q₁, q₂, ..., qₙ] at each time point.	required
`mu`	`float`	Trade-off parameter between accuracy (μ=1) and smoothness (μ=0). Must be in range (0, 1]. Default is 0.5.	`0.5`
`weights`	`list[float] or array_like`	Individual point weights [w₀, w₁, ..., wₙ]. Higher values enforce closer approximation at corresponding points. Default is None (equal weights of 1.0 for all points).	`None`
`v0`	`float`	Initial velocity constraint at t₀. Default is 0.0.	`0.0`
`vn`	`float`	Final velocity constraint at tₙ. Default is 0.0.	`0.0`
`debug`	`bool`	Whether to print debug information. Default is False.	`False`

Raises:

Type	Description
`ValueError`	If time and position arrays have different lengths. If fewer than 2 points are provided. If time points are not strictly increasing. If parameter μ is outside the valid range (0, 1]. If weights array length doesn't match time and position arrays.

evaluate ¶

evaluate(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the spline at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or list[float] or ndarray`	Time point or array of time points at which to evaluate the spline.	required

Returns:

Type	Description
`float or ndarray`	Position(s) at the specified time(s). Returns a scalar if input is a scalar, otherwise returns an array matching the shape of input.

Notes

For t < t₀ or t > tₙ, the function extrapolates using the first or last segment respectively.

evaluate_velocity ¶

evaluate_velocity(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the velocity at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or list[float] or ndarray`	Time point or array of time points at which to evaluate velocity.	required

Returns:

Type	Description
`float or ndarray`	Velocity at the specified time(s). Returns a scalar if input is a scalar, otherwise returns an array matching the shape of input.

Notes

Computes the first derivative of the spline at the given time(s). For t < t₀ or t > tₙ, the function extrapolates using the first or last segment respectively.

evaluate_acceleration ¶

evaluate_acceleration(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the acceleration at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or list[float] or ndarray`	Time point or array of time points at which to evaluate acceleration.	required

Returns:

Type	Description
`float or ndarray`	Acceleration at the specified time(s). Returns a scalar if input is a scalar, otherwise returns an array matching the shape of input.

Notes

Computes the second derivative of the spline at the given time(s). For t < t₀ or t > tₙ, the function extrapolates using the first or last segment respectively.

plot ¶

plot(num_points: int = 1000) -> None

Plot the spline trajectory with velocity and acceleration profiles.

Creates a three-panel figure showing position, velocity, and acceleration profiles over time.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points for smooth plotting. Default is 1000.	`1000`

Returns:

Type	Description
`None`	Displays the plot using matplotlib's show() function.

Notes

The plot includes: - Top panel: position trajectory with original waypoints and approximated points - Middle panel: velocity profile - Bottom panel: acceleration profile

Smoothing tolerance search¶

interpolatepy.SplineConfig `dataclass` ¶

SplineConfig(
    weights: list[float] | ndarray | None = None,
    v0: float = 0.0,
    vn: float = 0.0,
    max_iterations: int = 50,
    debug: bool = False,
)

Configuration parameters for smoothing spline calculation.

interpolatepy.smoothing_spline_with_tolerance ¶

smoothing_spline_with_tolerance(
    t_points: ndarray,
    q_points: ndarray,
    tolerance: float,
    config: SplineConfig,
) -> tuple[CubicSmoothingSpline, float, float, int]

Find a cubic smoothing spline with a maximum approximation error smaller than a given tolerance using binary search on the μ parameter.

This implements the algorithm for "Smoothing spline with prescribed tolerance".

Parameters:

Name	Type	Description	Default
`t_points`	`ndarray`	Time points [t₀, t₁, t₂, ..., tₙ]	required
`q_points`	`ndarray`	Position points [q₀, q₁, q₂, ..., qₙ]	required
`tolerance`	`float`	Maximum allowed approximation error δ between original and smoothed points	required
`config`	`SplineConfig`	Configuration object with optional parameters: - weights: Individual point weights [w₀, w₁, ..., wₙ] (None = equal weights) - v0: Initial velocity constraint at t₀ - vn: Final velocity constraint at tₙ - max_iterations: Maximum number of iterations for the binary search - debug: Whether to print debug information	required

Returns:

Name	Type	Description
`spline`	`CubicSmoothingSpline`	The final CubicSmoothingSpline object
`mu`	`float`	The found value of μ parameter
`e_max`	`float`	The maximum approximation error achieved
`iterations`	`int`	Number of iterations performed

Examples:

>>> import numpy as np
>>> from interpolatepy.c_s_smoothing import CubicSmoothingSpline
>>> # Create sample data
>>> t = np.linspace(0, 10, 100)
>>> q = np.sin(t) + 0.1 * np.random.randn(100)
>>> config = SplineConfig(max_iterations=20)
>>> # Find spline with tolerance of 0.05
>>> spline, mu, error, iterations = smoothing_spline_with_tolerance(t, q, 0.05, config)
>>> print(f"Found spline with μ={mu:.6f}, error={error:.6f} in {iterations} iterations")

Notes

The algorithm uses binary search to find the optimal μ parameter value that produces a smoothing spline with maximum error below the specified tolerance. The parameter μ controls the trade-off between smoothness and accuracy, with values closer to 0 producing smoother curves and values closer to 1 producing more accurate but less smooth curves.

CubicSplineWithAcceleration1¶

interpolatepy.CubicSplineWithAcceleration1 ¶

CubicSplineWithAcceleration1(
    t_points: list[float],
    q_points: list[float],
    v0: float = 0.0,
    vn: float = 0.0,
    a0: float = 0.0,
    an: float = 0.0,
    debug: bool = False,
)

Cubic spline trajectory planning with both velocity and acceleration constraints at endpoints.

This construction adds virtual points in the first and last segments so the resulting cubic pieces satisfy the requested endpoint accelerations.

Parameters:

Name	Type	Description	Default
`t_points`	`list of float or numpy.ndarray`	Time points [t₀, t₂, t₃, ..., tₙ₋₂, tₙ]	required
`q_points`	`list of float or numpy.ndarray`	Position points [q₀, q₂, q₃, ..., qₙ₋₂, qₙ]	required
`v0`	`float`	Initial velocity at t₀. Default is 0.0	`0.0`
`vn`	`float`	Final velocity at tₙ. Default is 0.0	`0.0`
`a0`	`float`	Initial acceleration at t₀. Default is 0.0	`0.0`
`an`	`float`	Final acceleration at tₙ. Default is 0.0	`0.0`
`debug`	`bool`	Whether to print debug information. Default is False	`False`

Attributes:

Name	Type	Description
`t_orig`	`ndarray`	Original time points
`q_orig`	`ndarray`	Original position points
`v0`	`float`	Initial velocity
`vn`	`float`	Final velocity
`a0`	`float`	Initial acceleration
`an`	`float`	Final acceleration
`debug`	`bool`	Debug flag
`n_orig`	`int`	Number of original points
`t`	`ndarray`	Time points including extra points
`q`	`ndarray`	Position points including extra points
`n`	`int`	Total number of points including extras
`T`	`ndarray`	Time intervals between consecutive points
`omega`	`ndarray`	Acceleration values at each point
`coeffs`	`ndarray`	Polynomial coefficients for each segment
`original_indices`	`list`	Indices of original points in expanded arrays

Notes

This implementation adds two extra points (at t₁ and tₙ₋₁) to the trajectory to satisfy both velocity and acceleration constraints at the endpoints. The extra points are placed at the midpoints of the first and last segments of the original trajectory.

The acceleration (omega) values are computed by solving a tridiagonal system that ensures C2 continuity throughout the trajectory.

Examples:

>>> import numpy as np
>>> # Define waypoints
>>> t_points = [0, 1, 2, 3]
>>> q_points = [0, 1, 0, 1]
>>> # Create spline with velocity and acceleration constraints
>>> spline = CubicSplineWithAcceleration1(t_points, q_points, v0=0.0, vn=0.0, a0=0.0, an=0.0)
>>> # Evaluate at specific time
>>> spline.evaluate(1.5)
>>> # Plot the trajectory
>>> spline.plot()

Parameters:

Name	Type	Description	Default
`t_points`	`list of float or numpy.ndarray`	Time points [t₀, t₂, t₃, ..., tₙ₋₂, tₙ]	required
`q_points`	`list of float or numpy.ndarray`	Position points [q₀, q₂, q₃, ..., qₙ₋₂, qₙ]	required
`v0`	`float`	Initial velocity at t₀. Default is 0.0	`0.0`
`vn`	`float`	Final velocity at tₙ. Default is 0.0	`0.0`
`a0`	`float`	Initial acceleration at t₀. Default is 0.0	`0.0`
`an`	`float`	Final acceleration at tₙ. Default is 0.0	`0.0`
`debug`	`bool`	Whether to print debug information. Default is 0.0	`False`

Raises:

Type	Description
`ValueError`	If time and position arrays have different lengths If fewer than two points are provided If time points are not strictly increasing

evaluate ¶

evaluate(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the spline at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or array_like`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Position(s) at the specified time(s)

Examples:

>>> # Evaluate at a single time point
>>> spline.evaluate(1.5)
>>> # Evaluate at multiple time points
>>> spline.evaluate(np.linspace(0, 3, 100))

evaluate_velocity ¶

evaluate_velocity(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the velocity at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or array_like`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Velocity at the specified time(s)

Examples:

>>> # Evaluate velocity at a single time point
>>> spline.evaluate_velocity(1.5)
>>> # Evaluate velocity at multiple time points
>>> spline.evaluate_velocity(np.linspace(0, 3, 100))

evaluate_acceleration ¶

evaluate_acceleration(
    t: float | list[float] | ndarray,
) -> float | ndarray

Evaluate the acceleration at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or array_like`	Time point or array of time points	required

Returns:

Type	Description
`float or ndarray`	Acceleration at the specified time(s)

Examples:

>>> # Evaluate acceleration at a single time point
>>> spline.evaluate_acceleration(1.5)
>>> # Evaluate acceleration at multiple time points
>>> spline.evaluate_acceleration(np.linspace(0, 3, 100))

plot ¶

plot(num_points: int = 1000) -> None

Plot the spline trajectory with velocity and acceleration profiles.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points for smooth plotting. Default is 1000	`1000`

Returns:

Type	Description
`None`	Displays the plot using matplotlib

Notes

This method creates a figure with three subplots showing: 1. Position trajectory with original and extra waypoints 2. Velocity profile with initial and final velocities marked 3. Acceleration profile with initial and final accelerations marked

Original waypoints are shown as red circles, while extra points are shown as green x-marks.

CubicSplineWithAcceleration2¶

interpolatepy.CubicSplineWithAcceleration2 ¶

CubicSplineWithAcceleration2(
    t_points: list[float] | ndarray,
    q_points: list[float] | ndarray,
    params: SplineParameters | None = None,
)

Bases: CubicSpline

Cubic spline trajectory planning with initial and final acceleration constraints.

This class extends CubicSpline with quintic first and last segments when endpoint acceleration constraints are supplied.

The spline consists of cubic polynomial segments for interior segments and optional quintic polynomial segments for the first and/or last segment when acceleration constraints are specified.

Parameters:

Name	Type	Description	Default
`t_points`	`array_like`	Array of time points (t0, t1, ..., tn).	required
`q_points`	`array_like`	Array of position points (q0, q1, ..., qn).	required
`params`	`SplineParameters`	Spline parameters including initial/final velocities and accelerations. If None, default parameters will be used.	`None`

Attributes:

Name	Type	Description
`t_points`	`ndarray`	Array of time points.
`q_points`	`ndarray`	Array of position points.
`velocities`	`ndarray`	Array of velocities at each point.
`t_intervals`	`ndarray`	Array of time intervals between consecutive points.
`n`	`int`	Number of segments.
`coefficients`	`ndarray`	Array of coefficients for each cubic segment.
`a0`	`float or None`	Initial acceleration constraint.
`an`	`float or None`	Final acceleration constraint.
`quintic_coeffs`	`dict`	Dictionary containing quintic coefficients for first and/or last segments.

Parameters:

Name	Type	Description	Default
`t_points`	`array_like`	Array of time points (t0, t1, ..., tn).	required
`q_points`	`array_like`	Array of position points (q0, q1, ..., qn).	required
`params`	`SplineParameters`	Spline parameters including initial/final velocities and accelerations. If None, default parameters will be used.	`None`

evaluate ¶

evaluate(t: float | ndarray) -> float | ndarray

Evaluate the spline at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points at which to evaluate the spline.	required

Returns:

Type	Description
`float or ndarray`	Position(s) at the specified time(s). Returns a float if a single time point is provided, or an ndarray if an array of time points is provided.

Notes

For time values outside the spline range: - If t < t_points[0], returns the position at t_points[0] - If t > t_points[-1], returns the position at t_points[-1]

For the first and last segments, quintic polynomials are used if acceleration constraints were specified. For all other segments, cubic polynomials are used.

evaluate_velocity ¶

evaluate_velocity(t: float | ndarray) -> float | ndarray

Evaluate the velocity at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points at which to evaluate the velocity.	required

Returns:

Type	Description
`float or ndarray`	Velocity at the specified time(s). Returns a float if a single time point is provided, or an ndarray if an array of time points is provided.

Notes

For time values outside the spline range: - If t < t_points[0], returns the velocity at t_points[0] - If t > t_points[-1], returns the velocity at t_points[-1]

For the first and last segments, derivatives of quintic polynomials are used if acceleration constraints were specified. For all other segments, derivatives of cubic polynomials are used.

evaluate_acceleration ¶

evaluate_acceleration(
    t: float | ndarray,
) -> float | ndarray

Evaluate the acceleration at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time point or array of time points at which to evaluate the acceleration.	required

Returns:

Type	Description
`float or ndarray`	Acceleration at the specified time(s). Returns a float if a single time point is provided, or an ndarray if an array of time points is provided.

Notes

For time values outside the spline range: - If t < t_points[0], returns the acceleration at t_points[0] - If t > t_points[-1], returns the acceleration at t_points[-1]

For the first and last segments, second derivatives of quintic polynomials are used if acceleration constraints were specified. For all other segments, second derivatives of cubic polynomials are used.

interpolatepy.SplineParameters `dataclass` ¶

SplineParameters(
    v0: float = 0.0,
    vn: float = 0.0,
    a0: float | None = None,
    an: float | None = None,
    debug: bool = False,
)

Container for spline initialization parameters.

Parameters:

Name	Type	Description	Default
`v0`	`float`	Initial velocity constraint at the start of the spline.	`0.0`
`vn`	`float`	Final velocity constraint at the end of the spline.	`0.0`
`a0`	`float`	Initial acceleration constraint at the start of the spline. If provided, the first segment will use a quintic polynomial.	`None`
`an`	`float`	Final acceleration constraint at the end of the spline. If provided, the last segment will use a quintic polynomial.	`None`
`debug`	`bool`	If True, prints detailed information about the spline calculation.	`False`

B-splines¶

BSpline¶

interpolatepy.BSpline ¶

BSpline(
    degree: int,
    knots: list | ndarray,
    control_points: list | ndarray,
)

A class for representing and evaluating B-spline curves.

Parameters:

Name	Type	Description	Default
`degree`	`int`	The degree of the B-spline.	required
`knots`	`array_like`	The knot vector.	required
`control_points`	`array_like`	The control points defining the B-spline.	required

Attributes:

Name	Type	Description
`degree`	`int`	The degree of the B-spline.
`knots`	`ndarray`	The knot vector.
`control_points`	`ndarray`	The control points defining the B-spline.
`u_min`	`float`	Minimum valid parameter value.
`u_max`	`float`	Maximum valid parameter value.
`dimension`	`int`	The dimension of the control points (2D, 3D, etc.).

Parameters:

Name	Type	Description	Default
`degree`	`int`	The degree of the B-spline (must be positive).	required
`knots`	`array_like`	The knot vector (must be non-decreasing).	required
`control_points`	`array_like`	The control points defining the B-spline. Can be multidimensional (e.g., 2D or 3D points).	required

Raises:

Type	Description
`ValueError`	If the inputs do not satisfy B-spline requirements.

repr ¶

__repr__() -> str

Return a string representation of the B-spline.

Returns:

Type	Description
`str`	String representation.

basis_function_derivatives ¶

basis_function_derivatives(
    u: float, span_index: int, order: int
) -> ndarray

Calculate derivatives of basis functions up to the specified order.

Parameters:

Name	Type	Description	Default
`u`	`float`	The parameter value.	required
`span_index`	`int`	The knot span index containing u.	required
`order`	`int`	The maximum order of derivatives to calculate.	required

Returns:

Type	Description
`ndarray`	2D array where ders[k][`j`] is the k-th derivative of the `j`-th basis function, where k is the derivative order and `j` is the basis function index.

basis_functions ¶

basis_functions(u: float, span_index: int) -> ndarray

Calculate all non-zero basis functions at parameter value u.

Parameters:

Name	Type	Description	Default
`u`	`float`	The parameter value.	required
`span_index`	`int`	The knot span index containing u.	required

Returns:

Type	Description
`ndarray`	Array of basis function values (p+1 values).

create_periodic_knots `staticmethod` ¶

create_periodic_knots(
    degree: int,
    num_control_points: int,
    domain_min: float = 0.0,
    domain_max: float = 1.0,
) -> ndarray

Create a periodic (uniform) knot vector for a B-spline.

Parameters:

Name	Type	Description	Default
`degree`	`int`	The degree of the B-spline.	required
`num_control_points`	`int`	The number of control points.	required
`domain_min`	`float`	Minimum value of the parameter domain. Default is 0.0.	`0.0`
`domain_max`	`float`	Maximum value of the parameter domain. Default is 1.0.	`1.0`

Returns:

Type	Description
`ndarray`	The periodic knot vector.

Raises:

Type	Description
`ValueError`	If degree is negative or num_control_points is less than degree+1.

create_uniform_knots `staticmethod` ¶

create_uniform_knots(
    degree: int,
    num_control_points: int,
    domain_min: float = 0.0,
    domain_max: float = 1.0,
) -> ndarray

Create a uniform knot vector for a B-spline with appropriate multiplicity at endpoints to ensure interpolation.

Parameters:

Name	Type	Description	Default
`degree`	`int`	The degree of the B-spline.	required
`num_control_points`	`int`	The number of control points.	required
`domain_min`	`float`	Minimum value of the parameter domain. Default is 0.0.	`0.0`
`domain_max`	`float`	Maximum value of the parameter domain. Default is 1.0.	`1.0`

Returns:

Type	Description
`ndarray`	The uniform knot vector with knots in the specified domain.

Raises:

Type	Description
`ValueError`	If degree is negative or num_control_points is less than or equal to degree.

evaluate ¶

evaluate(u: float) -> ndarray

Evaluate the B-spline curve at parameter value u.

Parameters:

Name	Type	Description	Default
`u`	`float`	The parameter value.	required

Returns:

Type	Description
`ndarray`	The point on the B-spline curve at parameter u.

evaluate_derivative ¶

evaluate_derivative(u: float, order: int = 1) -> ndarray

Evaluate the derivative of the B-spline curve at parameter value u.

Parameters:

Name	Type	Description	Default
`u`	`float`	The parameter value.	required
`order`	`int`	The order of the derivative. Default is 1.	`1`

Returns:

Type	Description
`ndarray`	The derivative of the B-spline curve at parameter u.

Raises:

Type	Description
`ValueError`	If the order is greater than the degree of the B-spline.

find_knot_span ¶

find_knot_span(u: float) -> int

Find the knot span index for a given parameter value u.

Parameters:

Name	Type	Description	Default
`u`	`float`	The parameter value.	required

Returns:

Type	Description
`int`	The index of the knot span containing u.

Raises:

Type	Description
`ValueError`	If u is outside the valid parameter range.

generate_curve_points ¶

generate_curve_points(
    num_points: int = 100,
) -> tuple[ndarray, ndarray]

Generate points along the B-spline curve for visualization.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate. Default is 100.	`100`

Returns:

Name	Type	Description
`u_values`	`ndarray`	Parameter values.
`curve_points`	`ndarray`	Corresponding points on the curve.

plot_2d ¶

plot_2d(
    num_points: int = 100,
    show_control_polygon: bool = True,
    show_knots: bool = False,
    ax: Axes | None = None,
) -> Axes

Plot a 2D B-spline curve with customizable styling.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate for the curve. Default is 100.	`100`
`show_control_polygon`	`bool`	Whether to show the control polygon. Default is True.	`True`
`show_knots`	`bool`	Whether to show the knot points on the curve. Default is False.	`False`
`ax`	`Axes`	Matplotlib axis to use for plotting. If None, a new figure is created.	`None`

Returns:

Type	Description
`Axes`	The matplotlib axis object.

Raises:

Type	Description
`ValueError`	If the dimension of control points is not 2.

plot_3d ¶

plot_3d(
    num_points: int = 100,
    show_control_polygon: bool = True,
    ax: Axes3D | None = None,
) -> Axes3D

Plot a 3D B-spline curve.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate for the curve. Default is 100.	`100`
`show_control_polygon`	`bool`	Whether to show the control polygon. Default is True.	`True`
`ax`	`Axes`	Matplotlib 3D axis to use for plotting. If None, a new figure is created.	`None`

Returns:

Type	Description
`Axes`	The matplotlib 3D axis object.

Raises:

Type	Description
`ValueError`	If the dimension of control points is not 3.

BSplineInterpolator¶

interpolatepy.BSplineInterpolator ¶

BSplineInterpolator(
    degree: int,
    points: list | ndarray,
    times: list | ndarray | None = None,
    initial_velocity: list | ndarray | None = None,
    final_velocity: list | ndarray | None = None,
    initial_acceleration: list | ndarray | None = None,
    final_acceleration: list | ndarray | None = None,
    cyclic: bool = False,
)

Bases: BSpline

A B-spline that interpolates a set of points with specified degrees of continuity.

This class inherits from BSpline and computes the knot vector and control points required to interpolate given data points at specified times, while maintaining desired continuity constraints.

The degree-specific knot and boundary-row construction supports: - Cubic splines (degree 3) with C² continuity - Quartic splines (degree 4) with C³ continuity (continuous jerk) - Quintic splines (degree 5) with C⁴ continuity (continuous snap)

Points can be of any dimension, including 2D and 3D.

Parameters:

Name	Type	Description	Default
`degree`	`int`	The degree of the B-spline (3, 4, or 5).	required
`points`	`list or ndarray`	The points to be interpolated.	required
`times`	`list or ndarray or None`	The time instants for each point. If None, uses uniform spacing.	`None`
`initial_velocity`	`list or ndarray or None`	Initial velocity constraint.	`None`
`final_velocity`	`list or ndarray or None`	Final velocity constraint.	`None`
`initial_acceleration`	`list or ndarray or None`	Initial acceleration constraint.	`None`
`final_acceleration`	`list or ndarray or None`	Final acceleration constraint.	`None`
`cyclic`	`bool`	Whether to use cyclic (periodic) conditions.	`False`

Raises:

Type	Description
`ValueError`	If the degree is not 3, 4, or 5.
`ValueError`	If there are not enough points for the specified degree.

plot_with_points ¶

plot_with_points(
    num_points: int = 100,
    show_control_polygon: bool = True,
    ax: Axes | None = None,
) -> Axes

Plot the 2D B-spline curve along with the interpolation points.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate for the curve.	`100`
`show_control_polygon`	`bool`	Whether to show the control polygon.	`True`
`ax`	`Axes or None`	Optional matplotlib axis to use.	`None`

Returns:

Type	Description
`Axes`	The matplotlib axis object.

Raises:

Type	Description
`ValueError`	If points are not 2D.

plot_with_points_3d ¶

plot_with_points_3d(
    num_points: int = 100,
    show_control_polygon: bool = True,
    ax: Axes3D | None = None,
) -> Axes3D

Plot the 3D B-spline curve along with the interpolation points.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate for the curve.	`100`
`show_control_polygon`	`bool`	Whether to show the control polygon.	`True`
`ax`	`Axes or None`	Optional matplotlib 3D axis to use.	`None`

Returns:

Type	Description
`Axes`	The matplotlib 3D axis object.

Raises:

Type	Description
`ValueError`	If points are not 3D.

Degrees 3, 4, and 5 accept two or more points. times defaults to generated parameters. Provide endpoint velocity or acceleration vectors when those derivatives need to be constrained.

CubicBSplineInterpolation¶

interpolatepy.CubicBSplineInterpolation ¶

CubicBSplineInterpolation(
    points: list | ndarray,
    v0: list | ndarray | None = None,
    vn: list | ndarray | None = None,
    method: str = "chord_length",
    auto_derivatives: bool = False,
)

Bases: BSpline

A class for cubic B-spline interpolation of a set of points.

This class implements a global interpolation algorithm for creating a cubic B-spline curve that passes through all specified points with C² continuity. It inherits from the BSpline class and extends it with interpolation capabilities.

Parameters:

Name	Type	Description	Default
`points`	`array_like`	The points to interpolate. Should be a 2D array of shape (n, d) where n is the number of points and d is the dimension, or a 1D array for single-dimensional points.	required
`v0`	`array_like`	Initial endpoint derivative vector. If None and auto_derivatives is True, it will be calculated as (q₁-q₀)/(ū₁-ū₀). If None and auto_derivatives is False, zero derivative is used. Default is None.	`None`
`vn`	`array_like`	Final endpoint derivative vector. If None and auto_derivatives is True, it will be calculated as (qₙ-qₙ₋₁)/(ūₙ-ūₙ₋₁). If None and auto_derivatives is False, zero derivative is used. Default is None.	`None`
`method`	`(equally_spaced, chord_length, centripetal)`	Method for calculating the parameters ūₖ. Default is 'chord_length'.	`'equally_spaced'`
`auto_derivatives`	`bool`	Whether to automatically calculate derivatives when not provided. Default is False.	`False`

Attributes:

Name	Type	Description
`interpolation_points`	`ndarray`	The points used for interpolation.
`n_interpolation_points`	`int`	The number of interpolation points.
`u_bars`	`ndarray`	The parameters ūₖ calculated using the specified method.
`v0`	`ndarray`	The initial endpoint derivative vector.
`vn`	`ndarray`	The final endpoint derivative vector.

Notes

The implementation follows the global interpolation algorithm described in Section 8.4.2 of "The NURBS Book" by Piegl and Tiller.

ApproximationBSpline¶

interpolatepy.ApproximationBSpline ¶

ApproximationBSpline(
    points: list | ndarray,
    num_control_points: int,
    *,
    degree: int = 3,
    weights: list | ndarray | None = None,
    method: str = "chord_length",
    debug: bool = False,
)

Bases: BSpline

A class for B-spline curve approximation of a set of points.

Inherits from BSpline class.

The endpoint-constrained least-squares approximation has these properties: - The end points are exactly interpolated - The internal points are approximated in the least squares sense - Degree 3 (cubic) is typically used to ensure C2 continuity

Attributes:

Name	Type	Description
`original_points`	`ndarray`	The original points being approximated.
`original_parameters`	`ndarray`	The parameter values corresponding to original points.

Parameters:

Name	Type	Description	Default
`points`	`list or ndarray`	The points to approximate.	required
`num_control_points`	`int`	The number of control points to use.	required
`degree`	`int`	The degree of the B-spline. Defaults to 3 for cubic.	`3`
`weights`	`list or ndarray or None`	Weights for points in approximation. If None, uniform weighting is used.	`None`
`method`	`str`	Method for parameter calculation. Options are 'equally_spaced', 'chord_length', or 'centripetal'.	`"chord_length"`
`debug`	`bool`	Whether to print debug information.	`False`

Raises:

Type	Description
`ValueError`	If inputs do not satisfy approximation requirements.

calculate_approximation_error ¶

calculate_approximation_error(
    points: ndarray | None = None,
    u_bar: ndarray | None = None,
) -> float

Calculate the approximation error as the sum of squared distances.

Computes sum of squared distances between the points and the corresponding points on the B-spline.

Parameters:

Name	Type	Description	Default
`points`	`ndarray or None`	The points to compare with the B-spline. If None, the original points used for approximation are used.	`None`
`u_bar`	`ndarray or None`	Parameter values for the points. If None, the original parameters are used for original points, or computed for new points.	`None`

Returns:

Type	Description
`float`	The sum of squared distances.

refine ¶

refine(
    max_error: float = 0.1, max_control_points: int = 100
) -> ApproximationBSpline

Refine the approximation by adding more control points.

Adds control points until the maximum error is below a threshold or the maximum number of control points is reached.

Parameters:

Name	Type	Description	Default
`max_error`	`float`	Maximum acceptable error.	`0.1`
`max_control_points`	`int`	Maximum number of control points.	`100`

Returns:

Type	Description
`ApproximationBSpline`	A refined approximation B-spline.

SmoothingCubicBSpline¶

interpolatepy.SmoothingCubicBSpline ¶

SmoothingCubicBSpline(
    points: list | ndarray,
    params: BSplineParams | None = None,
)

Bases: BSpline

A class for creating smoothing cubic B-splines that approximate a set of points.

This class fits a cubic B-spline by minimizing a penalized least-squares objective that balances waypoint residuals against curve roughness.

Parameters:

Name	Type	Description	Default
`points`	`array_like`	The points to approximate.	required
`params`	`BSplineParams`	Configuration parameters. If None, default parameters will be used.	`None`

calculate_approximation_error ¶

calculate_approximation_error() -> ndarray

Calculate the approximation error for each point.

Returns:

Type	Description
`ndarray`	Array with error values for each approximation point.

calculate_smoothness_measure ¶

calculate_smoothness_measure(
    num_points: int = 100,
) -> float

Calculate the smoothness measure (integral of squared second derivative).

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to use for numerical integration.	`100`

Returns:

Type	Description
`float`	The smoothness measure.

calculate_total_error ¶

calculate_total_error() -> float

Calculate the total weighted approximation error.

Returns:

Type	Description
`float`	The total weighted error.

interpolatepy.BSplineParams `dataclass` ¶

BSplineParams(
    mu: float = 0.5,
    weights: list | ndarray | None = None,
    v0: list | ndarray | None = None,
    vn: list | ndarray | None = None,
    method: str = "chord_length",
    enforce_endpoints: bool = False,
    auto_derivatives: bool = False,
)

Parameters for initializing a SmoothingCubicBSpline.

Attributes:

Name	Type	Description
`mu`	`float, default=0.5`	Smoothing parameter between 0 and 1, where higher values give more importance to fitting the data points exactly.
`weights`	`array_like or None, default=None`	Weights for each data point.
`v0`	`array_like or None, default=None`	Tangent vector at the start point.
`vn`	`array_like or None, default=None`	Tangent vector at the end point.
`method`	`str, default="chord_length"`	Method for parameter calculation ('equally_spaced', 'chord_length', or 'centripetal').
`enforce_endpoints`	`bool, default=False`	Whether to enforce interpolation at the endpoints.
`auto_derivatives`	`bool, default=False`	Whether to automatically calculate derivatives at endpoints.

Motion profiles¶

DoubleSTrajectory¶

interpolatepy.DoubleSTrajectory ¶

DoubleSTrajectory(
    state_params: StateParams, bounds: TrajectoryBounds
)

Double S-Trajectory Planner Class

This class implements a trajectory planning algorithm that generates smooth motion profiles with bounded velocity, acceleration, and jerk (double S-trajectory).

Parameters:

state_params : StateParams Start and end states for trajectory planning bounds : TrajectoryBounds Velocity, acceleration, and jerk bounds for trajectory planning

create_trajectory `staticmethod` ¶

create_trajectory(
    state_params: StateParams, bounds: TrajectoryBounds
) -> tuple[
    Callable[
        [float | ndarray], tuple[float | ndarray, ...]
    ],
    float,
]

Static factory method to create a trajectory function and return its duration. This method provides an interface similar to the original function-based API.

Parameters:

state_params : StateParams Start and end states for trajectory planning bounds : TrajectoryBounds Velocity, acceleration, and jerk bounds for trajectory planning

Returns:

trajectory_function : Callable A function that takes time t as input and returns position, velocity, acceleration, and jerk at that time T : float Total trajectory duration

evaluate ¶

evaluate(t: float | ndarray) -> float | ndarray

Evaluate position at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time(s) at which to evaluate.	required

Returns:

Type	Description
`float or ndarray`	Position at time t.

evaluate_acceleration ¶

evaluate_acceleration(
    t: float | ndarray,
) -> float | ndarray

Evaluate acceleration at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time(s) at which to evaluate.	required

Returns:

Type	Description
`float or ndarray`	Acceleration at time t.

evaluate_full ¶

evaluate_full(
    t: float | ndarray,
) -> tuple[float | ndarray, ...]

Evaluate all trajectory components at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time(s) at which to evaluate the trajectory.	required

Returns:

Name	Type	Description
`q`	`float or ndarray`	Position at time t.
`qp`	`float or ndarray`	Velocity at time t.
`qpp`	`float or ndarray`	Acceleration at time t.
`qppp`	`float or ndarray`	Jerk at time t.

evaluate_jerk ¶

evaluate_jerk(t: float | ndarray) -> float | ndarray

Evaluate jerk at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time(s) at which to evaluate.	required

Returns:

Type	Description
`float or ndarray`	Jerk at time t.

evaluate_velocity ¶

evaluate_velocity(t: float | ndarray) -> float | ndarray

Evaluate velocity at time t.

Parameters:

Name	Type	Description	Default
`t`	`float or ndarray`	Time(s) at which to evaluate.	required

Returns:

Type	Description
`float or ndarray`	Velocity at time t.

get_duration ¶

get_duration() -> float

Returns the total duration of the trajectory.

Returns:

T : float Total trajectory duration in seconds

get_phase_durations ¶

get_phase_durations() -> dict[str, float]

Returns the durations of each phase in the trajectory.

Returns:

phases : dict Dictionary containing the durations of each phase

interpolatepy.StateParams `dataclass` ¶

StateParams(q_0: float, q_1: float, v_0: float, v_1: float)

Parameters representing position and velocity state.

Parameters:

Name	Type	Description	Default
`q_0`	`float`	Start position.	required
`q_1`	`float`	End position.	required
`v_0`	`float`	Velocity at start of trajectory.	required
`v_1`	`float`	Velocity at end of trajectory.	required

interpolatepy.TrajectoryBounds `dataclass` ¶

TrajectoryBounds(
    v_bound: float, a_bound: float, j_bound: float
)

Bounds for trajectory planning.

Parameters:

Name	Type	Description	Default
`v_bound`	`float`	Velocity bound (absolute value will be used for both min/max).	required
`a_bound`	`float`	Acceleration bound (absolute value will be used for both min/max).	required
`j_bound`	`float`	Jerk bound (absolute value will be used for both min/max).	required

__post_init__ ¶

__post_init__() -> None

Validate the bounds.

DoubleSTrajectory.evaluate(t) returns only position. DoubleSTrajectory.evaluate_full(t) returns (position, velocity, acceleration, jerk).

TrapezoidalTrajectory¶

interpolatepy.TrapezoidalTrajectory ¶

Generate trapezoidal velocity profiles for trajectory planning.

This class provides methods to create trapezoidal velocity profiles for various trajectory planning scenarios, including single segment trajectories and multi-point interpolation. The trapezoidal profile consists of three phases: acceleration, constant velocity (cruise), and deceleration phases.

The implementation solves the constant-acceleration kinematic equations for both time-constrained and velocity-constrained motion.

Methods:

Name	Description
`generate_trajectory`	Generate a single-segment trapezoidal trajectory.
`interpolate_waypoints`	Generate a multi-segment trajectory through waypoints.
`calculate_heuristic_velocities`	Compute intermediate velocities for multi-point trajectories.

Examples:

>>> from interpolatepy import TrapezoidalTrajectory, TrajectoryParams
>>>
>>> # Simple point-to-point trajectory with velocity constraint
>>> params = TrajectoryParams(q0=0, q1=10, v0=0, v1=0, amax=2.0, vmax=5.0)
>>> trajectory_func, duration = TrapezoidalTrajectory.generate_trajectory(params)
>>>
>>> # Evaluate trajectory at various times
>>> for t in [0, duration/2, duration]:
...     pos, vel, acc = trajectory_func(t)
...     print(f"t={t:.2f}: pos={pos:.2f}, vel={vel:.2f}, acc={acc:.2f}")
>>>
>>> # Multi-point interpolation
>>> from interpolatepy import InterpolationParams
>>> waypoints = [0, 5, 3, 8]
>>> interp_params = InterpolationParams(points=waypoints, amax=2.0, vmax=4.0)
>>> traj_func, total_time = TrapezoidalTrajectory.interpolate_waypoints(interp_params)

calculate_heuristic_velocities `staticmethod` ¶

calculate_heuristic_velocities(
    q_list: list[float],
    v0: float,
    vn: float,
    v_max: float | None = None,
    amax: float | None = None,
) -> list[float]

Calculate velocities based on height differences with multiple options for heuristic velocity calculation.

Parameters:

Name	Type	Description	Default
`q_list`	`list[float]`	List of height values [q0, q1, ..., qn]	required
`v0`	`float`	Initial velocity (assigned)	required
`vn`	`float`	Final velocity (assigned)	required
`v_max`	`float \| None`	Maximum velocity value (positive magnitude)	`None`
`amax`	`float \| None`	Maximum acceleration (needed if v_max is not provided)	`None`

Returns:

Type	Description
`list[float]`	Calculated velocities [v0, v1, ..., vn]

Raises:

Type	Description
`ValueError`	If neither v_max nor amax is provided

generate_trajectory `staticmethod` ¶

generate_trajectory(
    params: TrajectoryParams,
) -> tuple[
    Callable[[float], tuple[float, float, float]], float
]

Generate a trapezoidal trajectory with non-null initial and final velocities.

Handles both positive and negative displacements by planning in a positive-displacement coordinate system and transforming the result back. Uses absolute values for amax and vmax and includes numerical stability enhancements.

Parameters:

Name	Type	Description	Default
`params`	`TrajectoryParams`	Parameters for trajectory generation including initial and final positions, velocities, acceleration and velocity limits, and optional duration.	required

Returns:

Type	Description
`tuple[Callable[[float], tuple[float, float, float]], float]`	A tuple containing: - Function that computes position, velocity, and acceleration at time t - Duration of trajectory

Raises:

Type	Description
`ValueError`	If parameter combination is invalid or trajectory is not feasible

interpolate_waypoints `classmethod` ¶

interpolate_waypoints(
    params: InterpolationParams,
) -> tuple[
    Callable[[float], tuple[float, float, float]], float
]

Generate a trajectory through a sequence of points using trapezoidal velocity profiles.

Supports both positive and negative displacements.

Parameters:

Name	Type	Description	Default
`params`	`InterpolationParams`	Parameters for interpolation including points, velocities, times, and motion constraints.	required

Returns:

Type	Description
`tuple[Callable[[float], tuple[float, float, float]], float]`	A tuple containing: - Function that returns position, velocity, and acceleration at any time t - Total duration of the trajectory

Raises:

Type	Description
`ValueError`	If less than two points are provided or if invalid velocity counts are provided

The trapezoidal configuration type is module-qualified because the package-root TrajectoryParams name belongs to polynomial trajectories:

interpolatepy.trapezoidal.TrajectoryParams `dataclass` ¶

TrajectoryParams(
    q0: float,
    q1: float,
    t0: float = 0.0,
    v0: float = 0.0,
    v1: float = 0.0,
    amax: float | None = None,
    vmax: float | None = None,
    duration: float | None = None,
)

Parameters for trapezoidal trajectory generation.

Parameters:

Name	Type	Description	Default
`q0`	`float`	Initial position.	required
`q1`	`float`	Final position.	required
`t0`	`float`	Initial time. Default is 0.0.	`0.0`
`v0`	`float`	Initial velocity. Default is 0.0.	`0.0`
`v1`	`float`	Final velocity. Default is 0.0.	`0.0`
`amax`	`float`	Maximum acceleration constraint.	`None`
`vmax`	`float`	Maximum velocity constraint.	`None`
`duration`	`float`	Desired trajectory duration.	`None`

interpolatepy.CalculationParams `dataclass` ¶

CalculationParams(
    q0: float, q1: float, v0: float, v1: float, amax: float
)

Parameters for trajectory calculations.

Parameters:

Name	Type	Description	Default
`q0`	`float`	Initial position.	required
`q1`	`float`	Final position.	required
`v0`	`float`	Initial velocity.	required
`v1`	`float`	Final velocity.	required
`amax`	`float`	Maximum acceleration.	required

interpolatepy.InterpolationParams `dataclass` ¶

InterpolationParams(
    points: list[float],
    v0: float = 0.0,
    vn: float = 0.0,
    inter_velocities: list[float] | None = None,
    times: list[float] | None = None,
    amax: float = 10.0,
    vmax: float | None = None,
)

Parameters for multi-point interpolation.

Parameters:

Name	Type	Description	Default
`points`	`list[float]`	List of position waypoints to interpolate through.	required
`v0`	`float`	Initial velocity. Default is 0.0.	`0.0`
`vn`	`float`	Final velocity. Default is 0.0.	`0.0`
`inter_velocities`	`list[float]`	Intermediate velocities at waypoints. If None, velocities are computed heuristically.	`None`
`times`	`list[float]`	Time points corresponding to each waypoint. If None, times are computed optimally.	`None`
`amax`	`float`	Maximum acceleration constraint. Default is 10.0.	`10.0`
`vmax`	`float`	Maximum velocity constraint.	`None`

PolynomialTrajectory¶

interpolatepy.PolynomialTrajectory ¶

Generate smooth polynomial trajectories with specified boundary conditions.

This class provides methods to create polynomial trajectories of different orders (3^rd, 5^th, and 7^th) with specified boundary conditions such as position, velocity, acceleration, and jerk. The polynomials ensure smooth motion profiles with continuous derivatives up to the jerk level, making them ideal for robotics and control applications.

Methods:

Name	Description
`order_3_trajectory`	Generate a 3^rd order polynomial trajectory with position and velocity constraints.
`order_5_trajectory`	Generate a 5^th order polynomial trajectory with position, velocity, and acceleration constraints.
`order_7_trajectory`	Generate a 7^th order polynomial trajectory with position, velocity, acceleration, and jerk constraints.
`heuristic_velocities`	Compute intermediate velocities for a sequence of points using heuristic rules.
`multipoint_trajectory`	Generate a trajectory through a sequence of points with specified times.

Notes

The polynomial trajectories are defined as:

3^rd Order: q(t) = a₀ + a₁τ + a₂τ² + a₃τ³ 5^th Order: q(t) = a₀ + a₁τ + a₂τ² + a₃τ³ + a₄τ⁴ + a₅τ⁵ 7^th Order: q(t) = a₀ + a₁τ + ... + a₇τ⁷

Where τ = t - t_start is the normalized time within each segment.

The coefficients are computed to satisfy the specified boundary conditions: - 3^rd order requires position and velocity at both endpoints (4 constraints) - 5^th order requires position, velocity, and acceleration (6 constraints) - 7^th order requires position, velocity, acceleration, and jerk (8 constraints)

Examples:

>>> import numpy as np
>>> from interpolatepy import PolynomialTrajectory, BoundaryCondition, TimeInterval
>>>
>>> # Create a 5th order polynomial trajectory
>>> initial = BoundaryCondition(position=0, velocity=0, acceleration=0)
>>> final = BoundaryCondition(position=10, velocity=0, acceleration=0)
>>> time_interval = TimeInterval(start=0, end=2.0)
>>>
>>> trajectory_func = PolynomialTrajectory.order_5_trajectory(
...     initial, final, time_interval
... )
>>>
>>> # Evaluate trajectory at various times
>>> for t in np.linspace(0, 2, 5):
...     pos, vel, acc, jerk = trajectory_func(t)
...     print(f"t={t:.1f}: pos={pos:.2f}, vel={vel:.2f}, acc={acc:.2f}")
>>>
>>> # Multi-point trajectory example
>>> from interpolatepy import TrajectoryParams
>>> params = TrajectoryParams(
...     points=[0, 5, 3, 8],
...     times=[0, 1, 2, 3],
...     order=5
... )
>>> multi_traj = PolynomialTrajectory.multipoint_trajectory(params)
>>>
>>> # Evaluate at any time
>>> pos, vel, acc, jerk = multi_traj(1.5)

heuristic_velocities `staticmethod` ¶

heuristic_velocities(
    points: list[float], times: list[float]
) -> list[float]

Compute intermediate velocities for a sequence of points using the heuristic rule.

The heuristic rule sets the velocity at each intermediate point to the average of the slopes of the adjacent segments, unless the slopes have different signs, in which case the velocity is set to zero. This prevents oscillatory behavior near direction changes.

Parameters:

Name	Type	Description	Default
`points`	`list[float]`	List of position points [q₀, q₁, ..., qₙ].	required
`times`	`list[float]`	List of time points [t₀, t₁, ..., tₙ].	required

Returns:

Type	Description
`list[float]`	List of velocities [v₀, v₁, ..., vₙ].

Notes

The heuristic rule is defined as:

For intermediate points i = 1, 2, ..., n-1: - If sign(sᵢ₋₁) ≠ sign(sᵢ): vᵢ = 0 - Otherwise: vᵢ = (sᵢ₋₁ + sᵢ) / 2

Where sᵢ = (qᵢ₊₁ - qᵢ) / (tᵢ₊₁ - tᵢ) is the slope of segment i.

The boundary velocities v₀ and vₙ are set to zero by default.

Examples:

>>> points = [0, 2, 1, 3]
>>> times = [0, 1, 2, 3]
>>> velocities = PolynomialTrajectory.heuristic_velocities(points, times)
>>> print(velocities)  # [0.0, 2.0, 0.0, 0.0]

multipoint_trajectory `classmethod` ¶

multipoint_trajectory(
    params: TrajectoryParams,
) -> Callable[[float], tuple[float, float, float, float]]

Generate a trajectory through a sequence of points with specified times.

Parameters:

Name	Type	Description	Default
`params`	`TrajectoryParams`	Parameters for trajectory generation including points, times, and optional velocities, accelerations, jerks, and polynomial order.	required

Returns:

Type	Description
`Callable[[float], tuple[float, float, float, float]]`	Function that computes trajectory at time t

Raises:

Type	Description
`ValueError`	If number of points and times are not the same, or if order is not one of the valid polynomial orders.

order_3_trajectory `staticmethod` ¶

order_3_trajectory(
    initial: BoundaryCondition,
    final: BoundaryCondition,
    time: TimeInterval,
) -> Callable[[float], tuple[float, float, float, float]]

Generate a 3^rd order polynomial trajectory with specified boundary conditions.

Parameters:

Name	Type	Description	Default
`initial`	`BoundaryCondition`	Initial boundary conditions (position, velocity).	required
`final`	`BoundaryCondition`	Final boundary conditions (position, velocity).	required
`time`	`TimeInterval`	Time interval for the trajectory.	required

Returns:

Type	Description
`Callable[[float], tuple[float, float, float, float]]`	Function that computes position, velocity, acceleration, and jerk at time t.

Notes

The 3^rd order polynomial is defined as: q(τ) = a₀ + a₁τ + a₂τ² + a₃τ³

Where the coefficients are determined by the boundary conditions: - q(0) = q₀, q̇(0) = v₀ - q(T) = q₁, q̇(T) = v₁

The coefficient formulas (equation 2.2) are: - a₀ = q₀ - a₁ = v₀ - a₂ = (3h - (2v₀ + v₁)T) / T² - a₃ = (-2h + (v₀ + v₁)T) / T³

Where h = q₁ - q₀ and T = t_end - t_start.

Examples:

>>> # Simple point-to-point motion
>>> initial = BoundaryCondition(position=0, velocity=1)
>>> final = BoundaryCondition(position=5, velocity=0)
>>> time_interval = TimeInterval(start=0, end=2.0)
>>> traj = PolynomialTrajectory.order_3_trajectory(initial, final, time_interval)
>>>
>>> # Evaluate at midpoint
>>> pos, vel, acc, jerk = traj(1.0)

order_5_trajectory `staticmethod` ¶

order_5_trajectory(
    initial: BoundaryCondition,
    final: BoundaryCondition,
    time: TimeInterval,
) -> Callable[[float], tuple[float, float, float, float]]

Generate a 5^th order polynomial trajectory with specified boundary conditions.

Parameters:

Name	Type	Description	Default
`initial`	`BoundaryCondition`	Initial boundary conditions (position, velocity, acceleration).	required
`final`	`BoundaryCondition`	Final boundary conditions (position, velocity, acceleration).	required
`time`	`TimeInterval`	Time interval for the trajectory.	required

Returns:

Type	Description
`Callable[[float], tuple[float, float, float, float]]`	Function that computes position, velocity, acceleration, and jerk at time t.

Notes

The 5^th order polynomial provides smooth acceleration profiles and is defined as: q(τ) = a₀ + a₁τ + a₂τ² + a₃τ³ + a₄τ⁴ + a₅τ⁵

The six boundary conditions are: - q(0) = q₀, q̇(0) = v₀, q̈(0) = a₀ - q(T) = q₁, q̇(T) = v₁, q̈(T) = a₁

The coefficients (equation 2.5) ensure continuous position, velocity, and acceleration, making this ideal for applications requiring smooth acceleration profiles such as robotic manipulators.

Examples:

>>> # Trajectory with zero initial and final accelerations
>>> initial = BoundaryCondition(position=0, velocity=0, acceleration=0)
>>> final = BoundaryCondition(position=10, velocity=2, acceleration=0)
>>> time_interval = TimeInterval(start=0, end=3.0)
>>> traj = PolynomialTrajectory.order_5_trajectory(initial, final, time_interval)

order_7_trajectory `staticmethod` ¶

order_7_trajectory(
    initial: BoundaryCondition,
    final: BoundaryCondition,
    time: TimeInterval,
) -> Callable[[float], tuple[float, float, float, float]]

Generate a 7^th order polynomial trajectory with specified boundary conditions.

Parameters:

Name	Type	Description	Default
`initial`	`BoundaryCondition`	Initial boundary conditions (position, velocity, acceleration, jerk)	required
`final`	`BoundaryCondition`	Final boundary conditions (position, velocity, acceleration, jerk)	required
`time`	`TimeInterval`	Time interval for the trajectory	required

Returns:

Type	Description
`Callable[[float], tuple[float, float, float, float]]`	Function that computes position, velocity, acceleration, and jerk at time t

interpolatepy.BoundaryCondition `dataclass` ¶

BoundaryCondition(
    position: float,
    velocity: float,
    acceleration: float = 0.0,
    jerk: float = 0.0,
)

Boundary conditions for polynomial trajectory generation.

Parameters:

Name	Type	Description	Default
`position`	`float`	Position constraint.	required
`velocity`	`float`	Velocity constraint.	required
`acceleration`	`float`	Acceleration constraint. Default is 0.0.	`0.0`
`jerk`	`float`	Jerk constraint. Default is 0.0.	`0.0`

Notes

Higher-order polynomial trajectories require more boundary conditions: - 3^rd order: position and velocity - 5^th order: position, velocity, and acceleration - 7^th order: position, velocity, acceleration, and jerk

interpolatepy.TimeInterval `dataclass` ¶

TimeInterval(start: float, end: float)

Time interval for trajectory generation.

Parameters:

Name	Type	Description	Default
`start`	`float`	Start time of the trajectory segment.	required
`end`	`float`	End time of the trajectory segment.	required

interpolatepy.TrajectoryParams `dataclass` ¶

TrajectoryParams(
    points: list[float],
    times: list[float],
    velocities: list[float] | None = None,
    accelerations: list[float] | None = None,
    jerks: list[float] | None = None,
    order: int = ORDER_3,
)

Parameters for multipoint polynomial trajectory generation.

Parameters:

Name	Type	Description	Default
`points`	`list[float]`	List of position waypoints to interpolate through.	required
`times`	`list[float]`	List of time points corresponding to each waypoint.	required
`velocities`	`list[float]`	Velocity constraints at each waypoint. If None, velocities are computed using heuristic rules.	`None`
`accelerations`	`list[float]`	Acceleration constraints at each waypoint. Required for 5^th and 7^th order polynomials. If None, zero accelerations are assumed.	`None`
`jerks`	`list[float]`	Jerk constraints at each waypoint. Required for 7^th order polynomials. If None, zero jerks are assumed.	`None`
`order`	`int`	Polynomial order (3, 5, or 7). Default is 3.	`ORDER_3`

ParabolicBlendTrajectory¶

interpolatepy.ParabolicBlendTrajectory ¶

ParabolicBlendTrajectory(
    q: list | ndarray,
    t: list | ndarray,
    dt_blend: list | ndarray,
    dt: float = 0.01,
)

Class to generate trajectories composed of linear segments with parabolic blends at via points.

The trajectory duration is extended: total_duration = t[-1] - t[0] + (dt_blend[0] + dt_blend[-1]) / 2

Initial and final velocities are set to zero (q̇0,1 = q̇N,N+1 = 0).

Parameters:

Name	Type	Description	Default
`q`	`list \| ndarray`	Positions of via points (length N).	required
`t`	`list \| ndarray`	Nominal times at which via points are reached (length N).	required
`dt_blend`	`list \| ndarray`	Blend durations at via points (length N).	required
`dt`	`float`	Sampling interval for plotting trajectory. Default is 0.01.	`0.01`

generate ¶

generate() -> tuple[
    Callable[[float], tuple[float, float, float]], float
]

Generate the parabolic blend trajectory function.

Returns:

Name	Type	Description
`trajectory_function`	`callable`	Function that takes a time value and returns position, velocity, and acceleration.
`total_duration`	`float`	The total duration of the trajectory.

plot ¶

plot(
    times: ndarray | None = None,
    pos: ndarray | None = None,
    vel: ndarray | None = None,
    acc: ndarray | None = None,
) -> None

Plot the trajectory's position, velocity, and acceleration.

If trajectory data is not provided, it will be generated.

Parameters:

Name	Type	Description	Default
`times`	`ndarray`	Time samples; if None, generated from trajectory function.	`None`
`pos`	`ndarray`	Position samples; if None, generated from trajectory function.	`None`
`vel`	`ndarray`	Velocity samples; if None, generated from trajectory function.	`None`
`acc`	`ndarray`	Acceleration samples; if None, generated from trajectory function.	`None`

Quaternion operations and interpolation¶

Quaternion¶

interpolatepy.Quaternion ¶

Quaternion(
    s: float = 1.0,
    v1: float = 0.0,
    v2: float = 0.0,
    v3: float = 0.0,
)

Core quaternion class that implements: - Basic quaternion arithmetic and operations - Quaternion dynamics (time derivatives, integration) - Spherical linear interpolation (Slerp) - Spherical cubic interpolation (Squad) - Matrix conversions and utilities

A quaternion is represented as q = [s, v] where: - s is the scalar part (w component) - v is the vector part [v1, v2, v3] (x, y, z components)

Example usage: # Create quaternions q1 = Quaternion.identity() q2 = Quaternion.from_euler_angles(0.1, 0.2, 0.3)

# Basic operations
q3 = q1 * q2
q_normalized = q3.unit()

# Interpolation
q_interp = q1.slerp(q2, 0.5)

# Conversions
rotation_matrix = q2.R()
roll, pitch, yaw = q2.to_euler_angles()

Args: s: Scalar part (w component) v1: X component of vector part v2: Y component of vector part v3: Z component of vector part

w `property` ¶

w: float

Alias for scalar part (w component)

x `property` ¶

x: float

Get x component of vector part

y `property` ¶

y: float

Get y component of vector part

z `property` ¶

z: float

Get z component of vector part

E ¶

E(sign: int) -> ndarray

Matrix E for quaternion dynamics.

E = sI - S(v) for BASE_FRAME (sign=0) E = sI + S(v) for BODY_FRAME (sign=1)

where S(v) is the skew-symmetric matrix of v

Integ_quat `staticmethod` ¶

Integ_quat(
    dquat_present: Quaternion,
    dquat_past: Quaternion,
    quat: Quaternion,
    dt: float,
) -> tuple[Quaternion, Quaternion, Quaternion, int]

Trapezoidal quaternion integration.

Returns: (updated_quat, updated_dquat_present, updated_dquat_past, status)

Log ¶

Log() -> Quaternion

Quaternion logarithm for unit quaternions.

For unit q = [cos(θ), v*sin(θ)], log(q) = [0, v*θ]

Omega `staticmethod` ¶

Omega(q: Quaternion, q_dot: Quaternion) -> ndarray

Return angular velocity from quaternion and its time derivative.

Solves: q̇ = ½E*ω for ω

R ¶

R() -> ndarray

Rotation matrix from unit quaternion.

R = (s² - v·v)I + 2vv^T + 2s*S(v)

Slerp_prime `staticmethod` ¶

Slerp_prime(
    q0: Quaternion, q1: Quaternion, t: float
) -> Quaternion

Static version of slerp_prime

Squad `staticmethod` ¶

Squad(
    p: Quaternion,
    a: Quaternion,
    b: Quaternion,
    q: Quaternion,
    t: float,
) -> Quaternion

Spherical Cubic Interpolation (Squad).

Squad_prime `staticmethod` ¶

Squad_prime(
    p: Quaternion,
    a: Quaternion,
    b: Quaternion,
    q: Quaternion,
    t: float,
) -> Quaternion

Spherical Cubic Interpolation derivative.

T ¶

T() -> ndarray

Transformation matrix from quaternion.

add ¶

__add__(other: Quaternion) -> Quaternion

Quaternion addition: q1 + q2 = [s1+s2, v1+v2]

eq ¶

__eq__(other: object) -> bool

Equality comparison with epsilon tolerance

mul ¶

__mul__(other: Union[Quaternion, float]) -> Quaternion

Quaternion multiplication or scalar multiplication.

neg ¶

__neg__() -> Quaternion

Quaternion negation: -q = [-s, -v]

repr ¶

__repr__() -> str

Detailed string representation

rmul ¶

__rmul__(scalar: float) -> Quaternion

Right scalar multiplication: c * q

str ¶

__str__() -> str

String representation

sub ¶

__sub__(other: Quaternion) -> Quaternion

Quaternion subtraction: q1 - q2 = [s1-s2, v1-v2]

truediv ¶

__truediv__(other: Union[Quaternion, float]) -> Quaternion

Quaternion division or scalar division.

compute_intermediate_quaternion `staticmethod` ¶

compute_intermediate_quaternion(
    q_prev: Quaternion,
    q_curr: Quaternion,
    q_next: Quaternion,
) -> Quaternion

Compute intermediate quaternion for Squad interpolation. s_i = q_i * exp(-(log(q_i^(-1) * q_{i+1}) + log(q_i^(-1) * q_{i-1})) / 4)

conjugate ¶

conjugate() -> Quaternion

Quaternion conjugate: q* = [s, -v]

copy ¶

copy() -> Quaternion

Create a copy of this quaternion

dot ¶

dot(w: ndarray, sign: int) -> Quaternion

Quaternion time derivative.

The quaternion time derivative (quaternion propagation equation): ṡ = -½v^T*w₀ v̇ = ½E(s,v)*w₀

Where E = sI - S(v) for BASE_FRAME (sign=0) E = sI + S(v) for BODY_FRAME (sign=1)

Args: w: Angular velocity vector (3D) sign: Frame type (BASE_FRAME=0 or BODY_FRAME=1)

dot_prod ¶

dot_prod(other: Quaternion) -> float

Quaternion dot product: q1·q2 = s1*s2 + v1·v2

dot_product ¶

dot_product(other: Quaternion) -> float

Alias for dot_prod

exp ¶

exp() -> Quaternion

Quaternion exponential.

For q = [0, θv], exp(q) = [cos(θ), v*sin(θ)]

from_angle_axis `classmethod` ¶

from_angle_axis(angle: float, axis: ndarray) -> Quaternion

Create quaternion from rotation angle and axis.

Args: angle: Rotation angle in radians axis: 3D rotation axis vector

Returns: Quaternion representing the rotation

from_euler_angles `classmethod` ¶

from_euler_angles(
    roll: float, pitch: float, yaw: float
) -> Quaternion

Create quaternion from Euler angles (roll, pitch, yaw) in radians

from_rotation_matrix `classmethod` ¶

from_rotation_matrix(
    rotation_matrix: ndarray,
) -> Quaternion

Create quaternion from 3x3 or 4x4 rotation matrix.

i ¶

i() -> Quaternion

Quaternion inverse: q^(-1) = q*/||q||²

identity `classmethod` ¶

identity() -> Quaternion

Create identity quaternion [1, 0, 0, 0]

integ_trap_quat_s `staticmethod` ¶

integ_trap_quat_s(
    present: Quaternion, past: Quaternion, dt: float
) -> float

Trapezoidal quaternion scalar part integration.

integ_trap_quat_v `staticmethod` ¶

integ_trap_quat_v(
    present: Quaternion, past: Quaternion, dt: float
) -> ndarray

Trapezoidal quaternion vector part integration.

inverse ¶

inverse() -> Quaternion

Alias for i() - quaternion inverse

norm ¶

norm() -> float

Quaternion norm: ||q|| = sqrt(s² + v·v)

norm_squared ¶

norm_squared() -> float

Squared quaternion norm: ||q||² = s² + v·v

power ¶

power(t: float) -> Quaternion

Quaternion power: q^t = exp(t * log(q))

slerp ¶

slerp(other: Quaternion, t: float) -> Quaternion

Spherical Linear Interpolation (Slerp).

slerp_prime ¶

slerp_prime(other: Quaternion, t: float) -> Quaternion

Spherical Linear Interpolation derivative.

to_axis_angle ¶

to_axis_angle() -> tuple[ndarray, float]

Convert quaternion to axis-angle representation.

Returns the canonical form with angle in [0, pi]. When the scalar part is negative, the equivalent rotation -q = [|s|, -v] is used so the returned axis points in the direction consistent with the positive-scalar branch.

to_euler_angles ¶

to_euler_angles() -> tuple[float, float, float]

Convert quaternion to Euler angles (roll, pitch, yaw) in radians

to_rotation_matrix ¶

to_rotation_matrix() -> ndarray

Alias for R() method

to_transformation_matrix ¶

to_transformation_matrix() -> ndarray

Alias for T() method

unit ¶

unit() -> Quaternion

Normalize quaternion to unit length.

Quaternion.to_axis_angle() returns (axis, angle). Angles passed to from_angle_axis() and from_euler_angles() are radians.

QuaternionSpline¶

interpolatepy.QuaternionSpline ¶

QuaternionSpline(
    time_points: list[float],
    quaternions: list[Quaternion],
    interpolation_method: str = AUTO,
)

Quaternion spline interpolator for smooth trajectory planning.

Supports both SLERP and SQUAD interpolation methods with automatic method selection based on the number of control points.

Example usage: # Create quaternions q1 = Quaternion.identity() q2 = Quaternion.from_euler_angles(0.1, 0.2, 0.3) q3 = Quaternion.from_euler_angles(0.2, 0.4, 0.6) q4 = Quaternion.identity()

# Create spline with SLERP interpolation
spline_slerp = QuaternionSpline([0, 1, 2, 3], [q1, q2, q3, q4], Quaternion.SLERP)

# Create spline with SQUAD interpolation
spline_squad = QuaternionSpline([0, 1, 2, 3], [q1, q2, q3, q4], Quaternion.SQUAD)

# Interpolate at specific time
result, status = spline_slerp.interpolate_at_time(1.5)

# Change interpolation method
spline_slerp.set_interpolation_method(Quaternion.SQUAD)

# Force specific interpolation regardless of setting
slerp_result, _ = spline_squad.interpolate_slerp(1.5)
squad_result, _ = spline_slerp.interpolate_squad(1.5)

Args: time_points: List of time values (must be sorted) quaternions: List of quaternions at each time point interpolation_method: Interpolation method - "slerp", "squad", or "auto"

len ¶

__len__() -> int

Return number of quaternion waypoints

repr ¶

__repr__() -> str

Detailed string representation

str ¶

__str__() -> str

String representation

evaluate ¶

evaluate(t: float) -> Quaternion

Evaluate the quaternion at time t.

Wrapper around interpolate_at_time that returns only the quaternion and raises on error, conforming to the QuaternionTrajectory protocol.

Parameters:

Name	Type	Description	Default
`t`	`float`	Time at which to evaluate.	required

Returns:

Type	Description
`Quaternion`	Interpolated quaternion at time t.

Raises:

Type	Description
`ValueError`	If the spline is empty or time is out of range.

evaluate_acceleration ¶

evaluate_acceleration(t: float) -> ndarray

Evaluate the angular acceleration at time t using finite differences.

Computes a central-difference approximation of angular acceleration from the angular velocity, conforming to the QuaternionTrajectory protocol.

Parameters:

Name	Type	Description	Default
`t`	`float`	Time at which to evaluate.	required

Returns:

Type	Description
`ndarray`	3D angular acceleration vector (finite-difference approximation).

Raises:

Type	Description
`ValueError`	If the spline is empty or time is out of range.

Notes

This is a numerical approximation using finite differences with step size dt=1e-6. For applications requiring exact angular acceleration, consider using SquadC2 or log-quaternion methods.

evaluate_velocity ¶

evaluate_velocity(t: float) -> ndarray

Evaluate the angular velocity at time t.

Uses interpolate_with_velocity internally and returns only the angular velocity vector, conforming to the QuaternionTrajectory protocol.

Parameters:

Name	Type	Description	Default
`t`	`float`	Time at which to evaluate.	required

Returns:

Type	Description
`ndarray`	3D angular velocity vector.

Raises:

Type	Description
`ValueError`	If the spline is empty or time is out of range.

get_interpolation_method ¶

get_interpolation_method() -> str

Get the current interpolation method

get_quaternion_at_time ¶

get_quaternion_at_time(t: float) -> Quaternion

Get quaternion at specific time, raising exception on error.

Returns: Interpolated quaternion Raises: ValueError if time is out of range or spline is empty

get_quaternions ¶

get_quaternions() -> list[Quaternion]

Get all quaternions in the spline

get_time_points ¶

get_time_points() -> list[float]

Get all time points in the spline

get_time_range ¶

get_time_range() -> tuple[float, float]

Get the time range of the spline

interpolate_at_time ¶

interpolate_at_time(t: float) -> tuple[Quaternion, int]

Quaternion interpolation at given time.

Returns: (interpolated_quaternion, status_code)

interpolate_slerp ¶

interpolate_slerp(t: float) -> tuple[Quaternion, int]

Force SLERP interpolation at given time, regardless of current method setting.

Returns: (interpolated_quaternion, status_code)

interpolate_squad ¶

interpolate_squad(t: float) -> tuple[Quaternion, int]

Force SQUAD interpolation at given time, regardless of current method setting.

Returns: (interpolated_quaternion, status_code)

interpolate_with_velocity ¶

interpolate_with_velocity(
    t: float,
) -> tuple[Quaternion, ndarray, int]

Quaternion interpolation with angular velocity.

Returns: (interpolated_quaternion, angular_velocity, status_code)

is_empty ¶

is_empty() -> bool

Check if this spline has no data

set_interpolation_method ¶

set_interpolation_method(method: str) -> None

Set the interpolation method for this spline.

Args: method: "slerp", "squad", or "auto"

SquadC2¶

interpolatepy.SquadC2 ¶

SquadC2(
    time_points: list[float],
    quaternions: list[Quaternion],
    normalize_quaternions: bool = True,
    validate_continuity: bool = True,
)

C²-Continuous, Zero-Clamped Quaternion Interpolation using SQUAD with Quintic Polynomial Parameterization.

This class implements the SQUAD_C2 method as described in "Spherical Cubic Blends: C²-Continuous, Zero-Clamped, and Time-Optimized Interpolation of Quaternions" by Wittmann et al. (ICRA 2023).

The construction proceeds as follows: 1. Creates extended quaternion sequence Q = [q₁, q₁ᵛⁱʳᵗ, q₂, ..., qₙ₋₁ᵛⁱʳᵗ, qₙ] where q₁ᵛⁱʳᵗ = q₁ and qₙ₋₁ᵛⁱʳᵗ = qₙ (Section III-B.1) 2. Computes intermediate quaternions using corrected formula (Equation 5): sᵢ = qᵢ ⊗ exp[(log(qᵢ⁻¹⊗qᵢ₊₁)/(-2(1+hᵢ/hᵢ₋₁))) + (log(qᵢ⁻¹⊗qᵢ₋₁)/(-2(1+hᵢ₋₁/hᵢ)))] 3. Uses SQUAD interpolation with proper time parameterization (Equations 2-4) 4. Applies quintic polynomial parameterization u(t) for C²-continuity and zero-clamped boundaries

Key Features: - Guarantees C²-continuous quaternion trajectories - Zero-clamped boundary conditions (zero angular velocity and acceleration at endpoints) - Proper handling of different segment durations hᵢ - Compatible with time-optimization frameworks

References: - Wittmann et al., "Spherical Cubic Blends: C²-Continuous, Zero-Clamped, and Time-Optimized Interpolation of Quaternions", ICRA 2023 - Original SQUAD: Shoemake, "Animating rotation with quaternion curves", SIGGRAPH 1985

The interpolator creates an extended quaternion sequence with virtual waypoints to enable zero-clamped boundary conditions and C²-continuous trajectories.

Args: time_points: List of time values (must be sorted and at least 2 points) quaternions: List of quaternions at each time point normalize_quaternions: Whether to normalize input quaternions to unit length validate_continuity: Whether to validate C² continuity (for debugging)

Raises: ValueError: If input validation fails

Note: The intermediate quaternion formula weights adjacent rotations by their non-uniform time intervals.

len ¶

__len__() -> int

Return number of original waypoints.

repr ¶

__repr__() -> str

Detailed string representation.

str ¶

__str__() -> str

String representation.

evaluate ¶

evaluate(t: float) -> Quaternion

Evaluate quaternion at time t using proper SQUAD_C2 interpolation.

Args: t: Time value

Returns: Interpolated quaternion at time t

evaluate_acceleration ¶

evaluate_acceleration(t: float) -> ndarray

Evaluate angular acceleration at time t.

Args: t: Time value

Returns: 3D angular acceleration vector in rad/s²

evaluate_velocity ¶

evaluate_velocity(t: float) -> ndarray

Evaluate angular velocity at time t.

Args: t: Time value

Returns: 3D angular velocity vector in rad/s

get_extended_sequence_info ¶

get_extended_sequence_info() -> dict

Get detailed information about the extended quaternion sequence for debugging.

Returns: Dictionary with extended sequence details

get_extended_waypoints ¶

get_extended_waypoints() -> tuple[
    list[float], list[Quaternion]
]

Get all waypoint times and quaternions (including virtual waypoints).

get_time_range ¶

get_time_range() -> tuple[float, float]

Get the time range of the trajectory (original waypoints only).

get_waypoints ¶

get_waypoints() -> tuple[list[float], list[Quaternion]]

Get the original waypoint times and quaternions (without virtual waypoints).

LogQuaternionInterpolation¶

interpolatepy.LogQuaternionInterpolation ¶

LogQuaternionInterpolation(
    time_points: list | ndarray,
    quaternions: list[Quaternion],
    degree: int = _DEFAULT_DEGREE,
    initial_velocity: list | ndarray | None = None,
    final_velocity: list | ndarray | None = None,
    initial_acceleration: list | ndarray | None = None,
    final_acceleration: list | ndarray | None = None,
)

Logarithmic Quaternion Interpolation (LQI) using axis-angle representation.

Transforms quaternions to axis-angle space r = θ*n̂ and interpolates the 3D vector with a B-spline (Parker et al. 2023). Before fitting, the quaternion signs and axis-angle branches are adjusted to keep the recovered r(t) continuous and make the interpolation C².

Parameters:

Name	Type	Description	Default
`time_points`	`array_like`	Time values corresponding to each quaternion (must be strictly increasing).	required
`quaternions`	`array_like`	List of unit quaternions to interpolate between.	required
`degree`	`int`	Degree of the B-spline (3, 4, or 5). Default is 3 (cubic).	`_DEFAULT_DEGREE`
`initial_velocity`	`array_like`	Initial/final angular velocity constraints (3D vectors).	`None`
`final_velocity`	`array_like`	Initial/final angular velocity constraints (3D vectors).	`None`
`initial_acceleration`	`array_like`	Initial/final angular acceleration constraints (3D vectors).	`None`
`final_acceleration`	`array_like`	Initial/final angular acceleration constraints (3D vectors).	`None`

evaluate ¶

evaluate(t: float) -> Quaternion

Evaluate the interpolated quaternion at time t.

evaluate_acceleration ¶

evaluate_acceleration(t: float) -> ndarray

Second time-derivative of the rotation vector r(t) (3D).

evaluate_velocity ¶

evaluate_velocity(t: float) -> ndarray

Time-derivative of the rotation vector r(t) (3D).

generate_trajectory ¶

generate_trajectory(
    num_points: int = 100,
) -> tuple[ndarray, list[Quaternion]]

Evaluate the trajectory at num_points evenly spaced times.

get_physical_kinematics ¶

get_physical_kinematics(
    t: float,
) -> tuple[ndarray, ndarray]

Physical 3D angular velocity (omega) and acceleration (alpha) at time t.

The spline interpolates r(t) = theta(t) * n_hat(t). As r -> 0 the left Jacobian J_l® -> I, so omega -> r_dot and alpha -> r_ddot; this limit is used directly when |r| < EPSILON to avoid dividing by a near-zero magnitude.

ModifiedLogQuaternionInterpolation¶

interpolatepy.ModifiedLogQuaternionInterpolation ¶

ModifiedLogQuaternionInterpolation(
    time_points: list | ndarray,
    quaternions: list[Quaternion],
    degree: int = _DEFAULT_DEGREE,
    normalize_axis: bool = True,
    initial_velocity: list | ndarray | None = None,
    final_velocity: list | ndarray | None = None,
    initial_acceleration: list | ndarray | None = None,
    final_acceleration: list | ndarray | None = None,
)

Modified Logarithmic Quaternion Interpolation (mLQI).

Interpolates quaternions as (θ, X, Y, Z) with X²+Y²+Z²=1, using separate B-splines for the scalar angle and the unit-axis components for better numerical stability (Parker et al. 2023). Provides C² continuity.

Parameters:

Name	Type	Description	Default
`time_points`	`array_like`	Time values corresponding to each quaternion (must be strictly increasing).	required
`quaternions`	`array_like`	List of unit quaternions to interpolate between.	required
`degree`	`int`	Degree of the B-spline (3, 4, or 5). Default is 3 (cubic).	`_DEFAULT_DEGREE`
`normalize_axis`	`bool`	If True (default), the spline-evaluated (X, Y, Z) is renormalised before reconstructing the quaternion. Setting this to False is only appropriate when the spline preserves unit norm exactly.	`True`
`initial_velocity`	`array_like`	Initial/final boundary constraints as 4D vectors [θ̇, Ẋ, Ẏ, Ż].	`None`
`final_velocity`	`array_like`	Initial/final boundary constraints as 4D vectors [θ̇, Ẋ, Ẏ, Ż].	`None`
`initial_acceleration`	`array_like`	Initial/final boundary constraints as 4D vectors.	`None`
`final_acceleration`	`array_like`	Initial/final boundary constraints as 4D vectors.	`None`

evaluate ¶

evaluate(t: float) -> Quaternion

Evaluate the interpolated quaternion at time t.

evaluate_acceleration ¶

evaluate_acceleration(t: float) -> ndarray

Second derivative of (θ, X, Y, Z) at time t (4D vector).

evaluate_velocity ¶

evaluate_velocity(t: float) -> ndarray

Derivative of (θ, X, Y, Z) at time t (4D vector).

generate_trajectory ¶

generate_trajectory(
    num_points: int = 100,
) -> tuple[ndarray, list[Quaternion]]

Evaluate the trajectory at num_points evenly spaced times.

get_physical_kinematics ¶

get_physical_kinematics(
    t: float,
) -> tuple[ndarray, ndarray]

Physical 3D angular velocity (omega) and acceleration (alpha) at time t.

With normalize_axis=True the raw xyz-spline derivatives are projected tangent to the unit sphere so radial drift in the spline does not leak into omega/alpha. With normalize_axis=False the raw derivatives are used as-is and the result is only accurate when the spline already preserves unit norm.

The logarithmic interpolators support degree 3, 4, or 5 with at least two quaternion waypoints.

Geometric paths and frames¶

LinearPath¶

interpolatepy.LinearPath ¶

LinearPath(pi: ndarray, pf: ndarray)

A linear path between two points in 3D space.

This class represents a straight-line trajectory from an initial point to a final point, providing methods to evaluate position, velocity, and acceleration along the path.

Parameters:

Name	Type	Description	Default
`pi`	`array_like`	Initial point coordinates [x, y, z].	required
`pf`	`array_like`	Final point coordinates [x, y, z].	required

Attributes:

Name	Type	Description
`pi`	`ndarray`	Initial point coordinates.
`pf`	`ndarray`	Final point coordinates.
`length`	`float`	Total length of the linear path.
`tangent`	`ndarray`	Unit tangent vector (constant for linear path).

Examples:

>>> import numpy as np
>>> # Create a linear path from origin to point (1, 1, 1)
>>> pi = np.array([0, 0, 0])
>>> pf = np.array([1, 1, 1])
>>> path = LinearPath(pi, pf)
>>>
>>> # Evaluate position at half the path length
>>> midpoint = path.position(path.length / 2)
>>> print(midpoint)  # Should be [0.5, 0.5, 0.5]
>>>
>>> # Generate complete trajectory
>>> trajectory = path.all_traj(num_points=10)
>>> positions = trajectory['position']
>>> velocities = trajectory['velocity']

Parameters:

Name	Type	Description	Default
`pi`	`array_like`	Initial point coordinates [x, y, z].	required
`pf`	`array_like`	Final point coordinates [x, y, z].	required

acceleration ¶

acceleration(_s: float | None = None) -> ndarray

Calculate second derivative with respect to arc length. For linear path, this is always zero.

Parameters:

Name	Type	Description	Default
`_s`	`float`	Arc length parameter (not used for linear path).	`None`

Returns:

Type	Description
`ndarray`	Acceleration vector (always zero for linear path).

all_traj ¶

all_traj(num_points: int = 100) -> dict[str, ndarray]

Generate a complete trajectory along the entire linear path.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate along the path. Default is 100.	`100`

Returns:

Type	Description
`dict[str, ndarray]`	Dictionary containing arrays for position, velocity, and acceleration. Each array has shape (num_points, 3).

evaluate_at ¶

evaluate_at(
    s_values: float | list[float] | ndarray,
) -> dict[str, ndarray]

Evaluate position, velocity, and acceleration at specific arc length values.

Parameters:

Name	Type	Description	Default
`s_values`	`float or array_like`	Arc length parameter(s).	required

Returns:

Type	Description
`dict[str, ndarray]`	Dictionary containing arrays for position, velocity, and acceleration. Each array has shape (n, 3) where n is the number of s values.

position ¶

position(s: float) -> ndarray

Calculate position at arc length s.

Parameters:

Name	Type	Description	Default
`s`	`float or array_like`	Arc length parameter(s).	required

Returns:

Type	Description
`ndarray`	Position vector(s) at the specified arc length(s).

velocity ¶

velocity(_s: float | None = None) -> ndarray

Calculate first derivative with respect to arc length. For linear path, this is constant and doesn't depend on s.

Parameters:

Name	Type	Description	Default
`_s`	`float`	Arc length parameter (not used for linear path).	`None`

Returns:

Type	Description
`ndarray`	Velocity (tangent) vector.

CircularPath¶

interpolatepy.CircularPath ¶

CircularPath(r: ndarray, d: ndarray, pi: ndarray)

A circular path in 3D space defined by an axis and a point on the circle.

This class represents a circular trajectory defined by an axis vector, a point on the axis, and a point on the circle. It provides methods to evaluate position, velocity, and acceleration along the circular arc.

Parameters:

Name	Type	Description	Default
`r`	`array_like`	Unit vector of circle axis.	required
`d`	`array_like`	Position vector of a point on the circle axis.	required
`pi`	`array_like`	Position vector of a point on the circle.	required

Attributes:

Name	Type	Description
`r`	`ndarray`	Normalized axis vector of the circle.
`d`	`ndarray`	Position vector of a point on the circle axis.
`pi`	`ndarray`	Position vector of a point on the circle.
`center`	`ndarray`	Center point of the circle.
`radius`	`float`	Radius of the circle.
`R`	`ndarray`	Rotation matrix from local to global coordinates.

Raises:

Type	Description
`ValueError`	If the point pi lies on the circle axis.

Examples:

>>> import numpy as np
>>> # Create a circular path in the XY plane centered at origin
>>> r = np.array([0, 0, 1])     # Z-axis
>>> d = np.array([0, 0, 0])     # Origin on axis
>>> pi = np.array([1, 0, 0])    # Point on circle
>>> circle = CircularPath(r, d, pi)
>>>
>>> # Evaluate position at quarter circle
>>> quarter_arc = np.pi * circle.radius / 2
>>> pos = circle.position(quarter_arc)
>>>
>>> # Generate complete trajectory around the circle
>>> trajectory = circle.all_traj(num_points=100)
>>> positions = trajectory['position']

Parameters:

Name	Type	Description	Default
`r`	`array_like`	Unit vector of circle axis.	required
`d`	`array_like`	Position vector of a point on the circle axis.	required
`pi`	`array_like`	Position vector of a point on the circle.	required

acceleration ¶

acceleration(s: float) -> ndarray

Calculate second derivative with respect to arc length.

Parameters:

Name	Type	Description	Default
`s`	`float`	Arc length parameter.	required

Returns:

Type	Description
`ndarray`	Acceleration vector.

all_traj ¶

all_traj(num_points: int = 100) -> dict[str, ndarray]

Generate a complete trajectory around the entire circular path.

Parameters:

Name	Type	Description	Default
`num_points`	`int`	Number of points to generate around the circle. Default is 100.	`100`

Returns:

Type	Description
`dict[str, ndarray]`	Dictionary containing arrays for position, velocity, and acceleration. Each array has shape (num_points, 3).

evaluate_at ¶

evaluate_at(
    s_values: float | list[float] | ndarray,
) -> dict[str, ndarray]

Evaluate position, velocity, and acceleration at specific arc length values.

Parameters:

Name	Type	Description	Default
`s_values`	`float or array_like`	Arc length parameter(s).	required

Returns:

Type	Description
`dict[str, ndarray]`	Dictionary containing arrays for position, velocity, and acceleration. Each array has shape (n, 3) where n is the number of s values.

position ¶

position(s: float | ndarray) -> ndarray

Calculate position at arc length s.

Parameters:

Name	Type	Description	Default
`s`	`float or array_like`	Arc length parameter(s).	required

Returns:

Type	Description
`ndarray`	Position vector(s) at the specified arc length(s).

velocity ¶

velocity(s: float) -> ndarray

Calculate first derivative with respect to arc length.

Parameters:

Name	Type	Description	Default
`s`	`float`	Arc length parameter.	required

Returns:

Type	Description
`ndarray`	Velocity (tangent) vector.

Frenet-frame functions¶

interpolatepy.compute_trajectory_frames ¶

compute_trajectory_frames(
    position_func: Callable[
        [float], tuple[ndarray, ndarray, ndarray]
    ],
    u_values: ndarray,
    tool_orientation: float
    | tuple[float, float, float]
    | None = None,
) -> tuple[ndarray, ndarray]

Compute Frenet frames along a parametric curve and optionally apply tool orientation.

Parameters:

Name	Type	Description	Default
`position_func`	`callable`	A function that takes a parameter u and returns: - position p(u) - first derivative dp/du - second derivative d2p/du2	required
`u_values`	`ndarray`	Parameter values at which to compute the frames.	required
`tool_orientation`	`float or tuple`	If None: Returns the Frenet frames without modification. If float: Angle in radians to rotate around the binormal axis (legacy mode). If tuple: (roll, pitch, yaw) angles in radians representing RPY rotations.	`None`

Returns:

Name	Type	Description
`points`	`ndarray`	Points on the curve with shape (len(u_values), 3).
`frames`	`ndarray`	Frames at each point [et, en, eb] with shape (len(u_values), 3, 3), either Frenet frames or tool frames.

interpolatepy.helicoidal_trajectory_with_derivatives ¶

helicoidal_trajectory_with_derivatives(
    u: float, r: float = 2.0, d: float = 0.5
) -> tuple[ndarray, ndarray, ndarray]

Return a circular helix and its first two parameter derivatives.

Parameters:

Name	Type	Description	Default
`u`	`float`	Parameter value.	required
`r`	`float`	Radius of the helix, by default 2.0.	`2.0`
`d`	`float`	Pitch parameter, by default 0.5.	`0.5`

Returns:

Name	Type	Description
`p`	`ndarray`	Position vector.
`dp_du`	`ndarray`	First derivative vector.
`d2p_du2`	`ndarray`	Second derivative vector.

interpolatepy.circular_trajectory_with_derivatives ¶

circular_trajectory_with_derivatives(
    u: float, r: float = 2.0
) -> tuple[ndarray, ndarray, ndarray]

Circular trajectory function returning position and derivatives.

Parameters:

Name	Type	Description	Default
`u`	`float`	Parameter value.	required
`r`	`float`	Radius of the circle, by default 2.0.	`2.0`

Returns:

Name	Type	Description
`p`	`ndarray`	Position vector.
`dp_du`	`ndarray`	First derivative vector.
`d2p_du2`	`ndarray`	Second derivative vector.

interpolatepy.plot_frames ¶

plot_frames(
    ax: Axes,
    points: ndarray,
    frames: ndarray,
    scale: float = 0.5,
    skip: int = 5,
    colors: list[str] | None = None,
) -> None

Plot the trajectory and frames.

Parameters:

Name	Type	Description	Default
`ax`	`Axes`	The 3D axes to plot on.	required
`points`	`ndarray`	Points on the trajectory with shape (n, 3).	required
`frames`	`ndarray`	Frames at each point [et, en, eb] with shape (n, 3, 3).	required
`scale`	`float`	Scale factor for the frame vectors, by default 0.5.	`0.5`
`skip`	`int`	Number of frames to skip between plotted frames, by default 5.	`5`
`colors`	`list of str`	Colors for the three vectors, by default ['r', 'g', 'b'].	`None`

Numerical utilities¶

interpolatepy.linear_traj ¶

linear_traj(
    p0: float | list[float] | ndarray,
    p1: float | list[float] | ndarray,
    t0: float,
    t1: float,
    time_array: ndarray,
) -> tuple[ndarray, ndarray, ndarray]

Generate points along a linear trajectory using NumPy vectorization.

This function computes positions, velocities, and accelerations for points along a linear trajectory between starting position p0 and ending position p1. The trajectory is calculated for each time point in time_array.

Parameters:

Name	Type	Description	Default
`p0`	`float or list[float] or ndarray`	Starting position. Can be a scalar for 1D motion or an array/list for multi-dimensional motion.	required
`p1`	`float or list[float] or ndarray`	Ending position. Must have the same dimensionality as p0.	required
`t0`	`float`	Start time of the trajectory.	required
`t1`	`float`	End time of the trajectory.	required
`time_array`	`ndarray`	Array of time points at which to calculate the trajectory.	required

Returns:

Name	Type	Description
`positions`	`ndarray`	Array of positions at each time point. For scalar inputs, shape is (len(time_array),). For vector inputs, shape is (len(time_array), dim) where dim is the dimension of p0/p1.
`velocities`	`ndarray`	Constant velocity at each time point, with the same shape as positions.
`accelerations`	`ndarray`	Zero acceleration at each time point, with the same shape as positions.

Examples:

Scalar positions (1D motion):

>>> import numpy as np
>>> times = np.linspace(0, 1, 5)
>>> pos, vel, acc = linear_traj(0, 1, 0, 1, times)
>>> print(pos)
[0.   0.25 0.5  0.75 1.  ]
>>> print(vel)
[1. 1. 1. 1. 1.]
>>> print(acc)
[0. 0. 0. 0. 0.]

Vector positions (2D motion):

>>> import numpy as np
>>> times = np.linspace(0, 2, 3)
>>> p0 = [0, 0]  # Start at origin
>>> p1 = [4, 6]  # End at point (4, 6)
>>> pos, vel, acc = linear_traj(p0, p1, 0, 2, times)
>>> print(pos)
[[0. 0.]
 [2. 3.]
 [4. 6.]]
>>> print(vel)
[[2. 3.]
 [2. 3.]
 [2. 3.]]

Notes

This function implements linear interpolation with constant velocity and zero acceleration.
For vector inputs (multi-dimensional motion), proper broadcasting is applied to ensure correct calculation across all dimensions.
The function handles both scalar and vector inputs automatically:
- For scalar inputs: outputs have shape (len(time_array),)
- For vector inputs: outputs have shape (len(time_array), dim)
Time points outside the range [t0, t1] will still produce valid positions by extrapolating the linear trajectory.
The velocity is always constant and equal to (p1 - p0) / (t1 - t0).
The acceleration is always zero.

interpolatepy.solve_tridiagonal ¶

solve_tridiagonal(
    lower_diagonal: ndarray,
    main_diagonal: ndarray,
    upper_diagonal: ndarray,
    right_hand_side: ndarray,
) -> ndarray

Solve a tridiagonal system using the Thomas algorithm.

This function solves the equation Ax = b where A is a tridiagonal matrix. The system is solved efficiently using the Thomas algorithm (also known as the tridiagonal matrix algorithm).

Parameters:

Name	Type	Description	Default
`lower_diagonal`	`ndarray`	Lower diagonal elements (first element is not used). Must have the same length as main_diagonal.	required
`main_diagonal`	`ndarray`	Main diagonal elements.	required
`upper_diagonal`	`ndarray`	Upper diagonal elements (last element is not used). Must have the same length as main_diagonal.	required
`right_hand_side`	`ndarray`	Right-hand side vector of the equation.	required

Returns:

Type	Description
`ndarray`	Solution vector x.

Raises:

Type	Description
`ValueError`	If a pivot is zero during forward elimination.

Examples:

>>> import numpy as np
>>> a = np.array([0, 1, 2, 3])  # Lower diagonal (a[0] is not used)
>>> b = np.array([2, 3, 4, 5])  # Main diagonal
>>> c = np.array([1, 2, 3, 0])  # Upper diagonal (c[-1] is not used)
>>> d = np.array([1, 2, 3, 4])  # Right hand side
>>> x = solve_tridiagonal(a, b, c, d)
>>> print(x)

Notes

The Thomas algorithm is a specialized form of Gaussian elimination for tridiagonal systems. It is much more efficient than general Gaussian elimination, with a time complexity of O(n) instead of O(n³).

The algorithm consists of two phases: 1. Forward elimination to transform the matrix into an upper triangular form 2. Back substitution to find the solution

The authoritative export list is interpolatepy.__all__. Internal module names, implementation attributes, C++ submodules, and visualization helpers not listed there may change without a compatibility guarantee.

API reference¶

Package information¶

Scalar splines¶

CubicSpline¶

interpolatepy.CubicSpline ¶

evaluate ¶

evaluate_velocity ¶

evaluate_acceleration ¶

plot ¶

CubicSmoothingSpline¶

interpolatepy.CubicSmoothingSpline ¶

evaluate ¶

evaluate_velocity ¶

evaluate_acceleration ¶

plot ¶

Smoothing tolerance search¶

interpolatepy.SplineConfig dataclass ¶

interpolatepy.smoothing_spline_with_tolerance ¶

CubicSplineWithAcceleration1¶

interpolatepy.CubicSplineWithAcceleration1 ¶

evaluate ¶

evaluate_velocity ¶

evaluate_acceleration ¶

plot ¶

CubicSplineWithAcceleration2¶

interpolatepy.CubicSplineWithAcceleration2 ¶

evaluate ¶

evaluate_velocity ¶

evaluate_acceleration ¶

interpolatepy.SplineParameters dataclass ¶

B-splines¶

BSpline¶

interpolatepy.BSpline ¶

__repr__ ¶

basis_function_derivatives ¶

basis_functions ¶

create_periodic_knots staticmethod ¶

create_uniform_knots staticmethod ¶

evaluate ¶

evaluate_derivative ¶

find_knot_span ¶

generate_curve_points ¶

plot_2d ¶

plot_3d ¶

BSplineInterpolator¶

interpolatepy.BSplineInterpolator ¶

plot_with_points ¶

plot_with_points_3d ¶

CubicBSplineInterpolation¶

interpolatepy.CubicBSplineInterpolation ¶

ApproximationBSpline¶

interpolatepy.ApproximationBSpline ¶

calculate_approximation_error ¶

refine ¶

SmoothingCubicBSpline¶

interpolatepy.SmoothingCubicBSpline ¶

calculate_approximation_error ¶

calculate_smoothness_measure ¶

calculate_total_error ¶

interpolatepy.BSplineParams dataclass ¶

Motion profiles¶

DoubleSTrajectory¶

interpolatepy.DoubleSTrajectory ¶

create_trajectory staticmethod ¶

evaluate ¶

evaluate_acceleration ¶

evaluate_full ¶

evaluate_jerk ¶

evaluate_velocity ¶

get_duration ¶

get_phase_durations ¶

interpolatepy.StateParams dataclass ¶

interpolatepy.TrajectoryBounds dataclass ¶

__post_init__ ¶

TrapezoidalTrajectory¶

interpolatepy.TrapezoidalTrajectory ¶

calculate_heuristic_velocities staticmethod ¶

generate_trajectory staticmethod ¶

interpolate_waypoints classmethod ¶

interpolatepy.trapezoidal.TrajectoryParams dataclass ¶

interpolatepy.SplineConfig `dataclass` ¶

interpolatepy.SplineParameters `dataclass` ¶

repr ¶

create_periodic_knots `staticmethod` ¶

create_uniform_knots `staticmethod` ¶

interpolatepy.BSplineParams `dataclass` ¶

create_trajectory `staticmethod` ¶

interpolatepy.StateParams `dataclass` ¶

interpolatepy.TrajectoryBounds `dataclass` ¶

calculate_heuristic_velocities `staticmethod` ¶

generate_trajectory `staticmethod` ¶

interpolate_waypoints `classmethod` ¶

interpolatepy.trapezoidal.TrajectoryParams `dataclass` ¶

interpolatepy.CalculationParams `dataclass` ¶

interpolatepy.InterpolationParams `dataclass` ¶

heuristic_velocities `staticmethod` ¶

multipoint_trajectory `classmethod` ¶

order_3_trajectory `staticmethod` ¶

order_5_trajectory `staticmethod` ¶

order_7_trajectory `staticmethod` ¶

interpolatepy.BoundaryCondition `dataclass` ¶

interpolatepy.TimeInterval `dataclass` ¶

interpolatepy.TrajectoryParams `dataclass` ¶

w `property` ¶

x `property` ¶

y `property` ¶

z `property` ¶

Integ_quat `staticmethod` ¶

Omega `staticmethod` ¶

Slerp_prime `staticmethod` ¶

Squad `staticmethod` ¶

Squad_prime `staticmethod` ¶

add ¶

eq ¶

mul ¶

neg ¶

repr ¶

rmul ¶

str ¶

sub ¶

truediv ¶

compute_intermediate_quaternion `staticmethod` ¶

from_angle_axis `classmethod` ¶

from_euler_angles `classmethod` ¶

from_rotation_matrix `classmethod` ¶

identity `classmethod` ¶

integ_trap_quat_s `staticmethod` ¶

integ_trap_quat_v `staticmethod` ¶

len ¶

repr ¶