Planar HSA Systems¶

The Planar Handed Shearing Auxetics (HSA) systems provide implementations for soft robots with auxetic properties in planar settings.

Overview¶

HSA robots exhibit unique mechanical properties due to their auxetic structure, which allows for interesting deformation patterns and control strategies. This module implements the kinematic and dynamic models for planar HSA robots.

Planar HSA geometry rendered with the specialized OpenCV backend — The specialized OpenCV renderer preserves the HSA platform and rod geometry in fast planar output.

API Reference¶

soromox.systems.hsa.planar_hsa ¶

PlanarHSA ¶

PlanarHSA(params: PlanarHSAParams, structure: PlanarHSAStructure, **kwargs: Any)

Bases: SoftRobot


              flowchart TD
              soromox.systems.hsa.planar_hsa.PlanarHSA[PlanarHSA]
              soromox.systems.soft_robot.SoftRobot[SoftRobot]
              soromox.systems.dynamical_system.DynamicalSystem[DynamicalSystem]

                              soromox.systems.soft_robot.SoftRobot --> soromox.systems.hsa.planar_hsa.PlanarHSA
                                soromox.systems.dynamical_system.DynamicalSystem --> soromox.systems.soft_robot.SoftRobot
                



              click soromox.systems.hsa.planar_hsa.PlanarHSA href "" "soromox.systems.hsa.planar_hsa.PlanarHSA"
              click soromox.systems.soft_robot.SoftRobot href "" "soromox.systems.soft_robot.SoftRobot"
              click soromox.systems.dynamical_system.DynamicalSystem href "" "soromox.systems.dynamical_system.DynamicalSystem"

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

This class implements the geometric and dynamic modeling of planar HSA robots using a piecewise constant strain assumption. It supports computation of forward kinematics, inverse kinematics, Jacobians, and dynamical matrices. The model accounts for hysteresis effects using the Bouc-Wen model when enabled.

Based on the publication

Stölzle, M., Rus, D., & Della Santina, C. (2023, November). An experimental study of model-based control for planar handed shearing auxetics robots. In International Symposium on Experimental Robotics (pp. 153-167). Cham: Springer Nature Switzerland. https://link.springer.com/chapter/10.1007/978-3-031-63596-0_14

Attributes:

Name	Type	Description
`num_segments`	`int`	Number of segments along the robot.
`num_rods_per_segment`	`int`	Number of physical rods per segment.
`num_dofs`		Number of degrees of freedom (active strain components).
`num_actuators`		Number of actuators in the robot.
`consider_underactuation`	`bool`	Whether to consider underactuation in the model.
`consider_hysteresis`	`bool`	Whether to consider hysteresis effects in the model.
`num_hysteresis`	`int`	Number of hysteresis state variables.
`chiv_lambda_sms`	`list[Callable]`	Lambda functions for virtual backbone forward kinematics per segment.
`chir_lambda_sms`	`list[Callable]`	Lambda functions for physical rod forward kinematics per segment.
`chip_lambda_sms`	`list[Callable]`	Lambda functions for platform forward kinematics per segment.
`chiee_lambda`	`Callable`	Lambda function for end-effector forward kinematics.
`Jee_lambda`	`Callable`	Lambda function for end-effector Jacobian.
`Jeed_lambda`	`Callable`	Lambda function for end-effector Jacobian time derivative.
`B_lambda`	`Callable`	Lambda function for inertia matrix computation.
`C_lambda`	`Callable`	Lambda function for Coriolis matrix computation.
`G_lambda`	`Callable`	Lambda function for gravitational force computation.
`Shat_lambda`	`Callable`	Lambda function for nominal stiffness matrix computation.
`K_lambda`	`Callable`	Lambda function for elastic force computation.
`D_lambda`	`Callable`	Lambda function for damping matrix computation.
`alpha_lambda`	`Callable`	Lambda function for actuation force computation.
`B_xi`	`Array`	Strain basis matrix for mapping active strain components.
`kappa_b_ref`	`Array`	Reference bending curvatures for each rod. Shape: (num_segments, num_rods_per_segment).
`sigma_sh_ref`	`Array`	Reference shear strains for each rod. Shape: (num_segments, num_rods_per_segment).
`sigma_a_ref`	`Array`	Reference axial strains for each rod. Shape: (num_segments, num_rods_per_segment).
`L`	`Array`	Segment lengths. Shape: (num_segments,).
`L_cum`	`Array`	Cumulative segment lengths. Shape: (num_segments + 1,).
`Lmax`	`Array`	Total robot length (sum of all segments).
`roff`	`Array`	Rod offset from centerline. Shape: (num_segments, num_rods_per_segment).
`pcudim`	`Array`	Platform dimensions (width, height, depth). Shape: (num_segments, 3).
`lpc`	`Array`	Length of rigid proximal rod caps. Shape: (num_segments,).
`ldc`	`Array`	Length of rigid distal rod caps. Shape: (num_segments,).
`chiee_off`	`Array`	End-effector offset transformation [theta, p_x, p_y]. Shape: (3,).
`B_hyst`	`Array`	Hysteresis basis matrix. Shape: (num_dofs, num_hysteresis).
`hyst_alpha`	`Array`	Bouc-Wen hysteresis parameter: ratio of post-yield to pre-yield stiffness.
`hyst_A`	`Array`	Bouc-Wen hysteresis parameter A.
`hyst_n`	`Array`	Bouc-Wen hysteresis parameter n.
`hyst_beta`	`Array`	Bouc-Wen hysteresis parameter beta.
`hyst_gamma`	`Array`	Bouc-Wen hysteresis parameter gamma.
`params_for_lambdify`	`list[Array]`	Flattened parameter list for symbolic function evaluation.

Notes:¶

The strain vector is composed of 3 components per segment: [kappa_b, sigma_sh, sigma_a] representing bending curvature, shear strain, and axial strain respectively.
The robot uses a virtual backbone representation with physical rod mapping for accurate modeling of HSA mechanics.
Hysteresis modeling is optional and uses the Bouc-Wen model when consider_hysteresis=True.

References

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

Initialize the PlanarHSA system.

Parameters:

Name	Type	Description	Default
`params`	`PlanarHSAParams`	Dynamic HSA parameters.	required
`structure`	`PlanarHSAStructure`	Static symbolic expression path and layout choices. This includes the strain selector, underactuation flag, hysteresis flag, and regularization epsilon.	required
`**kwargs`	`Any`	Additional keyword arguments for SoftRobot.init.	`{}`

is_planar `property` ¶

is_planar: bool

Planar HSA is a 2D model.

segment_length `property` ¶

segment_length: Array

Per-segment backbone lengths.

tangent_eps `property` ¶

tangent_eps: Array

Epsilon value for Lie algebra tangent computations.

Returns:

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

actuator_input_metadata `property` ¶

actuator_input_metadata: tuple[ActuatorMetadata, ...]

Metadata groups in the same order used to concatenate controls.

length `property` ¶

length: Array

Total backbone length of the robot (scalar).

supports_articulated_tendon_routing `property` ¶

supports_articulated_tendon_routing: bool

Whether joint indices describe a serial articulated routing topology.

base_transform `property` ¶

base_transform: Array

Return the homogeneous transform represented by base_pose.

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

cross_section_geometry ¶

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

Circular cross-section using max rod offset for the segment.

with_params ¶

with_params(params: PlanarHSAParams) -> PlanarHSA

Return an updated copy with a full typed parameter object.

update_params ¶

update_params(**updates: Array) -> PlanarHSA

Return an updated copy with selected typed parameter fields replaced.

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_local`	`Array`	point coordinate along the segment in the interval [0, l_segment]

strain ¶

strain(q: Array) -> Array

Map the generalized coordinates to the strains in the virtual backbone Args: q: generalized coordinates of shape (num_dofs, )

Returns:

Name	Type	Description
`xi`	`Array`	strains of the virtual backbone of shape (num_dofs, )

beta ¶

beta(vxi: Array) -> Array

Map the generalized coordinates to the strains in the physical rods Args: vxi: strains of the virtual backbone of shape (num_dofs, )

Returns:

Name	Type	Description
`pxi`	`Array`	strains in the physical rods of shape (num_segments, num_rods_per_segment, 3)

beta_inv ¶

beta_inv(pxi: Array) -> Array

Map the strains in the physical rods to the strains of the virtual backbone Args: pxi: strains in the physical rods of shape (num_segments, num_rods_per_segment, 3)

Returns:

Name	Type	Description
`vxi`	`Array`	strains of the virtual backbone of shape (num_dofs, )

ref_strains ¶

ref_strains() -> Array

Compute the ref strains of the virtual backbone

Returns:

Name	Type	Description
`vxi_ref`	`Array`	ref strains of the virtual backbone of shape (num_dofs, )

apply_eps_to_bend_strains ¶

apply_eps_to_bend_strains(xi: Array, eps: float | None = None) -> Array

Add a small number to the bending strain to avoid singularities Args: xi: strains of the virtual backbone of shape (num_dofs, ) eps: small number to add to the bending strain (optional). By default, it will be initialized to as self.global_eps

forward_kinematics_virtual_backbone ¶

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

Evaluate the forward kinematics the virtual backbone Args: q: generalized coordinates of shape (num_dofs, ) s: point coordinate along the rod in the interval [0, L].

Returns:

Name	Type	Description
`chi`	`Array`	pose of the backbone point in Cartesian-space with shape (3, ) Consists of [theta, p_x, p_y] where theta is the planar orientation with respect to the x-axis, p_x is the x-position, p_y is the y-position,

forward_kinematics_tips ¶

forward_kinematics_tips(q: Array) -> Array

Compute virtual-backbone forward kinematics at all segment tips.

Parameters:

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

Returns:

Name	Type	Description
`chi_tips`	`Array`	virtual-backbone poses at each segment tip, shape (num_segments, 3).

forward_kinematics_rod ¶

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

Evaluate the forward kinematics of the physical rods Args: params: Dictionary of robot parameters q: generalized coordinates of shape (num_dofs, ) s: point coordinate along the rod in the interval [0, L]. rod_idx: index of the rod. If there are two rods per segment, then rod_idx can be 0 or 1.

Returns:

Name	Type	Description
`chir`	`Array`	pose of the rod centerline point in Cartesian-space with shape (3, ) Consists of [theta, p_x, p_y] where theta is the planar orientation with respect to the x-axis, p_x is the x-position, p_y is the y-position,

forward_kinematics_platform ¶

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

Evaluate the forward kinematics the platform Args: q: generalized coordinates of shape (num_dofs, ) segment_idx: index of the segment

Returns:

Name	Type	Description
`chip`	`Array`	pose of the CoG of the platform in Cartesian-space with shape (3, ) Consists of [theta, p_x, p_y] where theta is the planar orientation with respect to the x-axis, p_x is the x-position, p_y is the y-position,

forward_kinematics_end_effector ¶

forward_kinematics_end_effector(q: Array) -> Array

Evaluate the forward kinematics of the end-effector Args: q: generalized coordinates of shape (num_dofs, )

Returns:

Name	Type	Description
`chiee`	`Array`	pose of the end-effector in Cartesian-space of shape (3, ) Consists of [theta, p_x, p_y] where theta is the planar orientation with respect to the x-axis, p_x is the x-position, p_y is the y-position,

jacobian_end_effector ¶

jacobian_end_effector(q: Array) -> Array

Evaluate the Jacobian of the end-effector Args: q: generalized coordinates of shape (num_dofs, )

Returns:

Name	Type	Description
`Jee`	`Array`	the Jacobian of the end-effector pose with respect to the generalized coordinates. Jee is an array of shape (3, num_dofs).

jacobian_virtual_backbone ¶

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

Compute the Jacobian of the virtual backbone forward kinematics at a point s.

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

Parameters:

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

Returns:

Name	Type	Description
`J`	`Array`	Jacobian matrix of shape (3, num_dofs), mapping velocities in configuration space to velocities in operational space [omega_z, v_x, v_y].

jacobian_tips ¶

jacobian_tips(q: Array) -> Array

Compute inertial-frame virtual-backbone Jacobians at all segment tips.

Parameters:

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

Returns:

Name	Type	Description
`J_tips`	`Array`	Jacobians at each segment tip, shape (num_segments, 3, num_dofs).

jacobian_and_time_derivative_virtual_backbone ¶

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

Compute the Jacobian and its time derivative of the virtual backbone at point s.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_dofs,).	required
`qd`	`Array`	Generalized velocities of shape (num_dofs,).	required
`s`	`Array`	Point coordinate along the robot in the interval [0, L].	required

Returns:

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

inverse_kinematics_end_effector ¶

inverse_kinematics_end_effector(chiee: Array) -> Array

Evaluates the inverse kinematics for a given end-effector pose. Important: only works for one segment! Args: params: Dictionary of robot parameters chiee: pose of the end-effector in Cartesian-space of shape (3, ) eps: small number to avoid singularities (e.g., division by zero)

Returns:

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

inertia_matrix ¶

inertia_matrix(q: Array, eps: float | None = None) -> Array

Compute the inertia matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_dofs,).	required
`eps`	`float`	small number to avoid singularities (e.g., division by zero). By default, it will be initialized to 1e4 * self.global_eps.	`None`

Returns:

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

coriolis_matrix ¶

coriolis_matrix(q: Array, qd: Array, eps: float | None = None) -> Array

Compute the Coriolis matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_dofs,).	required
`qd`	`Array`	time-derivative of the generalized coordinates of shape (num_dofs,).	required
`eps`	`float`	small number to avoid singularities (e.g., division by zero). By default, it will be initialized to 1e4 * self.global_eps.	`None`

Returns:

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

elastic_force ¶

elastic_force(q: Array) -> Array

Compute the conservative elastic force vector of the robot.

This is the gradient of elastic_energy(q) and intentionally excludes hysteresis-state effects. Hysteresis contributions are provided by hysteresis_force and are combined in forward_dynamics.

Parameters:

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

Returns:

Name	Type	Description
`K`	`Array`	Stiffness vector of shape (num_dofs, ).

hysteresis_force ¶

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

Compute the hysteresis-state elastic force contribution.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_dofs,).	required
`z`	`Array`	hysteresis state vector of shape (num_hysteresis,).	required

Returns:

Name	Type	Description
`K_hyst`	`Array`	Hysteresis force vector of shape (num_dofs,).

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

Returns:

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

actuation_force ¶

actuation_force(q: Array, phi: Array) -> Array

Compute the actuation matrix of the robot.

Parameters:

Name	Type	Description	Default
`q`	`Array`	generalized coordinates of shape (num_dofs,).	required
`phi`	`Array`	motor positions / twist angles of shape (num_segments * num_rods_per_segment, )	required

Returns:

Name	Type	Description
`alpha`	`Array`	Actuation matrix of shape (num_dofs, num_dofs).

Shat ¶

Shat() -> Array

Compute the nominal stiffness of the robot.

Returns:

Name	Type	Description
`Array`	`Array`	Nominal stiffness matrix of shape (num_dofs, num_dofs).

stiffness_matrix ¶

stiffness_matrix() -> Array

Compute the stiffness matrix of the robot in configuration space.

Returns:

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

forward_dynamics ¶

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

Forward dynamics function.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time.	required
`y`	`Array`	State vector containing configuration, velocity, and possibly hysteresis state. Shape is (2 * num_dofs + num_hysteresis,).	required
`actuation_args`	`Tuple`	Additional arguments for the actuation function. - u (Array): Actuation input. If consider_underactuation is True, this is an array of shape (num_actuators, ) with motor positions / twist angles of the proximal end of the rods. If consider_underactuation is False, this is an array of shape (num_dofs, ) with the configuration-space torques. - tau_ext (Array, optional): External generalized forces, shape (num_dofs,).	required

Returns:

Name	Type	Description
`yd`	`Array`	Time derivative of the state vector of shape (2 * num_dofs + num_hysteresis, ).

rollout_to ¶

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

Roll out the system dynamics in open loop using Diffrax.

Parameters:

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

Returns:

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

rollout_closed_loop_to ¶

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

Roll out the system dynamics in closed loop using Diffrax.

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

Parameters:

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

Returns:

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

rollout_discrete_closed_loop_to ¶

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

Roll out the system in discrete-time closed loop.

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

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

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

Parameters:

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

Returns:

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

precompute ¶

precompute() -> None

Optional hook for refreshing state-independent cached quantities.

Subclasses with cached mass, stiffness, damping, basis, or quadrature data can override this method and call it during initialization. Models without such caches can inherit this no-op implementation.

with_actuator_params ¶

with_actuator_params(index: int, params) -> SoftRobot

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

update_actuator_params ¶

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

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

with_passive_element_params ¶

with_passive_element_params(index: int, params) -> SoftRobot

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

update_passive_element_params ¶

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

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

forward_kinematics ¶

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

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

Parameters:

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

Returns:

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

forward_kinematics_batched ¶

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

Compute the forward kinematics at multiple points along the robot.

Default implementation uses vmap over forward_kinematics. Subclasses may override this for more efficient batch computation.

Parameters:

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

Returns:

Name	Type	Description
`chi_ps`	`Array`	Poses at all points, shape depends on robot type.

forward_kinematics_arc_length_derivative ¶

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

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

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

forward_kinematics_and_arc_length_derivative ¶

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

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

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

jacobian ¶

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

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

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

Parameters:

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

Returns:

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

jacobian_batched ¶

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

Compute the Jacobian at multiple points along the robot.

Default implementation uses vmap over jacobian. Subclasses may override this for more efficient batch computation.

Parameters:

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

Returns:

Name	Type	Description
`J_ps`	`Array`	Jacobians at all points, shape (N, n_pose_dim, num_dofs).

jacobian_arc_length_derivative ¶

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

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

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

jacobian_and_arc_length_derivative ¶

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

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

Returns:

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

jacobian_and_time_derivative ¶

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

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

Parameters:

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

Returns:

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

jacobian_and_time_derivative_batched ¶

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

Compute the Jacobian and its derivative at multiple points along the robot.

Default implementation uses vmap over jacobian_and_time_derivative. Subclasses may override this for more efficient batch computation.

Parameters:

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

Returns:

Name	Type	Description
`J_ps`	`Array`	Jacobians at all points, shape (N, n_pose_dim, num_dofs).
`Jd_ps`	`Array`	Jacobian time derivatives at all points, shape (N, n_pose_dim, num_dofs).

jacobian_bodyframe ¶

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

Compute the body-frame Jacobian at a point s along the robot.

The default implementation converts the public inertial-frame Jacobian to the local pose frame using the rotation-only convention used by the dynamics integrands.

jacobian_bodyframe_batched ¶

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

Compute body-frame Jacobians at multiple points along the robot.

jacobian_and_time_derivative_bodyframe ¶

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

Compute a body-frame Jacobian and its time derivative at s.

The default differentiates jacobian_bodyframe with respect to the generalized coordinates.

jacobian_and_time_derivative_bodyframe_batched ¶

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

Compute body-frame Jacobians and time derivatives at many points.

integration_kinematics ¶

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

Evaluate poses, body-frame Jacobians, and Jacobian derivatives at interior integration nodes.

The default implementation is intentionally unfused. It samples integration_points[..., 1:-1] for every segment, maps normalized nodes to arclength, and calls the public kinematics/Jacobian APIs. Subclasses can override this method with a fused implementation.

Returns:

Type	Description
`Array`	Tuple `(g_ps, J_ps, Jd_ps)` with leading axes
`Array`	`(num_segments, num_inner_points)`.

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

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

Returns:

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

potential_force ¶

potential_force(q: Array) -> Array

Compute the total conservative generalized force.

This is the sum of gravitational and elastic forces.

Parameters:

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

Returns:

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

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return all work-conjugate actuator coordinates in control order.

actuator_velocities ¶

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

Return all actuator-coordinate velocities in control order.

actuation_matrix ¶

actuation_matrix(q: Array) -> Array

Return the concatenated transmission moment matrix.

actuator_efforts ¶

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

Map ordered user controls to ordered work-conjugate efforts.

passive_elastic_force ¶

passive_elastic_force(q: Array) -> Array

Return the sum of installed passive conservative forces.

passive_damping_matrix ¶

passive_damping_matrix(q: Array) -> Array

Return the sum of installed passive damping matrices.

passive_elastic_energy ¶

passive_elastic_energy(q: Array) -> Array

Return the sum of installed passive elastic energies.

actuator_visual_layers ¶

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

Return semantic active and passive actuator geometry for renderers.

kinetic_energy ¶

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

Compute the kinetic energy of the system.

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

Parameters:

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

Returns:

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

gravitational_energy ¶

gravitational_energy(q: Array) -> Array

Compute the gravitational potential energy of the system.

Parameters:

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

Returns:

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

elastic_energy ¶

elastic_energy(q: Array) -> Array

Compute the elastic potential energy stored in the system.

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

Parameters:

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

Returns:

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

potential_energy ¶

potential_energy(q: Array) -> Array

Compute the total potential energy of the system.

This is the sum of gravitational and elastic energy.

Parameters:

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

Returns:

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

total_energy ¶

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

Compute the total energy of the system.

This is the sum of kinetic and potential energy.

Parameters:

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

Returns:

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

dynamics_terms ¶

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

Return forward-dynamics terms (M, Cqd, G).

Cqd is the convective force vector C(q, qd) @ qd. The default implementation is intentionally unfused and calls the public matrix and force APIs separately. Overrides must keep M and Cqd energy-consistent with inertia_matrix and coriolis_matrix.

Planar HSA Systems¶

Overview¶

API Reference¶

soromox.systems.hsa.planar_hsa ¶

PlanarHSA ¶

Notes:¶

is_planar property ¶

segment_length property ¶

tangent_eps property ¶

actuator_input_metadata property ¶

length property ¶

supports_articulated_tendon_routing property ¶

base_transform property ¶

cross_section_geometry ¶

with_params ¶

update_params ¶

classify_segment ¶

strain ¶

beta ¶

beta_inv ¶

ref_strains ¶

apply_eps_to_bend_strains ¶

forward_kinematics_virtual_backbone ¶

forward_kinematics_tips ¶

forward_kinematics_rod ¶

forward_kinematics_platform ¶

forward_kinematics_end_effector ¶

jacobian_end_effector ¶

jacobian_virtual_backbone ¶

jacobian_tips ¶

jacobian_and_time_derivative_virtual_backbone ¶

inverse_kinematics_end_effector ¶

inertia_matrix ¶

coriolis_matrix ¶

elastic_force ¶

hysteresis_force ¶

damping_matrix ¶

actuation_force ¶

Shat ¶

stiffness_matrix ¶

forward_dynamics ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

precompute ¶

with_actuator_params ¶

update_actuator_params ¶

with_passive_element_params ¶

update_passive_element_params ¶

forward_kinematics ¶

forward_kinematics_batched ¶

forward_kinematics_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative ¶

jacobian ¶

jacobian_batched ¶

jacobian_arc_length_derivative ¶

jacobian_and_arc_length_derivative ¶

jacobian_and_time_derivative ¶

jacobian_and_time_derivative_batched ¶

jacobian_bodyframe ¶

jacobian_bodyframe_batched ¶

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe_batched ¶

integration_kinematics ¶

gravitational_force ¶

potential_force ¶

actuator_coordinates ¶

actuator_velocities ¶

actuation_matrix ¶

actuator_efforts ¶

passive_elastic_force ¶

passive_damping_matrix ¶

passive_elastic_energy ¶

actuator_visual_layers ¶

kinetic_energy ¶

gravitational_energy ¶

elastic_energy ¶

potential_energy ¶

total_energy ¶

dynamics_terms ¶

is_planar `property` ¶

segment_length `property` ¶

tangent_eps `property` ¶

actuator_input_metadata `property` ¶

length `property` ¶

supports_articulated_tendon_routing `property` ¶

base_transform `property` ¶