Planar HSA¶

Planar Handed Shearing Auxetics (HSA) is a specialized planar PCS system for multi-rod auxetic soft robots. It uses the common PCS propagation and dynamics interfaces while adding HSA-specific rod geometry, platform and cap bodies, underactuation, and optional Bouc--Wen hysteresis.

API Reference¶

soromox.systems.pcs.planar_hsa.PlanarHSA ¶

PlanarHSA(params: PlanarHSAParams, structure: PlanarHSAStructure | None = None, *, base_pose: Array | None = None, floating_base: bool = False, **kwargs: Any)

Bases: PlanarPCS


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

                              soromox.systems.pcs.planar_pcs.PlanarPCS --> soromox.systems.pcs.planar_hsa.PlanarHSA
                                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_hsa.PlanarHSA href "" "soromox.systems.pcs.planar_hsa.PlanarHSA"
              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"

Kinematic and dynamic model for planar Handed Shearing Auxetics (HSA) robots.

The model uses a piecewise-constant virtual backbone with strain ordering [kappa_b, sigma_sh, sigma_a] per segment: bending curvature, shear strain, and axial strain. Physical rods are mapped to the virtual backbone through their offsets, and rigid caps, platforms, and the payload are included in forward kinematics and dynamics.

PlanarHSA reuses the planar PCS layout, SE(2) propagation, fixed Gauss--Legendre quadrature, strain selection, and differentiable-system interfaces. Kinematics, Jacobians, energies, forces, and forward dynamics are evaluated numerically with JAX and support JIT compilation. Optional underactuation maps motor inputs to rod forces, while optional Bouc--Wen hysteresis augments the elastic response.

Based on

Stölzle, M., Rus, D., & Della Santina, C. (2024). An experimental study of model-based control for planar handed shearing auxetics robots. In Experimental Robotics: The 18^th International Symposium (pp. 153-167). Springer. https://doi.org/10.1007/978-3-031-63596-0_14

Attributes:

Name	Type	Description
`num_segments`		Number of constant-strain segments.
`num_rods_per_segment`	`int`	Number of physical rods per segment.
`num_dofs`	`int`	Number of active strain coordinates.
`num_actuators`		Number of motor or direct-torque input channels.
`consider_underactuation`	`bool`	Whether motor-to-rod actuation is enabled.
`consider_hysteresis`	`bool`	Whether Bouc--Wen hysteresis is enabled.
`num_hysteresis`	`int`	Number of hysteresis state variables.
`B_xi`		Basis mapping active coordinates to virtual-backbone strains.
`L`		Flexible segment lengths.
`L_cum`		Cumulative flexible segment lengths.
`length`	`Array`	Total backbone length inherited from :class:`SoftRobot`.
`rod_offset`	`Array`	Physical rod offsets from the virtual backbone.
`platform_dimension`	`Array`	Platform width, height, and depth per segment.
`proximal_cap_length`	`Array`	Rigid proximal cap lengths.
`distal_cap_length`	`Array`	Rigid distal cap lengths.
`end_effector_offset`	`Array`	End-effector pose offset `[theta, x, y]`.
`xi_ref`		Runtime reference virtual-backbone strain inherited from :class:`PlanarPCS`. The canonical physical-rod input is `params.reference_strain`.
`phi_max`	`Array`	Motor limits for underactuated operation.
`hysteresis_basis`	`Array`	Basis mapping hysteresis states to full strains.
`hysteresis_alpha`	`Array`	Post-yield to pre-yield stiffness ratios.
`hysteresis_A`	`Array`	Bouc--Wen `A` parameters.
`hysteresis_n`	`Array`	Bouc--Wen exponents.
`hysteresis_beta`	`Array`	Bouc--Wen `beta` parameters.
`hysteresis_gamma`	`Array`	Bouc--Wen `gamma` parameters.

Initialize a numerical planar HSA model.

Parameters:

Name	Type	Description	Default
`params`	`PlanarHSAParams`	Typed physical parameters for the HSA rods, rigid bodies, constitutive laws, and optional hysteresis model.	required
`structure`	`PlanarHSAStructure \| None`	Numerical settings such as quadrature order, active strain selection, and underactuation/hysteresis switches. Defaults to :class:`PlanarHSAStructure` defaults.	`None`
`**kwargs`	`Any`	Additional :class:`SoftRobot` initialization options, including `eps`.	`{}`

Raises:

Type	Description
`TypeError`	If `params` or `structure` has the wrong type.
`ValueError`	If the typed parameters or numerical settings are invalid.

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

segment_length `property` ¶

segment_length: Array

Return the per-segment backbone lengths.

Returns:

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

is_planar `property` ¶

is_planar: bool

Return whether the system is planar.

Returns:

Type	Description
`bool`	Always `True`.

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.

with_params ¶

with_params(params: PlanarHSAParams) -> PlanarHSA

Return a model copy with all physical parameters replaced.

The number of segments and rods is part of the model structure. A change to either shape therefore requires constructing a new model; all other parameter changes refresh the state-independent caches on the returned copy.

Parameters:

Name	Type	Description	Default
`params`	`PlanarHSAParams`	Validated HSA parameters with the same segment and rod layout as this model.	required

Returns:

Type	Description
`PlanarHSA`	A new :class:`PlanarHSA` with the supplied parameters.

Raises:

Type	Description
`TypeError`	If `params` is not a :class:`PlanarHSAParams`.
`ValueError`	If the segment or rod layout changes.

update_params ¶

update_params(**updates: Array) -> PlanarHSA

Return a model copy with selected physical fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Array`	Field names and replacement values accepted by :meth:`PlanarHSAParams.replace`.	`{}`

Returns:

Type	Description
`PlanarHSA`	A new model with refreshed numerical caches.

cross_section_geometry ¶

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

Return a renderer-compatible cross-section descriptor.

HSA rods are represented by a circular section whose radius is the largest rod offset in the segment containing s. The generalized coordinates do not affect this geometric descriptor.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates. Accepted for the common renderer API.	required
`s`	`Array`	Arc-length coordinate along the flexible backbone.	required

Returns:

Type	Description
`Array`	A pair containing the circular-section enum and a one-element
`Array`	array containing the section radius.

virtual_to_physical_strains ¶

virtual_to_physical_strains(vxi: Array) -> Array

Map virtual-backbone strains to physical rod strains.

The virtual strain vector uses three components per segment. HSA rods share bending and shear strains, while the axial strain of a rod is shifted by its signed lateral offset and the segment curvature.

Parameters:

Name	Type	Description	Default
`vxi`	`Array`	Virtual strains with shape `(3 * num_segments,)`.	required

Returns:

Type	Description
`Array`	Physical rod strains with shape
`Array`	`(num_segments, num_rods_per_segment, 3)`.

physical_to_virtual_strains ¶

physical_to_virtual_strains(pxi: Array) -> Array

Map physical rod strains to the least-squares virtual strain.

The inverse uses the mean across rods and removes the offset-induced axial contribution from the virtual axial component.

Parameters:

Name	Type	Description	Default
`pxi`	`Array`	Physical rod strains with shape `(num_segments, num_rods_per_segment, 3)`.	required

Returns:

Type	Description
`Array`	Virtual strains flattened to shape `(3 * num_segments,)`.

forward_kinematics_rod ¶

forward_kinematics_rod(q: Array, s: Array, rod_idx: Array) -> Array

Return the pose of a physical rod centerline point.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates with shape `(num_dofs,)`.	required
`s`	`Array`	Arc-length coordinate along the flexible backbone.	required
`rod_idx`	`Array`	Index of the rod within the segment containing `s`.	required

Returns:

Type	Description
`Array`	Planar pose `[theta, x, y]` of the rod point in the base frame.

forward_kinematics_platform ¶

forward_kinematics_platform(q: Array, segment_idx: Array) -> Array

Return the pose of the platform belonging to one segment.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates with shape `(num_dofs,)`.	required
`segment_idx`	`Array`	Integer segment index.	required

Returns:

Type	Description
`Array`	Planar pose `[theta, x, y]` at the platform center.

forward_kinematics_end_effector ¶

forward_kinematics_end_effector(q: Array) -> Array

Return the pose of the HSA end effector.

Parameters:

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

Returns:

Type	Description
`Array`	End-effector pose `[theta, x, y]` in the base frame, including
`Array`	the distal cap, platform, and configured end-effector offset.

jacobian_end_effector ¶

jacobian_end_effector(q: Array) -> Array

Return the end-effector geometric Jacobian.

The row ordering is [x, y, theta] and the columns correspond to the active generalized coordinates. The result maps generalized velocities to the planar end-effector velocity in the inertial frame.

Parameters:

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

Returns:

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

jacobian_and_time_derivative_end_effector ¶

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

Return the end-effector Jacobian and its time derivative.

Parameters:

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

Returns:

Type	Description
`Array`	A pair `(J, Jd)`. Both arrays have shape `(3, num_dofs)` and
`Array`	`Jd` is the convective time derivative evaluated at `(q, qd)`.

inverse_kinematics ¶

inverse_kinematics(chi_ee: Array) -> Array

Solve one-segment constant-strain inverse kinematics.

The analytic solution accounts for the proximal and distal rigid geometry and returns active coordinates that reproduce the requested end-effector pose. As in the underlying model, this method is only defined for a single flexible segment.

Parameters:

Name	Type	Description	Default
`chi_ee`	`Array`	Desired end-effector pose `[theta, x, y]`.	required

Returns:

Type	Description
`Array`	Active generalized coordinates with shape `(num_dofs,)`.

Raises:

Type	Description
`AssertionError`	If the model has more than one segment.

integration_kinematics ¶

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

Return quadrature poses, Jacobians, and Jacobian derivatives.

The returned quantities are assembled over the interior fixed Gauss--Legendre points of every flexible segment and are used by the numerical dynamics implementation.

Parameters:

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

Returns:

Type	Description
`Array`	`(g_ps, J_ps, Jd_ps)` where `g_ps` has shape
`Array`	`(num_segments, num_gauss_points, 3, 3)` and both Jacobian
`Array`	arrays have shape `(num_segments, num_gauss_points, 3, num_dofs)`.

inertia_matrix ¶

inertia_matrix(q: Array) -> Array

Return the active-coordinate generalized inertia matrix.

The matrix is assembled from the physical rods, rigid platforms, caps, and payload using the fixed Gauss--Legendre grid. It is symmetric and positive semidefinite up to numerical round-off.

Parameters:

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

Returns:

Type	Description
`Array`	Inertia matrix with shape `(num_dofs, num_dofs)`.

coriolis_matrix ¶

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

Return the Christoffel-consistent Coriolis matrix.

The matrix is constructed analytically from the configuration derivative of the inertia matrix. It satisfies the convention used by :class:SoftRobot, namely that C(q, qd) @ qd is the convective generalized force.

Parameters:

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

Returns:

Type	Description
`Array`	Coriolis matrix with shape `(num_dofs, num_dofs)`.

stiffness_matrix ¶

stiffness_matrix() -> Array

Return the cached active-coordinate elastic stiffness matrix.

elastic_force ¶

elastic_force(q: Array) -> Array

Return the generalized elastic force at configuration q.

Parameters:

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

Returns:

Type	Description
`Array`	Elastic generalized force with shape `(num_dofs,)`.

damping_matrix ¶

damping_matrix(q: Array) -> Array

Return the cached active-coordinate damping matrix.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates. The HSA damping matrix is configuration independent, so this argument is unused.	required

Returns:

Type	Description
`Array`	Damping matrix with shape `(num_dofs, num_dofs)`.

actuation_force ¶

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

Return generalized forces generated by HSA actuation.

With underactuation disabled, phi is interpreted directly as an active generalized-force vector. With underactuation enabled, it is interpreted as one motor rotation per physical rod and mapped through the HSA rod stiffness and strain geometry.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates with shape `(num_dofs,)`.	required
`phi`	`Array`	Motor rotations or direct generalized forces, depending on `consider_underactuation`.	required
`qd`	`Array \| None`	Generalized velocities. Accepted for the common actuation API; HSA actuation is velocity independent.	`None`

Returns:

Type	Description
`Array`	Generalized actuation force with shape `(num_dofs,)`.

hysteresis_force ¶

hysteresis_force(q: Array, z: Array) -> Array

Return the generalized force contributed by hysteresis state z.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates. The force depends only on the configured hysteresis state for this model.	required
`z`	`Array`	Hysteresis coordinates with shape `(num_hysteresis,)`.	required

Returns:

Type	Description
`Array`	Generalized hysteresis force with shape `(num_dofs,)`.

dynamics_terms ¶

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

Return inertia, convective, and gravitational dynamics terms.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Active generalized coordinates with shape `(num_dofs,)`.	required
`qd`	`Array`	Generalized velocities with shape `(num_dofs,)`.	required
`backend`	`ExecutionBackend \| None`	Optional backend override. PlanarHSA currently supports JAX execution only.	`None`

Returns:

Type	Description
`Array`	A tuple `(B, Cqd, G)` with shapes `(num_dofs, num_dofs)`,
`Array`	`(num_dofs,)`, and `(num_dofs,)` respectively.

Raises:

Type	Description
`NotImplementedError`	If Warp execution is requested.

forward_dynamics ¶

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

Compute the HSA first-order state derivative.

The state is [q, qd] without hysteresis and [q, qd, z] when hysteresis is enabled. The supplied actuation tuple may contain the motor/direct-force input and optionally an external generalized force.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Simulation time. HSA dynamics are autonomous, so this argument is accepted but not used explicitly.	required
`y`	`Array`	State vector with shape `(2 * num_dofs,)` or `(2 * num_dofs + num_hysteresis,)`.	required
`actuation_args`	`tuple \| None`	`None`, `(u,)`, or `(u, tau_ext)`.	`None`

Returns:

Type	Description
`Array`	State derivative with the same shape as `y`.

Raises:

Type	Description
`ValueError`	If `actuation_args` has a length other than one or two.

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.

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.

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 ¶

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

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

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

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.

actuation_matrix ¶

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

Return the actuator matrix through the selected execution backend.

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

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.

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.

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

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

Model Features¶

Piecewise-constant virtual-backbone strain with numerical Cosserat rod quadrature
Multiple physical rods per segment
Rigid caps, platforms, and end-effector offsets
Optional motor-to-rod underactuation
Optional Bouc--Wen hysteresis
JAX-native kinematics, Jacobians, energies, and dynamics

Reference¶

Stölzle, M., Rus, D., & Della Santina, C. (2024). An experimental study of model-based control for planar handed shearing auxetics robots. In Experimental Robotics: The 18^th International Symposium (pp. 153–167). Springer. doi:10.1007/978-3-031-63596-0_14

Planar HSA¶

API Reference¶

soromox.systems.pcs.planar_hsa.PlanarHSA ¶

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 ¶

segment_length property ¶

is_planar property ¶

supports_articulated_tendon_routing property ¶

base_transform property ¶

with_params ¶

update_params ¶

cross_section_geometry ¶

virtual_to_physical_strains ¶

physical_to_virtual_strains ¶

forward_kinematics_rod ¶

forward_kinematics_platform ¶

forward_kinematics_end_effector ¶

jacobian_end_effector ¶

jacobian_and_time_derivative_end_effector ¶

inverse_kinematics ¶

integration_kinematics ¶

inertia_matrix ¶

coriolis_matrix ¶

stiffness_matrix ¶

elastic_force ¶

damping_matrix ¶

actuation_force ¶

hysteresis_force ¶

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 ¶

precompute ¶

with_actuator_params ¶

update_actuator_params ¶

with_passive_element_params ¶

update_passive_element_params ¶

forward_kinematics ¶

forward_kinematics_tips ¶

forward_kinematics_abscissa_batched ¶

forward_kinematics_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative ¶

jacobian ¶

jacobian_tips ¶

jacobian_abscissa_batched ¶

jacobian_arc_length_derivative ¶

jacobian_and_arc_length_derivative ¶

jacobian_and_time_derivative ¶

jacobian_and_time_derivative_abscissa_batched ¶

jacobian_bodyframe ¶

jacobian_bodyframe_abscissa_batched ¶

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe_abscissa_batched ¶

gravitational_force ¶

potential_force ¶

actuator_coordinates ¶

actuator_velocities ¶

actuation_matrix ¶

actuator_efforts ¶

passive_elastic_force ¶

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` ¶

segment_length `property` ¶

is_planar `property` ¶

supports_articulated_tendon_routing `property` ¶

base_transform `property` ¶

params_from_links `staticmethod` ¶

from_links `classmethod` ¶