Path¶

Path objects own the geometric path q(s) used by every solver family. Python defaults to sample-major matrices, where rows are station samples or waypoints and columns are dimensions. Pass layout="dim_major" only when sharing arrays with an external dim-major pipeline.

All path evaluation methods return PathDerivatives. evaluate_q is the position-only form and fills only out.q; evaluate_up_to_2nd and evaluate_up_to_3rd fill out.q plus the requested derivative fields. Use the fields explicitly:

q = path.evaluate_q(s).q
out = path.evaluate_up_to_2nd(s)
q, dq, ddq = out.q, out.dq, out.ddq

Waypoint paths are built with Path.from_waypoints_interpolating, which passes through every waypoint (Path.from_waypoints is an equivalent alias), or with Path.from_waypoints_fitting, a tolerance-bounded C4 quintic fit whose diagnostics are available from Path.smoothing_report. Both constructor families are unstable: names, signatures, and configuration types may change as more waypoint algorithms are added.

class copp_py.path.SplineConfig(*, order=5, s_min=0.0, s_max=1.0, out_of_range='error', parametrization='uniform', start_state=None, end_state=None)¶

Bases: object

Python-owned waypoint spline configuration backed by [RustSplineConfig].

end_state¶: Return a copy of the end boundary derivative matrix, if present.

order¶: Return the spline order stored in this Python config object.

out_of_range¶: Return the out-of-range evaluation policy.

parametrization¶: Return the waypoint parametrization policy.

s_max¶: Return the upper endpoint of the path parameter range.

s_min¶: Return the lower endpoint of the path parameter range.

start_state¶: Return a copy of the start boundary derivative matrix, if present.

class copp_py.path.SmoothingConfig(*, tolerance=0.001, axes=None, parameters=None, max_refinements=20, max_segments=20000, out_of_range='error')¶

Bases: object

Python-owned tolerance-bounded fitting configuration backed by [RustSmoothingConfig].

axes¶: Return the selected 0-based path dimensions, or None for all.

max_refinements¶: Return the maximum number of adaptive knot-refinement passes.

max_segments¶: Return the maximum number of spans used by the selected axes.

out_of_range¶: Return the out-of-range evaluation policy.

parameters¶: Return a copy of the waypoint parameters, if present.

tolerance¶: Return the tolerance as a float (uniform) or a per-axis array.

class copp_py.path.SmoothingReport¶

Bases: object

Python-visible construction diagnostics of a tolerance-fitted waypoint path.

axes¶: Return the selected 0-based path dimensions in tolerance/report order.

checked_intervals¶: Return the cumulative number of reference intervals visited by audits.

fitting_rows¶: Return the cumulative number of fitting rows assembled.

interpolated_segments¶: Return the number of spans in the separate unselected-axis interpolant.

max_errors¶

Return the final whole-domain absolute-error bound per selected axis.

Values are in input units and follow axes order. They are Bernstein-derived numerical bounds computed in ordinary floating-point arithmetic, not formal certificates or Cartesian errors.

refinements¶: Return the number of completed local knot-refinement passes.

segments¶: Return the number of final polynomial spans shared by the selected axes.

class copp_py.path.PathDerivatives¶

Bases: object

Python-visible path evaluation result container.

dddq¶: Third derivative samples, or None when not requested.

ddq¶: Second derivative samples, or None when not requested.

dq¶: First derivative samples, or None when not requested.

q¶: Position samples as a [PyArray2] in the path’s selected output layout.

class copp_py.path.Path¶

Bases: object

Python-owned wrapper around the Rust [RustPath] object.

dim¶: Return the number of path dimensions.

evaluate_q(s)¶

Evaluate position q only at the query path parameters.

Returns a PathDerivatives object whose q field is populated and whose derivative fields are None.

evaluate_up_to_2nd(s)¶

Evaluate position, first derivative, and second derivative.

Returns a PathDerivatives object with q, dq, and ddq populated. dddq is None.

evaluate_up_to_3rd(s)¶

Evaluate position and derivatives up to third order.

Returns a PathDerivatives object with q, dq, ddq, and dddq populated.

static from_autograd(q_fn, s_min, s_max, *, layout='sample_major')¶

Build a path from a scalar-parametric Python callable using Autograd.

This is the lightweight Python AD alternative to [Self::from_jax]. The Autograd dependency is imported lazily only when this constructor is called.

Parameters:

q_fn (callable) – Scalar-parametric function q_fn(s) returning one path vector. The function should use autograd.numpy operations so Autograd can trace it.
s_min (float) – Valid path-parameter range. Autograd-backed paths currently match the Rust evaluator API and reject out-of-range queries.
s_max (float) – Valid path-parameter range. Autograd-backed paths currently match the Rust evaluator API and reject out-of-range queries.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout used for returned derivative arrays.

Raises:

ImportError – If Autograd is not installed.
ValueError – If the callback output is invalid.

static from_casadi(q_expr, *, symbol, s_min=0.0, s_max=1.0, layout='sample_major')¶

Build a path from a scalar-parameter CasADi expression.

The expression is converted to a Python evaluator by copp_py._parametric and then delegated to [Self::from_evaluator_3rd]. This keeps CasADi optional and outside the Rust dependency graph.

Parameters:

q_expr (casadi.SX | casadi.MX | sequence) – Vector expression for the path position.
symbol (casadi.SX | casadi.MX) – Scalar path parameter used to differentiate q_expr.
s_min (float, default=0.0, 1.0) – Valid path-parameter range.
s_max (float, default=0.0, 1.0) – Valid path-parameter range.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout used for returned derivative arrays.

static from_evaluator(evaluator, s_min, s_max, *, layout='sample_major')¶

Compatibility alias for Path.from_evaluator_3rd.

New Python code should prefer from_evaluator_2nd or from_evaluator_3rd so the supported derivative order is explicit.

static from_evaluator_2nd(evaluator, s_min, s_max, *, layout='sample_major')¶

Build a path from a Python evaluator object with derivatives up to second order.

Parameters:

evaluator (object) – Python object implementing the evaluator protocol. It must provide dim as an integer attribute or zero-argument method, and evaluate_up_to_2nd(s) -> (q, dq, ddq). evaluate_q(s) -> q is optional and is used when available.
s_min (float) – Valid path-parameter range. Evaluator-backed paths currently match the Rust API and reject out-of-range queries.
s_max (float) – Valid path-parameter range. Evaluator-backed paths currently match the Rust API and reject out-of-range queries.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout expected from callback return arrays and used for returned derivative arrays.

Raises:

ValueError – If the evaluator protocol or callback return arrays are invalid.
CoppError – If the Rust COPP core rejects the path range or evaluator dimension.
Exception – Any exception raised by the Python evaluator callback is propagated unchanged.

static from_evaluator_3rd(evaluator, s_min, s_max, *, layout='sample_major')¶

Build a path from a Python evaluator object with derivatives up to third order.

Parameters:

evaluator (object) – Python object implementing the evaluator protocol. It must provide dim as an integer attribute or zero-argument method, and evaluate_up_to_3rd(s) -> (q, dq, ddq, dddq). evaluate_q and evaluate_up_to_2nd are optional. If evaluate_up_to_2nd is omitted, second-order evaluation calls evaluate_up_to_3rd and discards dddq; this is supported for convenience but not recommended for performance-sensitive code.
s_min (float) – Valid path-parameter range. Evaluator-backed paths currently match the Rust API and reject out-of-range queries.
s_max (float) – Valid path-parameter range. Evaluator-backed paths currently match the Rust API and reject out-of-range queries.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout expected from callback return arrays and used for returned derivative arrays.

Raises:

ValueError – If the evaluator protocol or callback return arrays are invalid.
CoppError – If the Rust COPP core rejects the path range or evaluator dimension.
Exception – Any exception raised by the Python evaluator callback is propagated unchanged.

static from_jax(q_fn, s_min, s_max, *, layout='sample_major', jit=True, require_x64=True)¶

Build a path from a scalar-parametric Python callable using JAX.

This convenience constructor lives in the Python facade layer. It lazily imports copp_py._parametric, builds a JAX-backed Python evaluator object, and delegates to [Self::from_evaluator_3rd]. The Rust core still receives the same [PathEvaluator3rd] protocol as explicit evaluator-backed paths.

Parameters:

q_fn (callable) – Scalar-parametric function q_fn(s) returning one path vector. The function should use jax.numpy operations so JAX can trace it.
s_min (float) – Valid path-parameter range. Parametric paths currently match the Rust evaluator API and reject out-of-range queries.
s_max (float) – Valid path-parameter range. Parametric paths currently match the Rust evaluator API and reject out-of-range queries.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout used for returned derivative arrays.
jit (bool, default=True) – JIT-compile the JAX batched evaluator.
require_x64 (bool, default=True) – Require JAX 64-bit mode before constructing the path.

Raises:

ImportError – If the selected optional dependency is not installed.
ValueError – If the callback output or JAX configuration is invalid.

static from_sympy(q_exprs, *, symbol, s_min=0.0, s_max=1.0, layout='sample_major')¶

Build a path from scalar-parameter SymPy expressions.

The SymPy expressions are differentiated in Python and wrapped as a [PathEvaluator3rd] object before entering the Rust core.

Parameters:

q_exprs (sympy.Expr | sequence | sympy.Matrix) – Position expression or vector of position expressions.
symbol (sympy.Symbol) – Scalar path parameter used to differentiate q_exprs.
s_min (float, default=0.0, 1.0) – Valid path-parameter range.
s_max (float, default=0.0, 1.0) – Valid path-parameter range.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout used for returned derivative arrays.

static from_waypoints(waypoints, config=None, *, order=5, s_min=0.0, s_max=1.0, out_of_range='error', parametrization='uniform', start_state=None, end_state=None, layout='sample_major')¶

Build a waypoint spline path.

Equivalent alias for Path.from_waypoints_interpolating: both names accept the same arguments and build the same interpolating path.

Parameters:

waypoints (ArrayLike) – Waypoint matrix convertible to float64. With the default MatrixLayout.SAMPLE_MAJOR, shape is (n_points, dim) and each row is one waypoint. With MatrixLayout.DIM_MAJOR, shape is (dim, n_points) and each column is one waypoint.
config (SplineConfig | None, default=None) – Spline construction options. When omitted, keyword arguments build an equivalent temporary SplineConfig.
order (int, default=5) – Odd spline order used only when config is omitted.
s_min (float, default=0.0, 1.0) – Path-parameter range used only when config is omitted.
s_max (float, default=0.0, 1.0) – Path-parameter range used only when config is omitted.
out_of_range (OutOfRangeMode | str, default=OutOfRangeMode.ERROR) – Out-of-range policy used only when config is omitted.
parametrization (Parametrization | str, default=Parametrization.UNIFORM) – Waypoint parameter assignment used only when config is omitted.
start_state (ArrayLike | None) – Boundary derivative matrices used only when config is omitted.
end_state (ArrayLike | None) – Boundary derivative matrices used only when config is omitted.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout for both input waypoints and returned derivative arrays. Strings "sample_major" and "dim_major" are accepted for convenience.

Returns:

A Python-owned wrapper around the Rust path object.

Return type:

Path

Raises:

ValueError – If array layout, dtype, wrapper-level options, or mixed config/keyword options are invalid.
CoppError – If the Rust COPP core rejects the path data or spline options.

static from_waypoints_fitting(waypoints, config=None, *, tolerance=0.001, axes=None, parameters=None, max_refinements=20, max_segments=20000, out_of_range='error', layout='sample_major')¶

Build a tolerance-bounded fitted waypoint path.

The path is an adaptive nonuniform quintic B-spline with C4 continuity. Unlike Path.from_waypoints_interpolating, it does not pass through interior waypoints: each selected axis may deviate from the piecewise-linear reference polyline through the waypoints by at most its tolerance. The absolute error is audited at the same path parameter over every complete reference interval, not only at the waypoints. Endpoints are retained. Unselected axes keep quintic C4 interpolation through every waypoint. Construction diagnostics are available from Path.smoothing_report.

This constructor family is unstable: names, signatures, and configuration types may change as more waypoint algorithms are added.

Parameters:

waypoints (ArrayLike) – Waypoint matrix convertible to float64. With the default MatrixLayout.SAMPLE_MAJOR, shape is (n_points, dim) and each row is one waypoint. With MatrixLayout.DIM_MAJOR, shape is (dim, n_points) and each column is one waypoint.
config (SmoothingConfig | None, default=None) – Fitting options. When omitted, keyword arguments build an equivalent temporary SmoothingConfig.
tolerance (float | ArrayLike, default=0.001) – Absolute per-axis tolerance used only when config is omitted.
axes (list[int] | None, default=None) – Selected 0-based path dimensions used only when config is omitted.
parameters (ArrayLike | None, default=None) – Waypoint parameters used only when config is omitted.
max_refinements (int, default=20) – Refinement-pass budget used only when config is omitted.
max_segments (int, default=20000) – Selected-axis span budget used only when config is omitted.
out_of_range (OutOfRangeMode | str, default=OutOfRangeMode.ERROR) – Out-of-range policy used only when config is omitted.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout for both input waypoints and returned derivative arrays. Strings "sample_major" and "dim_major" are accepted for convenience.

Returns:

A Python-owned wrapper around the Rust path object.

Return type:

Path

Raises:

ValueError – If array layout, dtype, wrapper-level options, or mixed config/keyword options are invalid.
PathError – If the Rust COPP core rejects the waypoints or options, or cannot satisfy the tolerance within the configured budgets.

static from_waypoints_interpolating(waypoints, config=None, *, order=5, s_min=0.0, s_max=1.0, out_of_range='error', parametrization='uniform', start_state=None, end_state=None, layout='sample_major')¶

Build a waypoint spline path that interpolates every waypoint.

The path passes exactly through every waypoint. Use Path.from_waypoints_fitting instead when waypoints only need to be followed within a tolerance. This constructor family is unstable: names, signatures, and configuration types may change as more waypoint algorithms are added.

Parameters:

waypoints (ArrayLike) – Waypoint matrix convertible to float64. With the default MatrixLayout.SAMPLE_MAJOR, shape is (n_points, dim) and each row is one waypoint. With MatrixLayout.DIM_MAJOR, shape is (dim, n_points) and each column is one waypoint.
config (SplineConfig | None, default=None) – Spline construction options. When omitted, keyword arguments build an equivalent temporary SplineConfig.
order (int, default=5) – Odd spline order used only when config is omitted.
s_min (float, default=0.0, 1.0) – Path-parameter range used only when config is omitted.
s_max (float, default=0.0, 1.0) – Path-parameter range used only when config is omitted.
out_of_range (OutOfRangeMode | str, default=OutOfRangeMode.ERROR) – Out-of-range policy used only when config is omitted.
parametrization (Parametrization | str, default=Parametrization.UNIFORM) – Waypoint parameter assignment used only when config is omitted.
start_state (ArrayLike | None) – Boundary derivative matrices used only when config is omitted.
end_state (ArrayLike | None) – Boundary derivative matrices used only when config is omitted.
layout (MatrixLayout | str, default=MatrixLayout.SAMPLE_MAJOR) – Matrix layout for both input waypoints and returned derivative arrays. Strings "sample_major" and "dim_major" are accepted for convenience.

Returns:

A Python-owned wrapper around the Rust path object.

Return type:

Path

Raises:

ValueError – If array layout, dtype, wrapper-level options, or mixed config/keyword options are invalid.
CoppError – If the Rust COPP core rejects the path data or spline options.

s_range¶: Return the inclusive valid path parameter range.

smoothing_report¶

Return construction diagnostics of a tolerance-fitted waypoint path.

None for paths not built by Path.from_waypoints_fitting, such as interpolated, evaluator-backed, and parametric paths.

Path¶

copp-py

Navigation

Related Topics