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 = (), backend: ExecutionBackend = 'auto', backend_params: PCSBackendParams | None = None, base_pose: Array | None = None, floating_base: bool = False, **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`	`int`	Initial planar pose `[theta, x, y]` with `theta` in radians.
`g`	`Array \| None`	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 \| None`	Number of active strain components (based on strain_selector).
`num_strains`	`int`	Total number of strain components (6 * num_segments).
`B_xi`	`Array \| None`	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 \| None`	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.
`backend_params`	`PCSBackendParams`	Optional tuning parameters for the PCS execution backend. The default uses 128 threads per planar Warp block.

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 a planar PCS model from typed parameters.

Parameters:

Name	Type	Description	Default
`params`	`PlanarPCSParams`	Canonical dynamic link, gravity, and base-pose parameters.	required
`structure`	`PlanarPCSStructure \| None`	Optional static quadrature, active-strain, and rotational-scaling configuration.	`None`
`actuators`	`Actuator \| tuple[Actuator, ...] \| None`	Optional actuator or tuple of actuators attached to the model.	`None`
`passive_elements`	`PassiveElement \| tuple[PassiveElement, ...] \| None`	Optional passive element or tuple of passive elements. Pass `None` or an empty tuple to disable them.	`()`
`backend`	`ExecutionBackend`	Preferred execution backend for accelerated methods.	`'auto'`
`backend_params`	`PCSBackendParams \| None`	Optional tuning parameters for accelerated PCS execution. Defaults to a 128-thread persistent Warp block.	`None`
`**kwargs`	`Any`	Additional keyword arguments forwarded to :class:`BaseContinuumSoftRobot`.	`{}`

Raises:

Type	Description
`TypeError`	If `params`, a structure field, or an attached component has an invalid type.
`ValueError`	If parameter shapes or values, the structure, or an attached component are invalid.

is_planar `property` ¶

is_planar: bool

Return whether the system is planar.

Returns:

Type	Description
`bool`	Always `True`.

segment_length `property` ¶

segment_length: Array

Return the per-segment backbone lengths.

Returns:

Type	Description
`Array`	Array with shape `(num_segments,)`.

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.

num_base_coordinates `property` ¶

num_base_coordinates: int

Return the configuration-storage dimension of the base.

Returns:

Type	Description
`int`	Zero for fixed robots, three for planar floating robots, and seven
`int`	for spatial floating robots.

num_base_velocities `property` ¶

num_base_velocities: int

Return the generalized-velocity dimension of the base.

Returns:

Type	Description
`int`	Zero for fixed robots, three for planar floating robots, and six
`int`	for spatial floating robots.

num_coordinates `property` ¶

num_coordinates: int

Return the total configuration dimension.

Returns:

Type	Description
`int`	`nq`, including runtime base coordinates when enabled.

num_velocities `property` ¶

num_velocities: int

Return the total generalized-velocity dimension.

Returns:

Type	Description
`int`	`nv`, including runtime base velocities when enabled.

num_auxiliary_states `property` ¶

num_auxiliary_states: int

Return the number of trailing first-order auxiliary states.

Returns:

Type	Description
`int`	The hysteresis-state dimension, or zero for systems without
`int`	auxiliary dynamics.

state_size `property` ¶

state_size: int

Return the flattened first-order state dimension.

Returns:

Type	Description
`int`	`num_coordinates + num_velocities + num_auxiliary_states`.

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 of the fixed/internal base pose.

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

params_from_links `staticmethod` ¶

params_from_links(links: list[LinkSpec] | tuple[LinkSpec, ...], *, gravity: Array | None = None) -> PlanarPCSParams

Build planar PCS parameters from shared link specifications.

Parameters:

Name	Type	Description	Default
`links`	`list[LinkSpec] \| tuple[LinkSpec, ...]`	Non-empty sequence of constant, circular link specifications. Each reference strain must have shape `(3,)`.	required
`gravity`	`Array \| None`	Optional planar gravity vector with shape `(2,)`.	`None`

Returns:

Name	Type	Description
`Validated`	`PlanarPCSParams`	class:`PlanarPCSParams` with canonical per-link
	`PlanarPCSParams`	stiffness and damping arrays of shape `(num_links, 3, 3)`.

Raises:

Type	Description
`ValueError`	If no links are supplied; a link is not constant and circular; a reference strain has the wrong shape; a material source is incomplete; or an explicit matrix is not `(3, 3)`.

from_links `classmethod` ¶

from_links(links: list[LinkSpec] | tuple[LinkSpec, ...], *, structure: PlanarPCSStructure | None = None, gravity: Array | None = None, base_pose: Array | None = None, **kwargs: Any) -> PlanarPCS

Construct a planar PCS model from shared link specifications.

Parameters:

Name	Type	Description	Default
`links`	`list[LinkSpec] \| tuple[LinkSpec, ...]`	Non-empty sequence of constant, circular link specifications.	required
`structure`	`PlanarPCSStructure \| None`	Optional static planar PCS quadrature, strain-selection, and rotational-scaling configuration. Defaults to :class:`PlanarPCSStructure`.	`None`
`gravity`	`Array \| None`	Optional planar gravity vector with shape `(2,)`.	`None`
`base_pose`	`Array \| None`	Optional planar base pose `[theta, x, y]` with shape `(3,)`.	`None`
`**kwargs`	`Any`	Additional keyword arguments forwarded to the PlanarPCS constructor, such as actuators or passive elements.	`{}`

Returns:

Type	Description
`PlanarPCS`	A fully initialized planar PCS model.

Raises:

Type	Description
`TypeError`	If a structure or constructor argument has an invalid type.
`ValueError`	If a link specification, static structure, parameter array, or attached component is invalid.

cross_section_geometry ¶

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

Evaluate the circular cross-section at a backbone coordinate.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates. PCS cross-section geometry is configuration-independent, but `q` is accepted for the common continuum-robot interface.	required
`s`	`Array`	Scalar global backbone coordinate.	required

Returns:

Type	Description
`Array`	A tuple containing the circular :class:`CrossSectionGeometry` tag
`Array`	and a one-element array holding the selected segment radius.

Raises:

Type	Description
`ValueError`	If `s` cannot be assigned to a segment.

with_params ¶

with_params(params: PlanarPCSParams) -> PlanarPCS

Return a model copy using a complete parameter PyTree.

Parameters:

Name	Type	Description	Default
`params`	`PlanarPCSParams`	Complete replacement parameters with the same number of segments and reference-strain layout as this model.	required

Returns:

Type	Description
`PlanarPCS`	A new PlanarPCS model with refreshed geometry, mass,
`PlanarPCS`	material-response, stiffness, and damping caches. The original
`PlanarPCS`	model is unchanged.

Raises:

Type	Description
`TypeError`	If `params` is not a :class:`PlanarPCSParams`.
`ValueError`	If the replacement is invalid or changes the static segment or strain layout.

update_params ¶

update_params(**updates: Any) -> PlanarPCS

Return a copy with selected top-level parameter fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Fields of :class:`PlanarPCSParams` to replace, typically `link` or `gravity`.	`{}`

Returns:

Type	Description
`PlanarPCS`	A new validated PlanarPCS model containing the replacements.

Raises:

Type	Description
`TypeError`	If an unknown field is supplied or a replacement has an invalid type.
`ValueError`	If the result is invalid or changes the static segment or strain layout.

update_link_params ¶

update_link_params(**updates: Any) -> PlanarPCS

Return a copy with selected continuum-link fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Fields of :class:`ContinuumLinkParams` to replace, such as `length`, `density`, `reference_strain`, `cross_section`, `stiffness`, or `damping`.	`{}`

Returns:

Type	Description
`PlanarPCS`	A new validated PlanarPCS model with refreshed dependent caches.

Raises:

Type	Description
`TypeError`	If an unknown link field is supplied.
`ValueError`	If a replacement is invalid or changes the static segment or strain layout.

link_matrices_from_material ¶

link_matrices_from_material(material: IsotropicMaterialParams) -> tuple[Array, Array]

Map isotropic material variables to canonical planar link matrices.

Parameters:

Name	Type	Description	Default
`material`	`IsotropicMaterialParams`	Scalar or per-segment Young's modulus, either shear modulus or Poisson's ratio, and optional material damping coefficient. Scalars are broadcast over all segments.	required

Returns:

Type	Description
`Array`	A tuple `(stiffness, damping)` whose arrays both have shape
`Array`	`(num_segments, 3, 3)`.

Raises:

Type	Description
`ValueError`	If a material field is not scalar or does not have shape `(num_segments,)`.

with_isotropic_material ¶

with_isotropic_material(material: IsotropicMaterialParams) -> Self

Return a copy whose link matrices are built from isotropic material.

The supplied material PyTree remains caller-owned and is not stored on the model.

Parameters:

Name	Type	Description	Default
`material`	`IsotropicMaterialParams`	Scalar or per-segment isotropic material variables.	required

Returns:

Type	Description
`Self`	A new PlanarPCS model containing the generated canonical link
`Self`	stiffness and damping matrices.

Raises:

Type	Description
`ValueError`	If a material field cannot be broadcast to one value per segment.

precompute ¶

precompute() -> None

Refresh state-independent matrices cached by the model.

Returns:

Type	Description
`None`	`None`. Material unit-response operators and the segment, full,
`None`	and active-coordinate matrices are replaced in place.

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`	Fixed-base generalized coordinates or total floating-base configuration.	required

Returns:

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

forward_kinematics ¶

forward_kinematics(q: Array, s: Array, *, backend: ExecutionBackend | None = None) -> Array

Compute a planar pose at one curvilinear abscissa.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s`	`Array`	Scalar curvilinear abscissa.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	Planar pose `[theta, x, y]` with shape `(3,)`.

forward_kinematics_abscissa_batched ¶

forward_kinematics_abscissa_batched(q: Array, s_ps: Array, *, backend: ExecutionBackend | None = None) -> Array

Compute planar poses at a batch of curvilinear abscissae.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s_ps`	`Array`	Curvilinear abscissae with shape `(N,)`.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	Planar poses with shape `(N, 3)`.

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

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 a body-frame Jacobian and its arc-length derivative.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`s`	`Array`	Scalar global backbone coordinate.	required

Returns:

Type	Description
`Array`	A tuple `(J, J_s)` containing the body-frame Jacobian and its
`Array`	derivative with respect to global arc length. Both arrays have
`tuple[Array, Array]`	shape `(3, num_active_strains)`.

jacobian_arc_length_derivative_bodyframe ¶

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

Compute the body-frame Jacobian derivative with respect to arc length.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`s`	`Array`	Scalar global backbone coordinate.	required

Returns:

Type	Description
`Array`	Arc-length derivative with shape
`Array`	`(3, num_active_strains)`.

jacobian_bodyframe_abscissa_batched ¶

jacobian_bodyframe_abscissa_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, *, backend: ExecutionBackend | None = None) -> Array

Compute an inertial Jacobian at one curvilinear abscissa.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s`	`Array`	Scalar curvilinear abscissa.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	Inertial Jacobian with shape `(3, D)`.

jacobian_inertialframe_abscissa_batched ¶

jacobian_inertialframe_abscissa_batched(q: Array, s_ps: Array, *, backend: ExecutionBackend | None = None) -> Array

Compute inertial Jacobians at a batch of curvilinear abscissae.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s_ps`	`Array`	Curvilinear abscissae with shape `(N,)`.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	Inertial-frame Jacobians with shape `(N, 3, D)`.

forward_kinematics_and_jacobian_inertialframe ¶

forward_kinematics_and_jacobian_inertialframe(q: Array, s: Array, *, backend: ExecutionBackend | None = None) -> tuple[Array, Array]

Compute a planar pose and inertial Jacobian in one traversal.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s`	`Array`	Scalar curvilinear abscissa.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	A pose with shape `(3,)` and an inertial Jacobian with shape
`Array`	`(3, D)`.

forward_kinematics_and_jacobian_inertialframe_abscissa_batched ¶

forward_kinematics_and_jacobian_inertialframe_abscissa_batched(q: Array, s_ps: Array, *, backend: ExecutionBackend | None = None) -> tuple[Array, Array]

Compute fused planar poses and Jacobians for an abscissa batch.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(D,)`.	required
`s_ps`	`Array`	Curvilinear abscissae with shape `(N,)`.	required
`backend`	`ExecutionBackend \| None`	Optional execution override. `None` uses the model's configured backend.	`None`

Returns:

Type	Description
`Array`	Poses with shape `(N, 3)` and inertial Jacobians with shape
`Array`	`(N, 3, D)`.

jacobian_and_arc_length_derivative_inertialframe ¶

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

Compute an inertial-frame Jacobian and its arc-length derivative.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`s`	`Array`	Scalar global backbone coordinate.	required

Returns:

Type	Description
`Array`	A tuple `(J, J_s)` containing the inertial-frame Jacobian and its
`Array`	derivative with respect to global arc length. Both arrays have
`tuple[Array, Array]`	shape `(3, num_active_strains)`.

jacobian_arc_length_derivative_inertialframe ¶

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

Compute the inertial Jacobian derivative with respect to arc length.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`s`	`Array`	Scalar global backbone coordinate.	required

Returns:

Type	Description
`Array`	Arc-length derivative with shape
`Array`	`(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_abscissa_batched ¶

jacobian_and_time_derivative_bodyframe_abscissa_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_abscissa_batched ¶

jacobian_and_time_derivative_inertialframe_abscissa_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_abscissa_batched ¶

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

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

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`s_ps`	`Array`	Backbone coordinates with shape `(num_points,)`.	required

Returns:

Type	Description
`Array`	Inertial-frame Jacobians with shape
`Array`	`(num_points, 3, num_active_strains)`.

jacobian_and_time_derivative_abscissa_batched ¶

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

Compute batched inertial Jacobians and their time derivatives.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized strains with shape `(num_active_strains,)`.	required
`qd`	`Array`	Active generalized strain rates with shape `(num_active_strains,)`.	required
`s_ps`	`Array`	Backbone coordinates with shape `(num_points,)`.	required

Returns:

Type	Description
`Array`	A tuple `(J, J_dot)` whose arrays both have shape
`Array`	`(num_points, 3, num_active_strains)`.

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

actuation_matrix ¶

actuation_matrix(q: Array, *, backend: ExecutionBackend | None = None) -> Array

Return the actuator matrix through the selected execution backend.

actuation_force ¶

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

Return generalized actuator force through the selected backend.

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_internal_dofs,)`.	required
`qd`	`Array`	Active generalized velocities, shape `(self.num_internal_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_internal_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, *, backend: ExecutionBackend | None = None) -> tuple[Array, Array, Array]

Assemble planar PCS dynamics terms for one or many environments.

backend=None uses the model's configured :attr:backend. Warp is selected for forward-only GPU execution with any positive quadrature count; CPU execution and all forward- or reverse-mode differentiation use the JAX implementation. Applying :func:jax.vmap to scalar calls invokes one batch-shaped Warp pipeline rather than mapping independent batch-one launches.

The Warp implementation uses FP64 SE(2) constant-strain operators and one persistent cooperative chain block per environment. Its generated source is independent of the batch size and segment count. Install the optional dependency with pip install soromox[warp] before explicitly requesting it.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates with shape `(num_dofs,)` or `(batch_size, num_dofs)`.	required
`qd`	`Array`	Active generalized velocities with the same shape as `q`.	required
`backend`	`ExecutionBackend \| None`	Optional per-call override: `"auto"`, `"jax"`, or `"warp"`. `None` uses :attr:`backend`.	`None`

Returns:

Type	Description
`Array`	Tuple `(B, Cqd, G)` with the same optional leading batch dimension
`Array`	as the inputs. `B` is the active inertia matrix, `Cqd` is the
`Array`	Coriolis/centrifugal force action, and `G` is generalized gravity.

Raises:

Type	Description
`ValueError`	If the backend or input shapes are invalid, or a Warp batch is empty.
`TypeError`	If Warp is selected for non-FP64 states.
`ImportError`	If Warp is selected but `warp-lang` is unavailable.

forward_dynamics ¶

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

Compute the time derivative of a planar PCS state.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current integration time. Planar PCS dynamics are autonomous, so the value is accepted for solver compatibility but is not otherwise used.	required
`y`	`Array`	State `[q, v, auxiliary]` with shape `(state_size,)`.	required
`actuation_args`	`tuple \| None`	Optional tuple containing the actuation input `u` and, optionally, an external generalized force `tau_ext`. A one-element tuple is interpreted as `(u,)` and a two-element tuple as `(u, tau_ext)`. Missing values default to zero.	`None`
`backend`	`ExecutionBackend \| None`	Optional execution-backend override for the inertia, Coriolis, and gravity terms. `None` uses :attr:`backend`.	`None`

Returns:

Type	Description
`Array`	State derivative `[qd, qdd]` with the same shape as `y`.

Raises:

Type	Description
`ValueError`	If `actuation_args` does not contain one or two elements.

project_state ¶

project_state(y: Array) -> Array

Project a state onto the robot's configuration manifold.

Fixed and planar systems return the original state without additional array operations. Spatial floating systems normalize the leading scalar-last quaternion while preserving velocity and auxiliary state.

Parameters:

Name	Type	Description	Default
`y`	`Array`	State with trailing dimension `state_size`.	required

Returns:

Type	Description
`Array`	State with a unit floating-base quaternion when applicable.

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 | Sequence[float] | 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 \| Sequence[float] \| 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 | None = 0.01, save_ts: Array | Sequence[float] | 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 \| None`	Time interval at which to save the solution when `save_ts` is not provided.	`0.01`
`save_ts`	`Array \| Sequence[float] \| 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.

pack_configuration ¶

pack_configuration(q_internal: Array, *, base_pose: Array | None = None) -> Array

Pack internal coordinates and a runtime base pose.

Parameters:

Name	Type	Description	Default
`q_internal`	`Array`	Internal coordinates with trailing dimension `num_internal_dofs`.	required
`base_pose`	`Array \| None`	Required runtime pose for floating robots. Fixed robots reject this argument.	`None`

Returns:

Type	Description
`Array`	Total configuration with trailing dimension `num_coordinates`.

Raises:

Type	Description
`ValueError`	If a required base pose is missing, a fixed robot is given a runtime pose, or a trailing dimension is invalid.

split_configuration ¶

split_configuration(q: Array) -> tuple[Array | None, Array]

Split total configuration into base and internal coordinates.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Configuration with trailing dimension `num_coordinates`.	required

Returns:

Type	Description
`tuple[Array \| None, Array]`	`(q_base, q_internal)`. `q_base` is `None` for fixed robots.

pack_velocity ¶

pack_velocity(qd_internal: Array, *, base_velocity: Array | None = None) -> Array

Pack internal and floating-base generalized velocities.

Parameters:

Name	Type	Description	Default
`qd_internal`	`Array`	Internal generalized velocity with trailing dimension `num_internal_dofs`.	required
`base_velocity`	`Array \| None`	Optional world-frame base velocity. Omission uses zero for floating robots; fixed robots reject this argument.	`None`

Returns:

Type	Description
`Array`	Total generalized velocity with trailing dimension
`Array`	`num_velocities`.

Raises:

Type	Description
`ValueError`	If a fixed robot is given a base velocity or a trailing dimension is invalid.

split_velocity ¶

split_velocity(v: Array) -> tuple[Array | None, Array]

Split total velocity into base and internal components.

Parameters:

Name	Type	Description	Default
`v`	`Array`	Generalized velocity with trailing dimension `num_velocities`.	required

Returns:

Type	Description
`tuple[Array \| None, Array]`	`(v_base, qd_internal)`. `v_base` is `None` for fixed robots.

pack_state ¶

pack_state(q: Array, v: Array, auxiliary_state: Array | None = None) -> Array

Pack configuration, velocity, and optional auxiliary state.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Configuration with trailing dimension `num_coordinates`.	required
`v`	`Array`	Velocity with trailing dimension `num_velocities`.	required
`auxiliary_state`	`Array \| None`	Optional state with trailing dimension `num_auxiliary_states`. Omission uses zeros.	`None`

Returns:

Type	Description
`Array`	State `[q, v, auxiliary]` with broadcast leading axes and trailing
`Array`	dimension `state_size`.

split_state ¶

split_state(y: Array) -> tuple[Array, Array, Array]

Split a state with unequal configuration and velocity dimensions.

Parameters:

Name	Type	Description	Default
`y`	`Array`	State with trailing dimension `state_size`.	required

Returns:

Type	Description
`tuple[Array, Array, Array]`	`(q, v, auxiliary_state)` with preserved leading axes.

normalize_configuration ¶

normalize_configuration(q: Array) -> Array

Normalize a floating spatial quaternion without changing hemisphere.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Configuration with trailing dimension `num_coordinates`.	required

Returns:

Type	Description
`Array`	The unchanged input for fixed or planar robots, or a configuration
`Array`	whose leading scalar-last quaternion has unit norm.

Raises:

Type	Description
`ValueError`	If a concrete spatial quaternion is zero or non-finite.

configuration_derivative ¶

configuration_derivative(q: Array, v: Array) -> Array

Map generalized velocity to the derivative of stored coordinates.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Configuration with trailing dimension `num_coordinates`.	required
`v`	`Array`	Velocity with trailing dimension `num_velocities`.	required

Returns:

Type	Description
`Array`	`qdot` with trailing dimension `num_coordinates`. Spatial base
`Array`	angular velocity is world-frame and left-multiplies the quaternion.

retract_configuration ¶

retract_configuration(q: Array, delta_v: Array) -> Array

Retract a velocity-space increment onto configuration space.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Configuration with trailing dimension `num_coordinates`.	required
`delta_v`	`Array`	Tangent increment with trailing dimension `num_velocities`.	required

Returns:

Type	Description
`Array`	Updated configuration. Spatial rotation increments left-multiply
`Array`	the scalar-last quaternion and the result is normalized.

base_transform_from_configuration ¶

base_transform_from_configuration(q: Array) -> Array

Convert the runtime or fixed base pose to homogeneous transforms.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Total configuration for floating robots or internal configuration for fixed robots.	required

Returns:

Type	Description
`Array`	A planar `(..., 3, 3)` or spatial `(..., 4, 4)` transform.

with_fixed_base_pose ¶

with_fixed_base_pose(pose: Array) -> Self

Return a fixed robot with a different mounting pose.

Parameters:

Name	Type	Description	Default
`pose`	`Array`	Planar pose with shape `(3,)` or spatial scalar-last quaternion pose with shape `(7,)`.	required

Returns:

Type	Description
`Self`	A functionally updated robot with mounting-dependent caches refreshed.

Raises:

Type	Description
`ValueError`	If the robot is floating or the pose is invalid.

with_actuator_params ¶

with_actuator_params(index: int, params) -> Self

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

update_actuator_params ¶

update_actuator_params(index: int, **updates: Any) -> Self

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

with_passive_element_params ¶

with_passive_element_params(index: int, params) -> Self

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

update_passive_element_params ¶

update_passive_element_params(index: int, **updates: Any) -> Self

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

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_coordinates,).	required
`s`	`Array`	Position parameter along the robot structure.	required

Returns:

Name	Type	Description
`J`	`Array`	Jacobian matrix of shape (n_pose_dim, num_velocities), 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_velocities).
`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_coordinates,).	required
`qd`	`Array`	Generalized velocities of shape (num_velocities,).	required
`s`	`Array`	Position parameter along the robot structure.	required

Returns:

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

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

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

Returns:

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

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_coordinates,).	required

Returns:

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

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return the installed transmissions' work-conjugate coordinates.

Coordinates are concatenated in actuator and channel order, matching the columns of :meth:actuation_matrix and the entries returned by :meth:actuator_efforts. Their physical units may differ between actuator families, such as length for tendons or volume for pressure actuation.

Parameters:

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

Returns:

Name	Type	Description
`y_a`	`Array`	Actuator coordinates of shape `(num_actuators,)`. An unactuated robot returns an empty array.

actuator_velocities ¶

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

Return the installed transmissions' coordinate velocities.

Velocities are concatenated in actuator and channel order and satisfy yd_a = A(q).T @ qd, where A(q) is the concatenated actuator transmission matrix.

Parameters:

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

Returns:

Name	Type	Description
`yd_a`	`Array`	Actuator-coordinate velocities of shape `(num_actuators,)`. An unactuated robot returns an empty array.

actuator_efforts ¶

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

Map user controls to work-conjugate actuator efforts.

Controls and returned efforts follow the order of the installed actuators. Effort models evaluate the actuator coordinates or velocities only when those quantities are required. If an effort model requires velocity and qd is omitted, zero generalized velocity is used.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_coordinates,).	required
`u`	`Array`	Actuator controls of shape (num_actuators,).	required
`qd`	`Array \| None`	Optional generalized velocities of shape (num_velocities,).	`None`
`actuation_matrix`	`Array \| None`	Optional precomputed actuator transmission matrix with shape `(num_velocities, num_actuators)`. It is reused for velocity-dependent effort laws.	`None`

Returns:

Name	Type	Description
`e`	`Array`	Work-conjugate actuator efforts of shape (num_actuators,).

Raises:

Type	Description
`ValueError`	If `u` or `actuation_matrix` has an incompatible shape.

passive_elastic_force ¶

passive_elastic_force(q: Array) -> Array

Return the installed passive elements' elastic generalized force.

This method sums only composable passive-element contributions. System implementations add the result to their intrinsic body elasticity when evaluating :meth:elastic_force.

Parameters:

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

Returns:

Name	Type	Description
`tau_passive`	`Array`	Passive elastic generalized force of shape `(num_velocities,)`. A robot without passive elements returns zeros.

passive_damping_matrix ¶

passive_damping_matrix(q: Array) -> Array

Return the installed passive elements' generalized damping matrix.

This method sums only composable passive-element contributions. System implementations add the result to their intrinsic body damping when evaluating :meth:damping_matrix.

Parameters:

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

Returns:

Name	Type	Description
`D_passive`	`Array`	Passive damping matrix of shape `(num_velocities, num_velocities)`. A robot without passive elements returns zeros.

passive_elastic_energy ¶

passive_elastic_energy(q: Array) -> Array

Return the installed passive elements' stored elastic energy.

This method sums only composable passive-element contributions. System implementations add the result to their intrinsic body strain energy when evaluating elastic or potential energy.

Parameters:

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

Returns:

Name	Type	Description
`U_passive`	`Array`	Scalar passive elastic energy. A robot without passive elements returns zero.

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_coordinates,).	required
`qd`	`Array`	Generalized velocities of shape (num_velocities,).	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_coordinates,).	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_coordinates,).	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_coordinates,).	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_coordinates,).	required
`qd`	`Array`	Generalized velocities of shape (num_velocities,).	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 ¶

num_base_coordinates property ¶

num_base_velocities property ¶

num_coordinates property ¶

num_velocities property ¶

num_auxiliary_states property ¶

state_size property ¶

actuator_input_metadata property ¶

length property ¶

supports_articulated_tendon_routing property ¶

base_transform property ¶

params_from_links staticmethod ¶

from_links classmethod ¶

cross_section_geometry ¶

with_params ¶

update_params ¶

update_link_params ¶

link_matrices_from_material ¶

with_isotropic_material ¶

precompute ¶

classify_segment ¶

strain ¶

forward_kinematics ¶

forward_kinematics_abscissa_batched ¶

forward_kinematics_tips ¶

inverse_kinematics ¶

jacobian_bodyframe ¶

jacobian_and_arc_length_derivative_bodyframe ¶

jacobian_arc_length_derivative_bodyframe ¶

jacobian_bodyframe_abscissa_batched ¶

jacobian_inertialframe ¶

jacobian_inertialframe_abscissa_batched ¶

forward_kinematics_and_jacobian_inertialframe ¶

forward_kinematics_and_jacobian_inertialframe_abscissa_batched ¶

jacobian_and_arc_length_derivative_inertialframe ¶

jacobian_arc_length_derivative_inertialframe ¶

jacobian_tips ¶

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe_abscissa_batched ¶

jacobian_and_time_derivative_inertialframe ¶

jacobian_and_time_derivative_inertialframe_abscissa_batched ¶

jacobian_abscissa_batched ¶

jacobian_and_time_derivative_abscissa_batched ¶

inertia_matrix ¶

coriolis_matrix ¶

stiffness_matrix ¶

elastic_force ¶

damping_matrix ¶

actuation_matrix ¶

actuation_force ¶

integration_kinematics ¶

dynamics_terms ¶

forward_dynamics ¶

project_state ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

pack_configuration ¶

split_configuration ¶

pack_velocity ¶

split_velocity ¶

pack_state ¶

split_state ¶

normalize_configuration ¶

configuration_derivative ¶

retract_configuration ¶

base_transform_from_configuration ¶

with_fixed_base_pose ¶

with_actuator_params ¶

update_actuator_params ¶

with_passive_element_params ¶

update_passive_element_params ¶

is_planar `property` ¶

segment_length `property` ¶

tangent_eps `property` ¶

num_base_coordinates `property` ¶

num_base_velocities `property` ¶

num_coordinates `property` ¶

num_velocities `property` ¶

num_auxiliary_states `property` ¶

state_size `property` ¶

actuator_input_metadata `property` ¶

length `property` ¶

supports_articulated_tendon_routing `property` ¶

base_transform `property` ¶

params_from_links `staticmethod` ¶

from_links `classmethod` ¶