Systems¶

This section provides documentation for all robot system implementations in SoRoMoX.

Overview¶

SoRoMoX includes implementations for various robot systems, from classical rigid-body pendulums to advanced soft continuum robots. Each system provides:

Forward Kinematics: Computing end-effector positions and orientations
Jacobians: Computing velocity relationships and sensitivities
Dynamics: Mass matrices, Coriolis forces, and gravitational effects
Energy Methods: Kinetic, potential, and total energy computation

Base Classes¶

All robot systems in SoRoMoX inherit from a common base class hierarchy:

DynamicalSystem¶

The DynamicalSystem class is the fundamental base class for all dynamical systems in SoRoMoX. It provides the interface for forward dynamics computation and time integration.

soromox.systems.DynamicalSystem ¶

Bases: Module


              flowchart TD
              soromox.systems.DynamicalSystem[DynamicalSystem]

              

              click soromox.systems.DynamicalSystem href "" "soromox.systems.DynamicalSystem"

forward_dynamics `abstractmethod` ¶

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

Compute the forward dynamics of the system.

This method computes the state derivative yd = [qd, qdd] given the current time, state, and actuation inputs.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time.	required
`y`	`Array`	State vector containing configuration and velocity.	required
`actuation_args`	`Optional[Tuple]`	Tuple of actuation inputs, typically (u, tau_ext) where u is the control input and tau_ext is the external force/torque.	`None`

Returns:

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

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.

SoftRobot¶

The SoftRobot class extends DynamicalSystem with interfaces specific to soft robots, including methods for forward kinematics and Jacobians parameterized by arc-length or position along the robot backbone.

soromox.systems.SoftRobot ¶

SoftRobot(eps: float | None = None, base_pose: Array | None = None, **kwargs: Any)

Bases: DynamicalSystem


              flowchart TD
              soromox.systems.SoftRobot[SoftRobot]
              soromox.systems.dynamical_system.DynamicalSystem[DynamicalSystem]

                              soromox.systems.dynamical_system.DynamicalSystem --> soromox.systems.SoftRobot
                


              click soromox.systems.SoftRobot href "" "soromox.systems.SoftRobot"
              click soromox.systems.dynamical_system.DynamicalSystem href "" "soromox.systems.dynamical_system.DynamicalSystem"

Abstract base class for soft robot systems.

This class extends DynamicalSystem with interfaces specific to soft robots, including methods for forward kinematics and Jacobians parameterized by arc-length or position along the robot backbone.

All soft robot implementations (PCS, PlanarPCS, Pendulum, etc.) should inherit from this class and implement the abstract methods.

The key distinction from DynamicalSystem is that soft robots support: - Continuous parameterization along their structure (via parameter s) - Forward kinematics and Jacobians at arbitrary points along the backbone - Dynamical matrices (inertia, Coriolis, damping, etc.) in configuration space - Energy computation methods

Attributes:

Name	Type	Description
`num_dofs`	`int`	Number of degrees of freedom (configuration variables).
`num_actuators`	`int`	Number of actuators.
`global_eps`	`float`	Global epsilon for numerical computations.
`base_pose`	`Array`	Base frame pose coordinates for the robot. Planar robots use shape `(3,)` with coordinates `[theta, x, y]`, where `theta` is a right-handed angle in radians about the out-of-plane z-axis. Spatial robots use shape `(7,)` with coordinates `[qw, qx, qy, qz, x, y, z]`. Spatial quaternions are scalar-first Hamilton quaternions, normalized before use, and represent the base-frame orientation; translations are inserted directly. Configured spatial quaternions must have nonzero finite norm. When omitted, the base pose is upright: the backbone points along world +y for planar robots and world +z for spatial robots. In an explicit zero-rotation pose, the backbone is aligned with +x.
`num_gauss_points`	`int \| Array \| None`	Requested nonzero Gauss-Legendre quadrature point count. May be scalar for systems with a uniform grid or an array for systems with per-segment grids.
`num_integration_points`	`int \| Array \| None`	Stored integration point count, including any zero-weight boundary nodes used internally. May be scalar or per-segment.
`integration_points`	`Array \| None`	Quadrature nodes used for numerical integration, typically on the normalized interval [0, 1].
`integration_weights`	`Array \| None`	Quadrature weights corresponding to `integration_points`.

Initialize the SoftRobot.

Parameters:

Name	Type	Description	Default
`eps`	`float`	Optional global epsilon value for numerical computations. If not provided, defaults to 10x machine epsilon for float64.	`None`
`base_pose`	`Array \| None`	Optional base frame pose coordinates. Planar robots expect shape `(3,)` with `[theta, x, y]`. Spatial robots expect shape `(7,)` with `[qw, qx, qy, qz, x, y, z]`. Spatial quaternions are scalar-first Hamilton quaternions, normalized before use, and must have nonzero finite norm. If omitted, the upright pose is used: the backbone points along world +y for planar robots and world +z for spatial robots.	`None`
`**kwargs`	`Any`	Additional keyword arguments (unused, kept for API compatibility).	`{}`

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

segment_length `abstractmethod` `property` ¶

segment_length: Array

Per-segment backbone lengths (1D array).

is_planar `abstractmethod` `property` ¶

is_planar: bool

Return True for planar (SE(2)) robots, False for spatial (SE(3)).

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.

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.

cross_section_geometry `abstractmethod` ¶

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

Return integer cross-section tag and geometry parameters at position s.

Tag values

CrossSectionGeometry.CIRCULAR
CrossSectionGeometry.RECTANGULAR
CrossSectionGeometry.ELLIPTICAL

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

forward_kinematics_tips(q: Array) -> Array

Compute the forward kinematics at all segment or link tips.

Parameters:

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

Returns:

Name	Type	Description
`chi_tips`	`Array`	Poses at the robot tips. The shape and meaning depend on the robot type: - For 3D robots (PCS, GVS): shape (num_segments, 4, 4) - For planar robots (PlanarPCS, Pendulum): shape (num_segments, 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_tips ¶

jacobian_tips(q: Array) -> Array

Compute inertial-frame Jacobians at all segment or link tips.

Parameters:

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

Returns:

Name	Type	Description
`J_tips`	`Array`	Inertial-frame Jacobians at the robot tips, with shape (num_tips, n_pose_dim, num_dofs).

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

inertia_matrix `abstractmethod` ¶

inertia_matrix(q: Array) -> Array

Compute the generalized inertia (mass) matrix.

Parameters:

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

Returns:

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

coriolis_matrix `abstractmethod` ¶

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

Compute the Coriolis/centrifugal matrix.

Implementations are expected to use the Christoffel/energy-consistent convention associated with inertia_matrix(q): C(q, qd) @ qd is the convective force and M_dot(q, qd) - 2 * C(q, qd) is skew-symmetric. This structure is important for energy balance, passivity, model-based control, and derivative-based APIs. Optimized dynamics_terms overrides should return a Cqd vector consistent with the same inertia matrix.

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
`C`	`Array`	Coriolis matrix of shape (num_dofs, num_dofs).

damping_matrix `abstractmethod` ¶

damping_matrix(q: Array) -> Array

Compute the damping matrix.

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

stiffness_matrix ¶

stiffness_matrix() -> Array

Compute the stiffness matrix of the robot.

Returns:

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

elastic_force `abstractmethod` ¶

elastic_force(q: Array) -> Array

Compute the elastic (stiffness) force.

Parameters:

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

Returns:

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

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

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

Returns:

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

potential_force ¶

potential_force(q: Array) -> Array

Compute the total conservative generalized force.

This is the sum of gravitational and elastic forces.

Parameters:

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

Returns:

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

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return all work-conjugate actuator coordinates in control order.

actuator_velocities ¶

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

Return all actuator-coordinate velocities in control order.

actuation_matrix ¶

actuation_matrix(q: Array) -> Array

Return the concatenated transmission moment matrix.

actuator_efforts ¶

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

Map ordered user controls to ordered work-conjugate efforts.

actuation_force ¶

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

Return generalized actuation force A(q) @ effort.

passive_elastic_force ¶

passive_elastic_force(q: Array) -> Array

Return the sum of installed passive conservative forces.

passive_damping_matrix ¶

passive_damping_matrix(q: Array) -> Array

Return the sum of installed passive damping matrices.

passive_elastic_energy ¶

passive_elastic_energy(q: Array) -> Array

Return the sum of installed passive elastic energies.

actuator_visual_layers ¶

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

Return semantic active and passive actuator geometry for renderers.

kinetic_energy ¶

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

Compute the kinetic energy of the system.

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

Parameters:

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

Returns:

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

gravitational_energy ¶

gravitational_energy(q: Array) -> Array

Compute the gravitational potential energy of the system.

Parameters:

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

Returns:

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

elastic_energy ¶

elastic_energy(q: Array) -> Array

Compute the elastic potential energy stored in the system.

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

Parameters:

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

Returns:

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

potential_energy ¶

potential_energy(q: Array) -> Array

Compute the total potential energy of the system.

This is the sum of gravitational and elastic energy.

Parameters:

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

Returns:

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

total_energy ¶

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

Compute the total energy of the system.

This is the sum of kinetic and potential energy.

Parameters:

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

Returns:

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

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.

forward_dynamics ¶

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

Compute the forward dynamics of the system.

Given the current state and actuation inputs, compute the state derivative.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time (scalar).	required
`y`	`Array`	State vector containing [q, qd], shape (2 * num_dofs,).	required
`actuation_args`	`tuple \| None`	Optional tuple containing actuation inputs: - (u,): Control input u - (u, tau_ext): Control input u and external forces tau_ext	`None`

Returns:

Name	Type	Description
`yd`	`Array`	State derivative [qd, qdd], shape (2 * num_dofs,).

Common Components¶

SystemState¶

The SystemState class is a container for the robot state used throughout SoRoMoX for simulation, control, and analysis.

soromox.systems.SystemState `dataclass` ¶

SystemState(t: Array, y: Array, u: Array | None = None, control_state: Any | None = None, environment_state: Any | None = None)

Simulation snapshot of the robot and optional coupled controller/environment state.

SystemState is the public state object passed to controllers and environment models, and returned by rollout methods. The robot dynamics state is stored in y; control_state and environment_state store optional auxiliary dynamics that are coupled to the robot during simulation.

Attributes:

Name	Type	Description
`t`	`Array`	Current simulation time.
`y`	`Array`	Robot state vector, typically concatenated configuration and velocity.
`u`	`Array \| None`	Actuation input applied at the current time.
`control_state`	`Any \| None`	Additional controller state as a PyTree (e.g., integrator terms).
`environment_state`	`Any \| None`	Additional environment state as a PyTree (e.g., contact state).

System Categories¶

SoRoMoX organizes systems into the following categories:

Category	Description	Dimension
Articulated Systems	Planar and spatial articulated chains, including compliant joints and tendon actuation	2D & 3D
PCS Systems	Piecewise Constant Strain continuum robots	2D & 3D
GVS Systems	Geometric Variable Strain robots	3D
HSA Systems	Handed Shearing Auxetics robots	2D

System Summary¶

Articulated Systems¶

Planar and spatial articulated robot systems modeled as serial rigid-link chains. Pendulum provides the planar benchmark and ArticulatedSoftRobot extends the interface to spatial screw-axis chains. Both hosts accept composable actuators and passive elements.

System	Actuation	Use Case
Pendulum	Identity or composable	Planar benchmark and cable-driven mechanisms
Articulated Soft Robot	Identity or composable	Spatial rigid-link chains with compliant joints
McKibben UMArm	McKibben pressure actuation	Pneumatic rigid-soft hybrid arm

PCS Systems¶

Continuum soft robots using piecewise constant strain modeling.

System	Dimension	Actuation	Use Case
PCS	3D	Identity or composable	General 3D continuum
Planar PCS	2D	Identity or composable	General 2D continuum
I-Support	3D	Threadlike pneumatic	I-Support platform

GVS Systems¶

Continuum robots with Geometric Variable Strain (GVS) parametrization.

System	Actuation	Use Case
GVS	Identity or composable	Flexible basis functions

HSA Systems¶

Soft robots based on handed shearing auxetics.

System	Actuation	Use Case
Planar HSA	Rod actuation	Auxetic soft robots

Future Systems and Roadmap¶

The following system capabilities are on the roadmap or under consideration for future development. They are not committed release targets, but they represent areas where contributions would be especially valuable. See the Contributing Guide for details on getting started.

Capability	Motivation
`PlanarGVS`	Provide a faster planar setting for prototyping controllers and algorithms that use higher-order geometric shape parametrizations before moving to full spatial GVS models.
Floating-base functionality across all systems	Support robots whose base pose is part of the system state, rather than assuming a fixed base.
Kinematic trees, particularly for GVS	Extend beyond serial kinematic chains to support branched soft robot architectures.
Closed-chain kinematics, particularly for GVS	Enable modeling of closed-loop mechanisms and parallel soft robots.

Systems¶

Overview¶

Base Classes¶

DynamicalSystem¶

soromox.systems.DynamicalSystem ¶

forward_dynamics abstractmethod ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

SoftRobot¶

soromox.systems.SoftRobot ¶

tangent_eps property ¶

actuator_input_metadata property ¶

length property ¶

segment_length abstractmethod property ¶

is_planar abstractmethod property ¶

supports_articulated_tendon_routing property ¶

base_transform property ¶

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 ¶

cross_section_geometry abstractmethod ¶

forward_kinematics ¶

forward_kinematics_tips ¶

forward_kinematics_batched ¶

forward_kinematics_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative ¶

jacobian ¶

jacobian_tips ¶

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 ¶

inertia_matrix abstractmethod ¶

coriolis_matrix abstractmethod ¶

damping_matrix abstractmethod ¶

stiffness_matrix ¶

elastic_force abstractmethod ¶

gravitational_force ¶

potential_force ¶

actuator_coordinates ¶

actuator_velocities ¶

actuation_matrix ¶

actuator_efforts ¶

actuation_force ¶

passive_elastic_force ¶

passive_damping_matrix ¶

passive_elastic_energy ¶

actuator_visual_layers ¶

kinetic_energy ¶

gravitational_energy ¶

elastic_energy ¶

potential_energy ¶

total_energy ¶

dynamics_terms ¶

forward_dynamics ¶

Common Components¶

SystemState¶

soromox.systems.SystemState dataclass ¶

System Categories¶

System Summary¶

Articulated Systems¶

PCS Systems¶

GVS Systems¶

HSA Systems¶

Future Systems and Roadmap¶

forward_dynamics `abstractmethod` ¶

tangent_eps `property` ¶

actuator_input_metadata `property` ¶

length `property` ¶

segment_length `abstractmethod` `property` ¶

is_planar `abstractmethod` `property` ¶

supports_articulated_tendon_routing `property` ¶

base_transform `property` ¶

cross_section_geometry `abstractmethod` ¶

inertia_matrix `abstractmethod` ¶

coriolis_matrix `abstractmethod` ¶

damping_matrix `abstractmethod` ¶

elastic_force `abstractmethod` ¶

soromox.systems.SystemState `dataclass` ¶