Robot And Constraints

Robot is the recommended high-level container for sampled path derivatives, physical limits, optional inverse dynamics, and the underlying raw constraint buffer. Use Constraints directly when you already have path-domain rows and do not need robot derivative storage.

Constraints.exceed_topp2 and Constraints.exceed_topp3 audit a solved profile against the stored limits and return maximum violation magnitudes. Each value is <= 0 when the profile is feasible and positive when violated. All values are NaN when fewer than two stations are given, the station range is unavailable, the station grid is not strictly increasing, the profile shapes are inconsistent, or the profile contains non-finite values.

class copp_py.robot.Robot(dim, *, capacity=None, inverse_dynamics=None)

Bases: object

Python-owned robot wrapper backed by [RustRobot].

add_acceleration_limits(lower, *, start_idx_s, length=None, layout='sample_major')

Add axial acceleration limits over an existing station interval.

add_jerk_limits(lower, *, start_idx_s, length=None, layout='sample_major')

Add axial jerk limits over an existing station interval.

add_torque_limits(lower, *, start_idx_s, length=None, layout='sample_major')

Add axial torque limits using point or Python inverse dynamics.

add_velocity_limits(lower, *, start_idx_s, length=None, layout='sample_major')

Add axial velocity limits over an existing station interval.

append_s(s)

Append strictly increasing station samples to the robot.

capacity

Return the allocated station-buffer capacity.

clear_inverse_dynamics()

Clear the Python inverse-dynamics callback and restore point dynamics.

constraints

Return a lightweight proxy for raw constraint-buffer operations.

dim

Return the robot dimension.

has_inverse_dynamics

Return whether a Python inverse-dynamics callback is installed.

idx_s_range

Return the active global station-id range (idx_s_start, idx_s_end).

is_empty

Return whether the constraint buffer contains no stations.

len

Return the number of station samples currently stored.

static point_mass(dim, *, capacity=None)

Construct an explicit point-mass robot, where tau = ddq.

set_inverse_dynamics(inverse_dynamics)

Replace the Python inverse-dynamics callback.

The callback may be a plain callable f(q, dq, ddq) or an object with a callable inverse_dynamics(q, dq, ddq) method. It must return a vector convertible to contiguous float64 with shape (dim,).

set_q(dq, ddq, idx_s, *, dddq=None, layout='sample_major')

Store discrete path derivatives over an existing station interval.

set_q_from_path_2nd(path, idx_s_from, idx_s_to)

Sample a path and store derivatives up to second order.

set_q_from_path_3rd(path, idx_s_from, idx_s_to)

Sample a path and store derivatives up to third order.

class copp_py.constraints.Constraints(dim, *, capacity=None)

Bases: object

Raw constraint-buffer proxy returned by [PyRobot::constraints].

add_constraint_1st(idx_s, *, layout='sample_major')

Add or tighten first-order raw constraints.

add_constraint_2nd(acc_b, acc_max, idx_s, *, is_negative=False, layout='sample_major')

Add second-order raw constraints.

add_constraint_3rd(jerk_b, jerk_c, jerk_d, jerk_max, idx_s, *, is_negative=False, layout='sample_major')

Add third-order raw constraints.

amax_substitute(amax, idx_s)

Overwrite first-order bounds over a station interval.

amax_values(idx_s_to=None)

Export first-order upper bounds over a half-open station-id interval.

append_s(s)

Append strictly increasing station samples to the constraint buffer.

capacity

Return the allocated station-buffer capacity.

clear()

Clear all stored constraints and station data.

dim

Return the robot/path dimension.

exceed_topp2(*, idx_s_start=0)

Evaluate maximum TOPP2 constraint violations of an a profile.

The path acceleration of each interval is reconstructed by the TOPP2 relation b[k] = (a[k+1] - a[k]) / (2 * ds[k]), and the second-order rows of both endpoint stations are checked against that interval’s b.

Parameters:

• a (ArrayLike) – One-dimensional node profile a = (ds/dt)^2 convertible to float64, sampled on the stations starting at idx_s_start.

• idx_s_start (int, default=0) – Global station index of a[0].

Returns:

(exceed_1st, exceed_2nd). Each value is <= 0 when the profile is feasible and positive when violated. The first-order term covers 0 <= a[k] <= amax[k]. Both values are NaN if the station range is unavailable or b cannot be reconstructed, i.e. fewer than two stations are given, the station grid is not strictly increasing, or a contains non-finite values.

Return type:

tuple[float, float]

Raises:

ValueError – If a cannot be converted to a one-dimensional float64 array.

exceed_topp3(b=None, *, num_stationary=None, idx_s_start=0)

Evaluate maximum TOPP3 constraint violations of an (a, b) profile.

The third-order term uses the original nonlinear sqrt(a) form, not the linearized rows, so it audits the profile that is actually delivered. Run it after post-processing such as Profile3rd.force_positive_a. The third-order term skips the two stationary boundary blocks described by num_stationary.

Parameters:

• a (ArrayLike | Profile3rd) – One-dimensional node profile a = (ds/dt)^2 convertible to float64, or a Profile3rd supplying a, b, and num_stationary together.

• b (ArrayLike | None, default=None) – Node profile b = dds/dt with the same length as a. Required unless a is a Profile3rd.

• num_stationary (tuple[int, int] | None, default=None) – Stationary boundary interval counts (start, end). None means (0, 0) for array input. Must be omitted when a is a Profile3rd, whose own counts are used.

• idx_s_start (int, default=0) – Global station index of a[0].

Returns:

(exceed_1st, exceed_2nd, exceed_3rd). Each value is <= 0 when the profile is feasible and positive when violated. All values are NaN if fewer than two stations are given, the station range is unavailable, the station grid is not strictly increasing, a and b disagree in length, or a or b contains non-finite values.

Return type:

tuple[float, float, float]

Raises:

ValueError – If an array cannot be converted to a one-dimensional float64 array, if b is missing for array input, or if b or num_stationary is combined with a Profile3rd.

idx_s_range

Return the active global station-id range (idx_s_start, idx_s_end).

is_empty

Return whether the constraint buffer contains no stations.

len

Return the number of station samples currently stored.

pop_back_n(n_cols)

Remove n_cols station samples from the back.

pop_back_until(idx_s_cut)

Remove back samples until the kept window ends before idx_s_cut.

pop_front_n(n_cols)

Remove n_cols station samples from the front.

pop_front_until(idx_s_cut)

Remove front samples until the kept window starts at idx_s_cut.

s_values(idx_s_to=None)

Export station samples over a half-open station-id interval.