Struct Robot 

pub struct Robot<M: RobotBasic> {
    pub constraints: Constraints,
    /* private fields */
}

User-facing robot wrapper that owns constraint storage and conversion logic.

Design role

Robot<M> bridges robot-side physical constraints and solver-side normalized inequalities. Internally it owns Constraints, but exposes higher-level APIs with physical semantics.

Why prefer this over direct Constraints

For most applications, Robot is the recommended entry because it provides domain-meaningful methods (with_axial_velocity, with_axial_acceleration, with_axial_jerk, with_axial_torque) and enforces common contracts.

Trait requirements by solver family

• Topp*Problem: model type M only needs RobotBasic.
• Copp*Problem: model type M must implement RobotTorque.

If you do not have a real inverse-dynamics model yet, use usize as a placeholder implementing RobotTorque (tau = ddq).

Example

The example below builds a two-dimensional point-mass robot, writes a station grid and path derivatives, then adds velocity, acceleration, and jerk constraints in one chain.

use copp::robot::Robot;
use nalgebra::DMatrix;

let mut robot = Robot::with_capacity(2usize, 3);
let s = [0.0, 0.5, 1.0];

let q = DMatrix::from_row_slice(
    2,
    3,
    &[
        0.0, 0.5, 1.0,
        1.0, 0.5, 0.0,
    ],
);
let dq = DMatrix::from_row_slice(
    2,
    3,
    &[
        1.0, 1.0, 1.0,
        -1.0, -1.0, -1.0,
    ],
);
let ddq = DMatrix::zeros(2, 3);
let dddq = DMatrix::zeros(2, 3);
let dddq_view = dddq.as_view();

let vel_max = [2.0, 2.0];
let vel_min = [-2.0, -2.0];
let acc_max = [3.0, 3.0];
let acc_min = [-3.0, -3.0];
let jerk_max = [10.0, 10.0];
let jerk_min = [-10.0, -10.0];

robot
    .with_s(s.as_slice())?
    .with_q(&q.as_view(), &dq.as_view(), &ddq.as_view(), Some(&dddq_view), 0)?
    .with_axial_velocity((vel_max.as_slice(), s.len()), (vel_min.as_slice(), s.len()), 0)?
    .with_axial_acceleration((acc_max.as_slice(), s.len()), (acc_min.as_slice(), s.len()), 0)?
    .with_axial_jerk((jerk_max.as_slice(), s.len()), (jerk_min.as_slice(), s.len()), 0)?;

assert_eq!(robot.constraints.len(), 3);

Fields

constraints: Constraints

Shared station-indexed constraint buffer used by TOPP/COPP solvers.

Implementations

impl<M: RobotBasic> Robot<M>

pub fn model(&self) -> &M

Access the robot model M: RobotBasic as a reference.

pub fn model_mut(&mut self) -> &mut M

Mutably access the robot model M: RobotBasic.

pub fn new(model: M) -> Self

Construct a robot wrapper with default constraint-buffer capacity.

Parameters

• model: concrete robot model implementing RobotBasic.

pub fn with_capacity(model: M, capacity: usize) -> Self

Construct a robot wrapper with explicit initial constraint capacity.

Parameters

• model: concrete robot model.
• capacity: initial circular-buffer column capacity.

pub fn dim(&self) -> usize

Get robot dimension / DoF.

pub fn with_s<T: AsInputMatrix1D + ?Sized>( &mut self, s_new: &T, ) -> Result<&mut Self, ConstraintError>

Append a new station segment into the internal constraint buffer.

This is the robot-level convenience wrapper for Constraints::with_s. Use the lower-level method directly when constructing Constraints without a robot model.

Parameters

• s_new: station samples accepted as 1D slice or matrix view.

Errors

• ConstraintError::NonIncreasingS if s_new is not strictly increasing, or if its first sample does not come after the current last stored station.

Returns

Returns &mut Self for chaining on success.

pub fn with_q( &mut self, q_new: &InputMatrix<'_>, dq_new: &InputMatrix<'_>, ddq_new: &InputMatrix<'_>, dddq_new: Option<&InputMatrix<'_>>, idx_s: usize, ) -> Result<&mut Self, ConstraintError>

Write path derivatives over interval starting at idx_s.

Parameters

• q_new, dq_new, ddq_new: required derivative matrices.
• dddq_new: optional third derivative matrix.
• idx_s: global start station id.

Behavior

• If dddq_new is provided, third-order derivative data is written for the target interval.
• If dddq_new is None, existing third-order derivative data is cleared over the target interval.

Errors

• ConstraintError::NoMatchDimensions if derivative matrix shapes are inconsistent with each other or with the robot dimension.
• ConstraintError::OutOfSBounds if the target station interval is outside the stored station range.

Returns

Returns &mut Self for chaining on success.

pub fn with_q_from_path_2nd( &mut self, path: &Path, idx_s_from: usize, idx_s_to: usize, ) -> Result<&mut Self, CoppError>

Sample a path over an existing station interval and store derivatives up to second order.

Parameters

• path: geometric path to evaluate at the stored station samples.
• idx_s_from: global start station id (inclusive).
• idx_s_to: global end station id (exclusive).

Behavior

• Reads the station samples already stored in [idx_s_from, idx_s_to).
• Evaluates q, dq, and ddq from path at those samples.
• Copies the evaluated derivatives into the robot’s constraint storage.
• Clears third-order derivative data over the sampled interval.
• Does not store a borrow of path; the path may be dropped after this call.

Errors

• CoppError::ConstraintError if the station interval is empty, out of bounds, or the evaluated path dimension does not match the robot dimension.
• CoppError::PathError if path evaluation fails, for example because a stored station is outside the path range.

Returns

Returns &mut Self for chaining on success.

pub fn with_q_from_path_3rd( &mut self, path: &Path, idx_s_from: usize, idx_s_to: usize, ) -> Result<&mut Self, CoppError>

Sample a path over an existing station interval and store derivatives up to third order.

Parameters

• path: geometric path to evaluate at the stored station samples.
• idx_s_from: global start station id (inclusive).
• idx_s_to: global end station id (exclusive).

Behavior

• Reads the station samples already stored in [idx_s_from, idx_s_to).
• Evaluates q, dq, ddq, and dddq from path at those samples.
• Copies the evaluated derivatives into the robot’s constraint storage.
• Does not store a borrow of path; the path may be dropped after this call.

Errors

• CoppError::ConstraintError if the station interval is empty, out of bounds, or the evaluated path dimension does not match the robot dimension.
• CoppError::PathError if path evaluation fails, for example because a stored station is outside the path range.

Returns

Returns &mut Self for chaining on success.

pub fn with_axial_velocity<T1, T2>( &mut self, axial_velocity_max: T1, axial_velocity_min: T2, start_idx_s: usize, ) -> Result<&mut Self, ConstraintError>

where T1: UpperBound, T2: UpperBound,

Add axial velocity limits on interval starting at start_idx_s.

Input semantics

Enforces per-axis bounds: axial_velocity_min < \dot{q} < axial_velocity_max.

Mapping

Converts velocity bounds into first-order path-speed limits on a = \dot{s}^2, then fuses into amax.

Errors

• ConstraintError::NoMatchDimensions
• ConstraintError::OutOfSBounds
• ConstraintError::NoGivenQInfo
• ConstraintError::InvalidSignedBounds when max/min signs are invalid

Returns

Returns &mut Self for chaining on success.

pub fn with_axial_acceleration<T1, T2>( &mut self, axial_acceleration_max: T1, axial_acceleration_min: T2, start_idx_s: usize, ) -> Result<&mut Self, ConstraintError>

where T1: UpperBound, T2: UpperBound,

Add axial acceleration limits on interval starting at start_idx_s.

Input semantics

Enforces per-axis bounds: axial_acceleration_min < \ddot{q} < axial_acceleration_max.

Mapping

Generates second-order rows: acc_a * a + acc_b * b <= acc_max, where (a,b) are path-speed variables.

Errors

• ConstraintError::NoMatchDimensions
• ConstraintError::OutOfSBounds
• ConstraintError::NoGivenQInfo
• ConstraintError::InvalidSignedBounds

Returns

Returns &mut Self for chaining on success.

pub fn with_axial_jerk<T1, T2>( &mut self, axial_jerk_max: T1, axial_jerk_min: T2, start_idx_s: usize, ) -> Result<&mut Self, ConstraintError>

where T1: UpperBound, T2: UpperBound,

Add axial jerk limits on interval starting at start_idx_s.

Input semantics

Enforces per-axis bounds: axial_jerk_min < \dddot{q} < axial_jerk_max.

Mapping

Generates third-order rows used by TOPP3/COPP3: sqrt(a) * (jerk_a*a + jerk_b*b + jerk_c*c + jerk_d) <= jerk_max.

Errors

• ConstraintError::NoMatchDimensions
• ConstraintError::OutOfSBounds
• ConstraintError::NoGivenQInfo (needs q/dq/ddq/dddq)
• ConstraintError::InvalidSignedBounds

Returns

Returns &mut Self for chaining on success.

impl<M: RobotTorque> Robot<M>

pub fn with_axial_torque<T1, T2>( &mut self, axial_torque_max: T1, axial_torque_min: T2, start_idx_s: usize, ) -> Result<&mut Self, CoppError>

where T1: UpperBound, T2: UpperBound,

Add axial torque limits on interval starting at start_idx_s.

Input semantics

Enforces per-axis bounds: axial_torque_min < tau < axial_torque_max.

Mapping

Using inverse dynamics, torque limits are transformed into second-order rows on (a,b) and appended to the constraint buffer.

For a fuller inverse-dynamics implementation used with this method, see the test reference model in robot_2dof.rs.

Errors

• ConstraintError::NoMatchDimensions
• ConstraintError::OutOfSBounds
• ConstraintError::NoGivenQInfo
• ConstraintError::InvalidSignedBounds
• RobotDynamicsError if inverse dynamics fails

Returns

Returns &mut Self for chaining on success.