Module constraints 

Constraint storage and access layer for TOPP/COPP pipelines.

Method identity

This module provides a circular-buffer based constraint container shared by:

• TOPP2 / COPP2 (first-order + second-order constraints),
• TOPP3 / COPP3 (plus nonlinear / linearized third-order constraints).

Data model (math + discrete code view)

Continuous/discrete state definition:

• $a(s) = \dot{s}^2$;
• $b(s) = \ddot{s} = \frac{1}{2}\frac{\mathrm{d}a}{\mathrm{d}s}$;
• $c(s) = \frac{\dddot{s}}{\dot{s}} = \frac{\mathrm{d}b}{\mathrm{d}s}$.

Continuous/discrete state definition at station $s_k$:

• $a_k = \dot{s}_k^2$;
• $b_k = \ddot{s}_k$;
• $c_k = \frac{\dddot{s}_k}{\dot{s}_k}$.

Discrete code symbols in this module:

• a[k] corresponds to $a_k$,
• b[k] corresponds to $b_k$,
• c[k] corresponds to $c_k$.

Constraint families:

• first-order rows: $a(s) \le a_{\text{max}}(s)$;
• second-order rows: $f_a(s) a(s) + f_b(s) b(s) \le f_{\text{max}}(s)$;
• third-order rows: $\sqrt{a(s)}(g_a(s) a(s) + g_b(s) b(s) + g_c(s) c(s) + g_d(s)) \le g_{\text{max}}(s)$;
• linearized third-order rows: $h_a(s) a(s) + h_b(s) b(s) + h_c(s) c(s) \le h_{\text{max}}(s)$.

API layering

• Public safe getters get_* (e.g. get_s, get_acc_constraints, get_jerk_constraints) return Result<_, ConstraintError> with explicit bounds contract.
• Internal fast getters *_unchecked are pub(crate) and require caller-side precondition guarantees.

User guidance

• For most users, prefer Robot as the entry point so constraints can be expressed with physical semantics (with_axial_velocity, with_axial_acceleration, torque-related APIs).
• Direct manipulation of Constraints is recommended for advanced users who need maximum flexibility and custom low-level constraint composition.

Contract summary

• Public APIs validate station range before indexing.
• Internal unchecked APIs are for hot paths and guarded by debug assertions.
• Linearized jerk access requires builders to call build_with_linearization(Topp3) or build_with_linearization(Copp3) beforehand.
• For robust solver behavior, keep zero-state a=b=c=0 strictly feasible at every station. In practice this means every active scalar RHS must stay strictly positive: amax > 0, acc_max > 0, and jerk_max > 0 (after sign normalization).

Structs

Constraints

Constraint storage and query object used by TOPP/COPP solvers.

Enums

ModePopConstraints

The mode for popping constraints.

Traits

AsInputMatrix1D

Conversion helper trait for 1D-like first-order inputs.

Type Aliases

InputMatrix

Borrowed 2D matrix view type accepted by constraint-ingestion APIs.