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 given the current time, state, and actuation inputs. No particular decomposition or order of the state is assumed.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time.	required
`y`	`Array`	State vector.	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.

project_state ¶

project_state(y: Array) -> Array

Project state storage onto the system state manifold.

The generic implementation is an identity operation. Systems with a constrained state representation can override this hook. It is invoked before rollout callbacks and on saved trajectories.

Parameters:

Name	Type	Description	Default
`y`	`Array`	System state with the state dimension on the trailing axis.	required

Returns:

Type	Description
`Array`	Projected state 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 | 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.

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, floating_base: bool = False, **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

Concrete parameterized models expose params and implement with_params(...) and update_params(...). A complete parameter replacement must return a new model, refresh every parameter-dependent runtime array and cache, and preserve the model's static structure. It must not mutate the original model or rely on the constructor-time :meth:precompute hook.

Attributes:

Name	Type	Description
`num_actuators`	`int`	Number of actuators.
`global_eps`	`float`	Global epsilon for numerical computations.
`floating_base`	`bool`	Whether configuration and velocity contain runtime base state.
`fixed_base_pose`	`Array \| None`	Fixed mounting pose, or `None` for floating models.
`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 `[qx, qy, qz, qw, x, y, z]`. Spatial quaternions are scalar-last 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`
`floating_base`	`bool`	Whether the base pose and velocity are runtime state. Floating robots reject `base_pose` because their initial pose must be supplied to :meth:`pack_configuration`.	`False`
`**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.

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

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.

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.

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

Optionally initialize state-independent cached quantities.

Subclasses with cached mass, stiffness, damping, basis, or quadrature data can override this method and call it during construction. Models without such caches can inherit this no-op implementation. Immutable parameter updates must instead refresh dependent caches functionally on the model returned by with_params(...); they must not call this potentially mutating constructor hook.

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.

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

Rectangular parameters use [height, width] order, matching :func:soromox.systems.components.section_properties. Elliptical parameters use [semi_major, semi_minor] order.

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

forward_kinematics_abscissa_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_coordinates,).	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_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 or link tips.

Parameters:

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

Returns:

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

jacobian_abscissa_batched ¶

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

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 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_coordinates,).	required
`qd`	`Array`	Generalized velocities of shape (num_velocities,).	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_velocities).
`Jd_ps`	`Array`	Jacobian time derivatives at all points, shape (N, n_pose_dim, num_velocities).

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

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

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

Returns:

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

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

Returns:

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

damping_matrix `abstractmethod` ¶

damping_matrix(q: Array) -> Array

Compute the damping matrix.

Parameters:

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

Returns:

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

stiffness_matrix ¶

stiffness_matrix() -> Array

Compute the stiffness matrix of the robot.

Returns:

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

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

Returns:

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

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

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

Returns:

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

potential_force ¶

potential_force(q: Array) -> Array

Compute the total conservative generalized force.

This is the sum of gravitational and elastic forces.

Parameters:

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

Returns:

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

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return the installed transmissions' work-conjugate coordinates.

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

Parameters:

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

Returns:

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

actuator_velocities ¶

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

Return the installed transmissions' coordinate velocities.

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

Parameters:

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

Returns:

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

actuation_matrix ¶

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

Return the actuator transmission matrix A(q).

A(q) is the concatenated moment-arm matrix of the installed transmissions. It maps work-conjugate actuator efforts e to generalized forces,

tau_u = A(q) @ e.

Equivalently, A(q).T is the Jacobian of the actuator coordinates with respect to the generalized coordinates.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Generalized coordinates of shape (num_coordinates,).	required
`backend`	`str \| None`	Optional execution-backend override. The base implementation supports JAX execution.	`None`

Returns:

Name	Type	Description
`A`	`Array`	Actuator transmission matrix of shape (num_velocities, num_actuators).

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.

actuation_force ¶

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

Compute the generalized actuation force.

The installed effort models first map the ordered controls u to work-conjugate actuator efforts e. The actuator transmission matrix then maps those efforts to generalized forces as

tau_u = A(q) @ e.

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`
`backend`	`str \| None`	Optional execution-backend override. The base implementation supports JAX execution.	`None`

Returns:

Name	Type	Description
`tau_u`	`Array`	Generalized actuation force of shape (num_velocities,).

Raises:

Type	Description
`ValueError`	If `u` does not have shape (num_actuators,).

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

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 `[q, v, auxiliary]` with shape `(state_size,)`.	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:

Type	Description
`Array`	State derivative `[qdot, vdot, auxiliary_dot]` with shape
`Array`	`(state_size,)`.

Common Components¶

PCS and GVS share continuum-link, cross-section, isotropic-material, and joint components. Their physical meaning, ownership, matrix shapes, and construction specifications are described in Continuum Robot Components. Practical immutable replacement and gradient-based identification examples are in Parameters, Updates, and Optimization. State layouts and pose and velocity conventions for optional moving bases are documented in Floating-base Systems.

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, including PlanarHSA	2D & 3D
GVS Systems	Geometric Variable Strain robots	3D
Execution Backends	Backend selection and optional Warp integration APIs	JAX/XLA & Warp

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
Planar HSA	2D	Motor or direct effort	Handed shearing auxetics
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

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

project_state ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

SoftRobot¶

soromox.systems.SoftRobot ¶

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

pack_configuration ¶

split_configuration ¶

pack_velocity ¶

split_velocity ¶

pack_state ¶

split_state ¶

normalize_configuration ¶

project_state ¶

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 ¶

cross_section_geometry abstractmethod ¶

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 ¶

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 ¶

kinetic_energy ¶

gravitational_energy ¶

forward_dynamics `abstractmethod` ¶

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