Planar PCS¶

The planar Piecewise Constant Strain (PCS) systems provide implementations for 2D soft continuum robots using the Cosserat rod theory with piecewise constant strain assumptions, based on the discrete Cosserat approach by Renda et al. (2018).

Overview¶

The PCS model divides the continuum robot into segments, each with constant strain properties. This approach, originally proposed by Renda et al. (2018), provides a good balance between computational efficiency and modeling accuracy for soft continuum robots.

Main Implementation¶

soromox.systems.pcs.planar_pcs ¶

PlanarPCS ¶

PlanarPCS(params: PlanarPCSParams, structure: PlanarPCSStructure | None = None, actuators: Actuator | tuple[Actuator, ...] | None = None, passive_elements: PassiveElement | tuple[PassiveElement, ...] | None = (), **kwargs: Any)

Bases: SoftRobot


              flowchart TD
              soromox.systems.pcs.planar_pcs.PlanarPCS[PlanarPCS]
              soromox.systems.soft_robot.SoftRobot[SoftRobot]
              soromox.systems.dynamical_system.DynamicalSystem[DynamicalSystem]

                              soromox.systems.soft_robot.SoftRobot --> soromox.systems.pcs.planar_pcs.PlanarPCS
                                soromox.systems.dynamical_system.DynamicalSystem --> soromox.systems.soft_robot.SoftRobot
                



              click soromox.systems.pcs.planar_pcs.PlanarPCS href "" "soromox.systems.pcs.planar_pcs.PlanarPCS"
              click soromox.systems.soft_robot.SoftRobot href "" "soromox.systems.soft_robot.SoftRobot"
              click soromox.systems.dynamical_system.DynamicalSystem href "" "soromox.systems.dynamical_system.DynamicalSystem"

Planar Piecewise Constant Strain (PCS) model for 2D soft continuum robots.

This class implements the geometric and dynamic modeling of a 2D soft robot using the Cosserat rod theory and piecewise constant strain assumption. It supports computation of forward kinematics, Jacobians, dynamical matrices.

Attributes:

Name	Type	Description
`num_segments`	`int`	Number of segments (constant strain sections) along the robot.
`num_actuators`	`int`	Number of actuators (control inputs) for the robot.
`base_pose`	`Array`	Initial planar pose `[theta, x, y]` with `theta` in radians.
`g`	`Array`	Gravitational acceleration vector (embedded in a 3D vector). [0, g_x, g_y]
`L,`	`(r, E, G, rho)`	Physical properties of each segment. `r` is the radius of the assumed solid circular cross-section.
`num_active_strains`	`Array`	Number of active strain components (based on strain_selector).
`num_strains`	`int`	Total number of strain components (6 * num_segments).
`B_xi`	`Array`	Basis matrix for projecting active strains (3 * num_segments, num_active_strains).
`scale_rotational_basis_by_length`	`bool`	If True, rotational strain-basis rows are divided by their segment length.
`xi_ref`	`Array`	Reference strain (reference configuration) of the robot.
`num_gauss_points`	`int`	Requested nonzero Gauss-Legendre quadrature nodes.
`num_integration_points`	`int`	Stored integration nodes, including zero-weight endpoints.
`integration_points,`	`integration_weights`	Quadrature nodes and weights.

Notes:¶

The material-frame local x-axis is the rod's longitudinal axis (the undeformed backbone tangent). This convention is independent of the base pose, which may orient the local x-axis arbitrarily in the inertial frame.
The strain vector is composed of 3 components per segment: [kappa_z, sigma_x, sigma_y]. The default straight, unstretched reference strain is [0, 1, 0]. Thus, kappa_z is the out-of-plane bending strain, sigma_x is axial stretch along local x, and sigma_y is transverse shear.
Every segment is assumed to have a solid circular cross-section. Its radius determines the area and second moment used by the mass, material damping, and stiffness matrices.
material_damping_coefficient is a viscosity-like modulus in Pa*s (N*s/m^2). The assembled damping matrix also contains section geometry and segment-length factors, so its entries do not share one blanket unit.

References

Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete Cosserat Approach for Multisection Soft Manipulator Dynamics. IEEE Transactions on Robotics, 34(6), 1518-1533.

Initialize the PlanarPCS class from typed dynamic parameters.

is_planar `property` ¶

is_planar: bool

Planar PCS is a 2D model.

segment_length `property` ¶

segment_length: Array

Per-segment backbone lengths.

tangent_eps `property` ¶

tangent_eps: Array

Epsilon value for Lie algebra tangent computations.

Returns:

Name	Type	Description
`Array`	`Array`	Epsilon value for Lie algebra tangent computations.

actuator_input_metadata `property` ¶

actuator_input_metadata: tuple[ActuatorMetadata, ...]

Metadata groups in the same order used to concatenate controls.

length `property` ¶

length: Array

Total backbone length of the robot (scalar).

supports_articulated_tendon_routing `property` ¶

supports_articulated_tendon_routing: bool

Whether joint indices describe a serial articulated routing topology.

base_transform `property` ¶

base_transform: Array

Return the homogeneous transform represented by base_pose.

Planar robots consume [theta, x, y] and return an SE(2) matrix with shape (3, 3). Spatial robots consume [qw, qx, qy, qz, x, y, z] and return an SE(3) matrix with shape (4, 4). Spatial quaternions are scalar-first Hamilton quaternions.

cross_section_geometry ¶

cross_section_geometry(q: Array, s: Array) -> tuple[Array, Array]

Return the assumed solid circular cross-section and segment radius.

with_params ¶

with_params(params: PlanarPCSParams) -> PlanarPCS

Return an updated copy with a full typed parameter object.

update_params ¶

update_params(**updates: Array) -> PlanarPCS

Return an updated copy with selected typed parameter fields replaced.

precompute ¶

precompute() -> None

Refresh state-independent matrices cached by the model.

classify_segment ¶

classify_segment(s: Array) -> tuple[Array, Array]

Classify the point along the robot to the corresponding segment.

Parameters:

Name	Type	Description	Default
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`segment_idx`	`Array`	index of the segment where the point is located
`s_segment`	`Array`	point coordinate along the segment in the interval [0, l_segment]

strain ¶

strain(q: Array) -> Array

Compute the strain vector from the generalized coordinates.

Components use the rod material frame, whose local x-axis is the longitudinal backbone direction.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`xi`	`Array`	strain vector of shape (num_active_strains,)

chi ¶

chi(xi: Array, s: Array) -> Array

Compute the forward kinematics of the robot.

Linear strains are expressed in the material frame: axial stretch is along local x and transverse shear is along local y.

Parameters:

Name	Type	Description	Default
`xi`	`Array`	strain vector of shape (3*num_segments,) where each row corresponds to a segment	required
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`chi_s`	`Array`	forward kinematics of the robot at point s, shape (3,) : [theta, x, y]

forward_kinematics_tips ¶

forward_kinematics_tips(q: Array) -> Array

Compute the forward kinematics of the robot at the tips of all segments.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`chi_tips`	`Array`	forward kinematics at each segment tip, shape (num_segments, 3) where each row is [theta, x, y].

forward_kinematics_batched ¶

forward_kinematics_batched(q: Array, s_ps: Array) -> Array

Compute the forward kinematics of the robot at a batch of arc-length positions.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`s_ps`	`Array`	arc-length positions in [0, L] of shape (N,).	required

Returns:

Name	Type	Description
`chi_ps`	`Array`	forward kinematics evaluated at all points, shape (N, 3) where each row is [theta, x, y].

inverse_kinematics ¶

inverse_kinematics(chi_tips: Array) -> Array

Execute inverse kinematics to find the generalized coordinates / configurations. Instead of an iterative IK procedure, we leverage here the closed-form solution for the mapping the relative tip poses of each segment distal end with respect to the proximal end of the segment to the planar constant strain parameters.

Parameters:

Name	Type	Description	Default
`chi_tips`	`Array`	the tip poses of shape (num_segments, 3) where each row is [theta, x, y] for the corresponding segment tip.	required

Returns:

Name	Type	Description
`q`	`Array`	the generalized coordinates of shape (num_active_strains,)

jacobian_bodyframe ¶

jacobian_bodyframe(q: Array, s: Array) -> Array

Compute the Jacobian of the forward kinematics at a point s along the robot in the body frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`J_local`	`Array`	Jacobian of the forward kinematics at point s in the body frame, shape (3, num_active_strains)

jacobian_and_arc_length_derivative_bodyframe ¶

jacobian_and_arc_length_derivative_bodyframe(q: Array, s: Array) -> tuple[Array, Array]

Compute the body-frame Jacobian and its arc-length derivative at s.

jacobian_arc_length_derivative_bodyframe ¶

jacobian_arc_length_derivative_bodyframe(q: Array, s: Array) -> Array

Compute the arc-length derivative of the body-frame Jacobian at s.

jacobian_bodyframe_batched ¶

jacobian_bodyframe_batched(q: Array, s_ps: Array) -> Array

Compute the Jacobian of the forward kinematics at a batch of points s_ps along the robot in the body frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`s_ps`	`Array`	point coordinates along the robot in the interval [0, L] of shape (N,).	required

Returns:

Name	Type	Description
`J_local_ps`	`Array`	Jacobians evaluated at all points, shape (N, 3, num_active_strains)

jacobian_inertialframe ¶

jacobian_inertialframe(q: Array, s: Array) -> Array

Compute the Jacobian of the forward kinematics at a point s along the robot in the inertial frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`J_global`	`Array`	Jacobian of the forward kinematics at point s in the inertial frame, shape (3, num_active_strains)

jacobian_and_arc_length_derivative_inertialframe ¶

jacobian_and_arc_length_derivative_inertialframe(q: Array, s: Array) -> tuple[Array, Array]

Compute the inertial-frame Jacobian and its arc-length derivative at s.

jacobian_arc_length_derivative_inertialframe ¶

jacobian_arc_length_derivative_inertialframe(q: Array, s: Array) -> Array

Compute the arc-length derivative of the inertial-frame Jacobian at s.

jacobian_inertialframe_batched ¶

jacobian_inertialframe_batched(q: Array, s_ps: Array) -> Array

Compute the Jacobian of the forward kinematics at a batch of points s_ps along the robot in the inertial frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`s_ps`	`Array`	point coordinates along the robot in the interval [0, L] of shape (N,).	required

Returns:

Name	Type	Description
`J_global_ps`	`Array`	Jacobians evaluated at all points, shape (N, 3, num_active_strains)

jacobian_tips ¶

jacobian_tips(q: Array) -> Array

Compute inertial-frame Jacobians at all segment tips.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`J_tips`	`Array`	inertial-frame Jacobians at each segment tip, shape (num_segments, 3, num_active_strains).

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe(q: Array, qd: Array, s: Array) -> tuple[Array, Array]

Compute the Jacobian and its time-derivative for the forward kinematics at a point s along the robot in the body frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_active_strains,).	required
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`J_local`	`Array`	Jacobian of the forward kinematics at point s in the body frame, shape (3, num_active_strains)
`Jd_local`	`Array`	Time-derivative of the Jacobian at point s in the body frame, shape (3, num_active_strains)

jacobian_and_time_derivative_bodyframe_batched ¶

jacobian_and_time_derivative_bodyframe_batched(q: Array, qd: Array, s_ps: Array) -> tuple[Array, Array]

Compute the Jacobian and its time-derivative for the forward kinematics at a batch of points s_ps along the robot in the body frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_active_strains,).	required
`s_ps`	`Array`	point coordinates along the robot in the interval [0, L] of shape (N,).	required

Returns:

Name	Type	Description
`J_local_ps`	`Array`	Jacobians evaluated at all points, shape (N, 3, num_active_strains)
`Jd_local_ps`	`Array`	Time-derivative of the Jacobians, shape (N, 3, num_active_strains)

jacobian_and_time_derivative_inertialframe ¶

jacobian_and_time_derivative_inertialframe(q: Array, qd: Array, s: Array) -> tuple[Array, Array]

Compute the Jacobian and its time-derivative for the forward kinematics at a point s along the robot in the inertial frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_active_strains,).	required
`s`	`Array`	point coordinate along the robot in the interval [0, L].	required

Returns:

Name	Type	Description
`J_global`	`Array`	Jacobian of the forward kinematics at point s in the inertial frame, shape (3, num_active_strains)
`Jd_global`	`Array`	Time-derivative of the Jacobian at point s in the inertial frame, shape (3, num_active_strains)

jacobian_and_time_derivative_inertialframe_batched ¶

jacobian_and_time_derivative_inertialframe_batched(q: Array, qd: Array, s_ps: Array) -> tuple[Array, Array]

Compute the Jacobian and its time-derivative for the forward kinematics at a batch of points s_ps along the robot in the inertial frame.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_active_strains,).	required
`s_ps`	`Array`	point coordinates along the robot in the interval [0, L] of shape (N,).	required

Returns:

Name	Type	Description
`J_global_ps`	`Array`	Jacobians evaluated at all points, shape (N, 3, num_active_strains)
`Jd_global_ps`	`Array`	Time-derivative of the Jacobians, shape (N, 3, num_active_strains)

jacobian_batched ¶

jacobian_batched(q: Array, s_ps: Array) -> Array

Compute inertial-frame Jacobians at multiple arc-length positions.

jacobian_and_time_derivative_batched ¶

jacobian_and_time_derivative_batched(q: Array, qd: Array, s_ps: Array) -> tuple[Array, Array]

Compute inertial-frame Jacobians and time derivatives at multiple arc-length positions.

inertia_matrix ¶

inertia_matrix(q: Array) -> Array

Compute the inertia matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`B`	`Array`	Inertia matrix of shape (num_active_strains, num_active_strains).

coriolis_matrix ¶

coriolis_matrix(q: Array, qd: Array) -> Array

Compute the Coriolis matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`C`	`Array`	Coriolis matrix of shape (num_active_strains, num_active_strains).

stiffness_matrix ¶

stiffness_matrix() -> Array

Compute the stiffness matrix of the robot.

Returns:

Name	Type	Description
`K`	`Array`	Stiffness matrix of shape (num_active_strains, num_active_strains).

elastic_force ¶

elastic_force(q: Array) -> Array

Compute the elastic forces of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`tau_el`	`Array`	Elastic force of shape (num_active_strains,).

damping_matrix ¶

damping_matrix(q: Array) -> Array

Compute the damping matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_active_strains,).	required

Returns:

Name	Type	Description
`D`	`Array`	Damping matrix of shape (num_active_strains, num_active_strains).

integration_kinematics ¶

integration_kinematics(q: Array, qd: Array) -> tuple[Array, Array, Array]

Return integration-point kinematics in active generalized coordinates.

The stored quadrature grid includes zero-weight endpoint nodes; this method ignores those endpoints and evaluates only the nonzero-weight interior quadrature nodes. The coordinates are generalized coordinates for active strain components only.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates, shape `(self.num_dofs,)`.	required
`qd`	`Array`	Active generalized velocities, shape `(self.num_dofs,)`.	required

Returns:

Type	Description
`Array`	Tuple `(g_ps, J_ps, Jd_ps)`. `g_ps` contains SE(2) poses with
`Array`	shape `(self.num_segments, self.num_gauss_points, 3, 3)`.
`Array`	`J_ps` contains body-frame Jacobians in active generalized
`tuple[Array, Array, Array]`	coordinates with shape
`tuple[Array, Array, Array]`	`(self.num_segments, self.num_gauss_points, 3, self.num_dofs)`.
`tuple[Array, Array, Array]`	`Jd_ps` contains their time derivatives with the same shape as
`tuple[Array, Array, Array]`	`J_ps`.

dynamics_terms ¶

dynamics_terms(q: Array, qd: Array) -> tuple[Array, Array, Array]

Assemble forward-dynamics terms in active generalized coordinates.

The coordinates and returned generalized forces correspond only to the active strain components selected by the strain basis.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates, shape `(self.num_dofs,)`.	required
`qd`	`Array`	Active generalized velocities, shape `(self.num_dofs,)`.	required

Returns:

Type	Description
`Array`	Tuple `(B, Cqd, G)`. `B` is the active-coordinate inertia
`Array`	matrix with shape `(self.num_dofs, self.num_dofs)`. `Cqd` is
`Array`	the active Coriolis/centrifugal force vector with shape
`tuple[Array, Array, Array]`	`(self.num_dofs,)`. `G` is the active generalized gravity
`tuple[Array, Array, Array]`	vector with shape `(self.num_dofs,)`.

forward_dynamics ¶

forward_dynamics(t: Array, y: Array, actuation_args: tuple | None = None) -> Array

Forward dynamics function.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time.	required
`y`	`Array`	State vector containing configuration and velocity. Shape is (2 * num_strains,).	required
`actuation_args`	`Tuple`	Additional arguments for the actuation mapping function. Default is None.	`None`

Returns:

Name	Type	Description
`yd`	`Array`	Time derivative of the state vector.

rollout_to ¶

rollout_to(initial_state: SystemState, u: Array | None = None, tau_ext: Array | None = None, environment_model: Callable[[SystemState], tuple[Array | None, Any | None]] | None = None, t1: float | Array = 10.0, solver_dt: float | Array = 0.0001, save_dt: float | Array | None = 0.01, save_ts: Array | None = None, solver: AbstractSolver | None = None, stepsize_controller: AbstractStepSizeController | None = ConstantStepSize(), max_steps: int | None = None) -> SystemState

Roll out the system dynamics in open loop using Diffrax.

Parameters:

Name	Type	Description	Default
`initial_state`	`SystemState`	Dataclass holding the initial time, system state vector (y), optional actuation (u), and optional control state.	required
`u`	`Array \| None`	Constant actuation to apply throughout the rollout. If not provided, falls back to `initial_state.u`, then zeros.	`None`
`tau_ext`	`Array \| None`	External forces/torques applied to the system (broadcast as constant).	`None`
`environment_model`	`Callable[[SystemState], tuple[Array \| None, Any \| None]] \| None`	Optional callable that accepts a `SystemState` and returns `(tau_environment, environment_state_dot)`. The returned generalized torques are added to `tau_ext` during integration.	`None`
`t1`	`float \| Array`	Final time of the simulation, included in the saved trajectory.	`10.0`
`solver_dt`	`float \| Array`	Time step for the solver.	`0.0001`
`save_dt`	`float \| Array \| None`	Time interval at which to save the solution when `save_ts` is not provided.	`0.01`
`save_ts`	`Array \| None`	Explicit time points to be saved in the output. Must be within [initial_state.t, t1]. Falls back to `save_dt` if None.	`None`
`solver`	`AbstractSolver \| None`	Solver to use for the ODE integration.	`None`
`stepsize_controller`	`AbstractStepSizeController \| None`	Stepsize controller for the solver.	`ConstantStepSize()`
`max_steps`	`int \| None`	Maximum number of steps for the solver.	`None`

Returns:

Type	Description
`SystemState`	SystemState PyTree containing time samples, system state trajectory,
`SystemState`	actuation at each saved step, (optionally) the control state
`SystemState`	trajectory, and (optionally) the environment state trajectory if
`SystemState`	`initial_state.environment_state` was provided. Each leaf has a
`SystemState`	leading time dimension aligned with `save_ts`.

rollout_closed_loop_to ¶

rollout_closed_loop_to(initial_state: SystemState, controller: Callable[[SystemState], tuple[Array, Any | None]], tau_ext: Array | None = None, environment_model: Callable[[SystemState], tuple[Array | None, Any | None]] | None = None, t1: float | Array = 10.0, solver_dt: float | Array = 0.0001, save_dt: float | Array = 0.01, save_ts: Array | None = None, solver: AbstractSolver | None = None, stepsize_controller: AbstractStepSizeController | None = ConstantStepSize(), max_steps: int | None = None) -> SystemState

Roll out the system dynamics in closed loop using Diffrax.

The provided controller is queried at every integration step with the current system state (and optional control_state). Its actuation output is added to any feed-forward actuation contained in initial_state.u.

Parameters:

Name	Type	Description	Default
`initial_state`	`SystemState`	Dataclass holding the initial time, system state vector (y), optional actuation (u), and optional control state.	required
`controller`	`Callable[[SystemState], tuple[Array, Any \| None]]`	Callable that accepts a `SystemState` and returns a tuple `(u_control, control_state_dot)`. `u_control` is added to the base actuation from the initial state.	required
`tau_ext`	`Array \| None`	External forces/torques applied to the system (broadcast as constant).	`None`
`environment_model`	`Callable[[SystemState], tuple[Array \| None, Any \| None]] \| None`	Optional callable that accepts a `SystemState` and returns `(tau_environment, environment_state_dot)`. The returned generalized torques are added to `tau_ext` during integration.	`None`
`t1`	`float \| Array`	Final time of the simulation, included in the saved trajectory.	`10.0`
`solver_dt`	`float \| Array`	Time step for the solver.	`0.0001`
`save_dt`	`float \| Array`	Time interval at which to save the solution when `save_ts` is not provided.	`0.01`
`save_ts`	`Array \| None`	Explicit time points to be saved in the output. Must be within [initial_state.t, t1]. Falls back to `save_dt` if None.	`None`
`solver`	`AbstractSolver \| None`	Solver to use for the ODE integration.	`None`
`stepsize_controller`	`AbstractStepSizeController \| None`	Stepsize controller for the solver.	`ConstantStepSize()`
`max_steps`	`int \| None`	Maximum number of steps for the solver.	`None`

Returns:

Type	Description
`SystemState`	SystemState PyTree containing time samples, system state trajectory,
`SystemState`	actuation at each saved step, controller state trajectory, and
`SystemState`	(optionally) the environment state trajectory if
`SystemState`	`initial_state.environment_state` was provided. Each leaf has a
`SystemState`	leading time dimension aligned with `save_ts`.

rollout_discrete_closed_loop_to ¶

rollout_discrete_closed_loop_to(initial_state: SystemState, controller: Callable[[SystemState], tuple[Array, Any | None]], tau_ext: Array | None = None, environment_model: Callable[[SystemState], tuple[Array | None, Any | None]] | None = None, duration: float = 10.0, solver_dt: float | Array = 0.0001, control_dt: float = 0.01, save_dt: float = 0.01, solver: AbstractSolver | None = None, stepsize_controller: AbstractStepSizeController | None = ConstantStepSize(), max_steps: int | None = None) -> SystemState

Roll out the system in discrete-time closed loop.

The controller is evaluated every control_dt seconds. Between control evaluations the actuation is held constant and the system is integrated with Diffrax (equivalent to repeatedly calling rollout_to over each control interval).

The controller signature mirrors rollout_closed_loop_to. If it returns a control_state_dot and initial_state.control_state is provided, the control state is advanced with a forward-Euler step over the control period; otherwise the control state is held constant between controller calls.

The rollout uses a regular time grid. For static tracing/compilation the following constraints are enforced: - duration is an integer multiple of control_dt. - control_dt is an integer multiple of save_dt.

Parameters:

Name	Type	Description	Default
`initial_state`	`SystemState`	initial time/state (and optional feedforward actuation/control state).	required
`controller`	`Callable[[SystemState], tuple[Array, Any \| None]]`	callable returning `(u_control, control_state_dot)`.	required
`tau_ext`	`Array \| None`	constant external wrench/force applied during the rollout.	`None`
`environment_model`	`Callable[[SystemState], tuple[Array \| None, Any \| None]] \| None`	Optional callable returning `(tau_environment, environment_state_dot)`. The returned generalized torques are added to `tau_ext` during integration.	`None`
`duration`	`float`	simulation duration in seconds.	`10.0`
`solver_dt`	`float \| Array`	initial step size for the solver.	`0.0001`
`control_dt`	`float`	sampling period for the controller. Must be positive.	`0.01`
`save_dt`	`float`	save interval. Must be positive and evenly divide `control_dt`.	`0.01`
`solver`	`AbstractSolver \| None`	Diffrax solver.	`None`
`stepsize_controller`	`AbstractStepSizeController \| None`	Diffrax stepsize controller.	`ConstantStepSize()`
`max_steps`	`int \| None`	maximum solver steps.	`None`

Returns:

Type	Description
`SystemState`	SystemState PyTree containing time samples, system state trajectory,
`SystemState`	actuation at each saved step, controller state trajectory, and
`SystemState`	(optionally) the environment state trajectory if
`SystemState`	`initial_state.environment_state` was provided. Each leaf has a
`SystemState`	leading time dimension aligned with the regular save grid.

with_actuator_params ¶

with_actuator_params(index: int, params) -> SoftRobot

Return a robot with one actuator's complete parameter object replaced.

update_actuator_params ¶

update_actuator_params(index: int, **updates) -> SoftRobot

Return a robot with selected fields of one actuator's params replaced.

with_passive_element_params ¶

with_passive_element_params(index: int, params) -> SoftRobot

Return a robot with one passive element's complete params replaced.

update_passive_element_params ¶

update_passive_element_params(index: int, **updates) -> SoftRobot

Return a robot with selected passive-element parameter fields replaced.

forward_kinematics ¶

forward_kinematics(q: Array, s: Array) -> Array

Compute the forward kinematics at a point s along the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`s`	`Array`	Position parameter along the robot structure. The meaning depends on the specific robot type: - For continuum robots (PCS, PlanarPCS): arc-length in [0, L_total] - For articulated robots (Pendulum): can be link index or fraction	required

Returns:

Name	Type	Description
`chi`	`Array`	Pose at point s. The shape and meaning depend on the robot type: - For 3D robots (PCS): SE(3) transformation matrix, shape (4, 4) - For planar robots (PlanarPCS, Pendulum): [theta, x, y], shape (3,)

forward_kinematics_arc_length_derivative ¶

forward_kinematics_arc_length_derivative(q: Array, s: Array) -> Array

Compute the arc-length derivative of the forward kinematics at s.

The returned tangent has the same shape and representation as forward_kinematics(q, s).

forward_kinematics_and_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative(q: Array, s: Array) -> tuple[Array, Array]

Compute forward kinematics and its arc-length derivative at s.

Subclasses can override the protected hook to share intermediate kinematic quantities between the primal pose and d pose / ds.

jacobian ¶

jacobian(q: Array, s: Array) -> Array

Compute the Jacobian of the forward kinematics at a point s along the robot.

The Jacobian maps configuration space velocities to operational space (Cartesian/task space) velocities at point s.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`s`	`Array`	Position parameter along the robot structure.	required

Returns:

Name	Type	Description
`J`	`Array`	Jacobian matrix of shape (n_pose_dim, num_dofs), where n_pose_dim depends on the robot type: - For 3D robots (PCS): 6 (angular velocity + linear velocity) - For planar robots (PlanarPCS, Pendulum): 3 (omega_z, v_x, v_y)

jacobian_arc_length_derivative ¶

jacobian_arc_length_derivative(q: Array, s: Array) -> Array

Compute the arc-length derivative of the Jacobian at s.

The returned derivative has the same shape and frame convention as jacobian(q, s).

jacobian_and_arc_length_derivative ¶

jacobian_and_arc_length_derivative(q: Array, s: Array) -> tuple[Array, Array]

Compute the Jacobian and its arc-length derivative at s.

Returns:

Name	Type	Description
`J`	`Array`	Jacobian matrix of shape (n_pose_dim, num_dofs).
`Js`	`Array`	Arc-length derivative of the Jacobian with the same shape as `J`.

jacobian_and_time_derivative ¶

jacobian_and_time_derivative(q: Array, qd: Array, s: Array) -> tuple[Array, Array]

Compute the Jacobian and its time derivative at a point s along the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`qd`	`Array`	Generalized velocities of shape (num_dofs,).	required
`s`	`Array`	Position parameter along the robot structure.	required

Returns:

Name	Type	Description
`J`	`Array`	Jacobian matrix of shape (n_pose_dim, num_dofs).
`Jd`	`Array`	Time derivative of the Jacobian, shape (n_pose_dim, num_dofs).

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required

Returns:

Name	Type	Description
`G`	`Array`	Gravitational force of shape (num_dofs,).

potential_force ¶

potential_force(q: Array) -> Array

Compute the total conservative generalized force.

This is the sum of gravitational and elastic forces.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required

Returns:

Name	Type	Description
`tau_pot`	`Array`	Potential force of shape (num_dofs,).

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return all work-conjugate actuator coordinates in control order.

actuator_velocities ¶

actuator_velocities(q: Array, qd: Array) -> Array

Return all actuator-coordinate velocities in control order.

actuation_matrix ¶

actuation_matrix(q: Array) -> Array

Return the concatenated transmission moment matrix.

actuator_efforts ¶

actuator_efforts(q: Array, u: Array, qd: Array | None = None) -> Array

Map ordered user controls to ordered work-conjugate efforts.

actuation_force ¶

actuation_force(q: Array, u: Array, qd: Array | None = None) -> Array

Return generalized actuation force A(q) @ effort.

passive_elastic_force ¶

passive_elastic_force(q: Array) -> Array

Return the sum of installed passive conservative forces.

passive_damping_matrix ¶

passive_damping_matrix(q: Array) -> Array

Return the sum of installed passive damping matrices.

passive_elastic_energy ¶

passive_elastic_energy(q: Array) -> Array

Return the sum of installed passive elastic energies.

actuator_visual_layers ¶

actuator_visual_layers(q: Array, s_points: Array, *, actuator_inputs: Array | None = None)

Return semantic active and passive actuator geometry for renderers.

kinetic_energy ¶

kinetic_energy(q: Array, qd: Array) -> Array

Compute the kinetic energy of the system.

Default implementation: T = 0.5 * qd^T * M(q) * qd

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`qd`	`Array`	Generalized velocities of shape (num_dofs,).	required

Returns:

Name	Type	Description
`T`	`Array`	Kinetic energy (scalar).

gravitational_energy ¶

gravitational_energy(q: Array) -> Array

Compute the gravitational potential energy of the system.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required

Returns:

Name	Type	Description
`U_g`	`Array`	Gravitational potential energy (scalar).

elastic_energy ¶

elastic_energy(q: Array) -> Array

Compute the elastic potential energy stored in the system.

Default implementation: U_el = 0.5 * q^T * K * q

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required

Returns:

Name	Type	Description
`U_el`	`Array`	Elastic potential energy (scalar).

potential_energy ¶

potential_energy(q: Array) -> Array

Compute the total potential energy of the system.

This is the sum of gravitational and elastic energy.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required

Returns:

Name	Type	Description
`U`	`Array`	Total potential energy (scalar).

total_energy ¶

total_energy(q: Array, qd: Array) -> Array

Compute the total energy of the system.

This is the sum of kinetic and potential energy.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`qd`	`Array`	Generalized velocities of shape (num_dofs,).	required

Returns:

Name	Type	Description
`E`	`Array`	Total energy (scalar).

References¶

The PCS (Piecewise Constant Strain) model was originally proposed in:

Renda, F., Boyer, F., Dias, J., & Seneviratne, L. (2018). Discrete cosserat approach for multisection soft manipulator dynamics. IEEE Transactions on Robotics, 34(6), 1518-1533.

Planar PCS¶

Overview¶

Main Implementation¶

soromox.systems.pcs.planar_pcs ¶

PlanarPCS ¶

Notes:¶

is_planar property ¶

segment_length property ¶

tangent_eps property ¶

actuator_input_metadata property ¶

length property ¶

supports_articulated_tendon_routing property ¶

base_transform property ¶

cross_section_geometry ¶

with_params ¶

update_params ¶

precompute ¶

classify_segment ¶

strain ¶

chi ¶

forward_kinematics_tips ¶

forward_kinematics_batched ¶

inverse_kinematics ¶

jacobian_bodyframe ¶

jacobian_and_arc_length_derivative_bodyframe ¶

jacobian_arc_length_derivative_bodyframe ¶

jacobian_bodyframe_batched ¶

jacobian_inertialframe ¶

jacobian_and_arc_length_derivative_inertialframe ¶

jacobian_arc_length_derivative_inertialframe ¶

jacobian_inertialframe_batched ¶

jacobian_tips ¶

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe_batched ¶

jacobian_and_time_derivative_inertialframe ¶

jacobian_and_time_derivative_inertialframe_batched ¶

jacobian_batched ¶

jacobian_and_time_derivative_batched ¶

inertia_matrix ¶

coriolis_matrix ¶

stiffness_matrix ¶

elastic_force ¶

damping_matrix ¶

integration_kinematics ¶

dynamics_terms ¶

forward_dynamics ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

with_actuator_params ¶

update_actuator_params ¶

with_passive_element_params ¶

update_passive_element_params ¶

forward_kinematics ¶

forward_kinematics_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative ¶

jacobian ¶

jacobian_arc_length_derivative ¶

jacobian_and_arc_length_derivative ¶

jacobian_and_time_derivative ¶

gravitational_force ¶

potential_force ¶

actuator_coordinates ¶

actuator_velocities ¶

actuation_matrix ¶

actuator_efforts ¶

actuation_force ¶

passive_elastic_force ¶

passive_damping_matrix ¶

passive_elastic_energy ¶

actuator_visual_layers ¶

kinetic_energy ¶

gravitational_energy ¶

elastic_energy ¶

potential_energy ¶

total_energy ¶

References¶

is_planar `property` ¶

segment_length `property` ¶

tangent_eps `property` ¶

actuator_input_metadata `property` ¶

length `property` ¶

supports_articulated_tendon_routing `property` ¶

base_transform `property` ¶