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

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.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.

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.

Path¶

copp-py

Navigation

Related Topics