Articulated Soft Robot¶

The ArticulatedSoftRobot system models a spatial serial chain with rigid links and optional joint stiffness and damping. It is the spatial counterpart to the planar Pendulum benchmark, while keeping the SoftRobot interface used by the rest of SoRoMoX.

Overview¶

The model uses one screw-axis joint per link. Dense matrix dynamics are exposed for controller and coordinate-transformation APIs, and forward dynamics is implemented through a dedicated articulated-body path that is validated against the dense equations of motion.

The constructor accepts the shared actuators= and passive_elements= interface. actuators=None installs identity joint-effort actuation, while an empty tuple creates an unactuated chain. Affine joint transmissions and articulated tendons use the same API as the planar Pendulum; see Joint-space actuation.

Usage¶

import jax.numpy as jnp
from soromox.systems import ArticulatedSoftRobot, ArticulatedSoftRobotParams

params = ArticulatedSoftRobotParams(
    joint_screw=jnp.array([
        [0.0, 0.0, 1.0, 0.0, 0.0, 0.0],
        [0.0, 1.0, 0.0, 0.0, 0.0, 0.0],
    ]),
    tip_position=jnp.array([
        [0.5, 0.0, 0.0],
        [0.4, 0.0, 0.0],
    ]),
    center_of_mass_position=jnp.array([
        [0.25, 0.0, 0.0],
        [0.20, 0.0, 0.0],
    ]),
    mass=jnp.array([1.0, 0.8]),
    center_of_mass_inertia=jnp.array([
        jnp.diag(jnp.array([0.02, 0.03, 0.04])),
        jnp.diag(jnp.array([0.01, 0.02, 0.03])),
    ]),
    joint_stiffness=jnp.diag(jnp.array([0.5, 0.3])),
    joint_damping=jnp.diag(jnp.array([0.02, 0.01])),
    joint_rest_configuration=jnp.zeros(2),
    parent_to_joint_transform=jnp.broadcast_to(jnp.eye(4), (2, 4, 4)),
    radius=jnp.array([0.025, 0.02]),
)

robot = ArticulatedSoftRobot(params=params)
q = jnp.array([0.2, -0.1])
qd = jnp.array([0.0, 0.0])

g_tips = robot.forward_kinematics_tips(q)
J_tip = robot.jacobians_tips(q)[-1]

M = robot.inertia_matrix(q)
C = robot.coriolis_matrix(q, qd)
G = robot.gravitational_force(q)

API Reference¶

soromox.systems.articulated.articulated_soft_robot ¶

ArticulatedSoftRobot ¶

ArticulatedSoftRobot(params: ArticulatedSoftRobotParams, *, actuators: Actuator | tuple[Actuator, ...] | None = None, passive_elements: PassiveElement | tuple[PassiveElement, ...] | None = (), **kwargs: Any)

Bases: SoftRobot


              flowchart TD
              soromox.systems.articulated.articulated_soft_robot.ArticulatedSoftRobot[ArticulatedSoftRobot]
              soromox.systems.soft_robot.SoftRobot[SoftRobot]
              soromox.systems.dynamical_system.DynamicalSystem[DynamicalSystem]

                              soromox.systems.soft_robot.SoftRobot --> soromox.systems.articulated.articulated_soft_robot.ArticulatedSoftRobot
                                soromox.systems.dynamical_system.DynamicalSystem --> soromox.systems.soft_robot.SoftRobot
                



              click soromox.systems.articulated.articulated_soft_robot.ArticulatedSoftRobot href "" "soromox.systems.articulated.articulated_soft_robot.ArticulatedSoftRobot"
              click soromox.systems.soft_robot.SoftRobot href "" "soromox.systems.soft_robot.SoftRobot"
              click soromox.systems.dynamical_system.DynamicalSystem href "" "soromox.systems.dynamical_system.DynamicalSystem"

Spatial serial chain with rigid links and optional compliant joints.

This system models an open kinematic chain whose links are rigid and whose one-degree-of-freedom joints are described by screw axes. It follows the same SoftRobot interface as continuum models, so points can be queried by arc length and the standard configuration-space dynamics methods are available.

Notes¶

The generalized coordinates q are the scalar joint coordinates. Each joint has a screw axis joint_screw[i] = [omega, v] expressed in the joint frame before the joint motion is applied. The post-joint link frame is connected to the next link through the fixed tip vector p_tip[i].

Dynamics are implemented through two complementary algorithmic paths. The public matrix-valued methods use a dense Jacobian-energy formulation: link COM Jacobians map generalized velocities to spatial twists, kinetic energy is assembled as T = 0.5 * sum_i V_i.T @ I_i @ V_i, and the dense inertia matrix follows from the quadratic form in qd. Gravity is computed as the gradient of gravitational potential energy, while the Coriolis matrix is assembled from Christoffel symbols of M(q). This path is intentionally explicit and dense because model-based controllers, coordinate transformations, and diagnostics often need M(q), C(q, qd), G(q), elastic forces, and damping as standalone arrays. Readers interested in the Lagrangian formulation and dense direct-dynamics construction should start with Hollerbach (1980) and Walker & Orin (1982).

Forward dynamics uses an articulated-body algorithm (ABA) instead of solving the dense equations at every call. ABA performs a forward velocity pass, a backward articulated-inertia pass, and a final forward acceleration pass to compute qdd directly in linear time for a serial chain. The recursion uses spatial inertias, motion transforms, and joint motion subspaces, and includes gravity, actuation, external generalized forces, joint elasticity, and joint damping. The implementation uses jax.lax.scan for the serial recurrences so JAX does not unroll Python loops as the number of links grows. Readers interested in the articulated-body recursion should start with Featherstone (1983).

Both paths represent the same equations of motion: M(q) qdd + C(q, qd) qd + G(q) + elastic_force(q) + D(q) qd = tau. Tests validate the ABA result against the dense solve. Keeping the dense Jacobian-energy assembly separate from ABA makes the controller-facing API easy to inspect while preserving a faster default forward_dynamics path.

References

Hollerbach, J. M. (1980). A Recursive Lagrangian Formulation of Manipulator Dynamics and a Comparative Study of Dynamics Formulation Complexity. IEEE Transactions on Systems, Man, and Cybernetics, SMC-10(11), 730-736.

Walker, M. W., & Orin, D. E. (1982). Efficient Dynamic Computer Simulation of Robotic Mechanisms. Journal of Dynamic Systems, Measurement, and Control, 104(3), 205-211. https://doi.org/10.1115/1.3139699

Featherstone, R. (1983). The Calculation of Robot Dynamics Using Articulated-Body Inertias. The International Journal of Robotics Research, 2(1), 13-30. https://doi.org/10.1177/027836498300200102

Attributes:

Name	Type	Description
`num_links`	`int`	Number of links and joints.
`joint_screw`	`Array`	Joint screw axis array, shape `(num_links, 6)`.
`g_parent_joint`	`Array`	Fixed transforms from previous link tip to joint frame, shape `(num_links, 4, 4)`.
`p_tip`	`Array`	Link tip vectors in post-joint link frames, shape `(num_links, 3)`.
`p_com`	`Array`	Link COM vectors in post-joint link frames, shape `(num_links, 3)`.
`m`	`Array`	Link masses, shape `(num_links,)`.
`I_com`	`Array`	Link inertia matrices about each COM, expressed in the post-joint link frame, shape `(num_links, 3, 3)`.
`g`	`Array`	Gravity acceleration vector in the base frame, shape `(3,)`.
`K`	`Array`	Joint stiffness matrix, shape `(num_links, num_links)`.
`D`	`Array`	Joint damping matrix, shape `(num_links, num_links)`.
`q_ref_k`	`Array`	Rest configuration for the joint springs, shape `(num_links,)`.
`r`	`Array`	Circular visualization radii, shape `(num_links,)`.

Initialize an articulated soft robot from typed dynamic parameters.

is_planar `property` ¶

is_planar: bool

Return False because this is a spatial SE(3) system.

supports_articulated_tendon_routing `property` ¶

supports_articulated_tendon_routing: bool

The generalized coordinates form a serial articulated joint chain.

segment_length `property` ¶

segment_length: Array

Per-link centerline lengths.

L_cum `property` ¶

L_cum: Array

Cumulative link lengths [0, L_0, ..., sum_i L_i].

total_length `property` ¶

total_length: Array

Alias for length used by other articulated systems.

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

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.

classify_segment ¶

classify_segment(s: Array) -> tuple[Array, Array]

Determine which link contains an arc-length position.

Parameters:

Name	Type	Description	Default
`s`	`Array`	Arc-length position along the serial chain.	required

Returns:

Type	Description
`Array`	Tuple `(link_idx, s_local)` with the zero-based link index and local
`Array`	arc length within that link.

cross_section_geometry ¶

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

Return circular cross-section metadata for visualization.

forward_kinematics_joints ¶

forward_kinematics_joints(q: Array) -> Array

Compute SE(3) frames at all joint origins.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Joint frames, shape `(num_links, 4, 4)`.

forward_kinematics_coms ¶

forward_kinematics_coms(q: Array) -> Array

Compute SE(3) frames at all link centers of mass.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	COM frames, shape `(num_links, 4, 4)`.

forward_kinematics_tips ¶

forward_kinematics_tips(q: Array) -> Array

Compute SE(3) frames at all link tips.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Tip frames, shape `(num_links, 4, 4)`.

jacobian_coms ¶

jacobian_coms(q: Array) -> Array

Compute spatial Jacobians at all link COMs.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	COM Jacobians, shape `(num_links, 6, num_links)`.

jacobian_tips ¶

jacobian_tips(q: Array) -> Array

Compute spatial Jacobians at all link tips.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Tip Jacobians, shape `(num_links, 6, num_links)`.

jacobian_joints ¶

jacobian_joints(q: Array) -> Array

Compute spatial Jacobians at all joint origins.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Joint-origin Jacobians, shape `(num_links, 6, num_links)`.

jacobian_and_time_derivatives_tips ¶

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

Compute tip Jacobians and their time derivatives.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required
`qd`	`Array`	Joint velocities, shape `(num_links,)`.	required

Returns:

Type	Description
`tuple[Array, Array]`	Tuple `(J, Jd)`, both with shape `(num_links, 6, num_links)`.

inertia_matrix ¶

inertia_matrix(q: Array) -> Array

Compute the dense generalized inertia matrix.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Inertia matrix, shape `(num_links, num_links)`.

coriolis_matrix ¶

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

Compute a Christoffel-consistent dense Coriolis matrix.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required
`qd`	`Array`	Joint velocities, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Coriolis matrix, shape `(num_links, num_links)`.

stiffness_matrix ¶

stiffness_matrix() -> Array

Return the linear joint stiffness matrix.

Returns:

Type	Description
`Array`	Stiffness matrix, shape `(num_links, num_links)`.

elastic_force ¶

elastic_force(q: Array) -> Array

Compute generalized elastic joint forces.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Elastic force vector, shape `(num_links,)`.

damping_matrix ¶

damping_matrix(q: Array) -> Array

Return the viscous joint damping matrix.

Parameters:

Name	Type	Description	Default
`q`	`Array`	Joint coordinates, shape `(num_links,)`.	required

Returns:

Type	Description
`Array`	Damping matrix, shape `(num_links, num_links)`.

forward_dynamics ¶

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

Compute state-space forward dynamics.

Parameters:

Name	Type	Description	Default
`t`	`Array`	Current time, shape `()`. The model is autonomous, so this value is unused.	required
`y`	`Array`	State vector `[q, qd]`, shape `(2 * num_links,)`.	required
`actuation_args`	`tuple \| None`	Optional actuation tuple: - `None`: zero actuation and zero external force. - `(u,)`: joint inputs only. - `(u, tau_ext)`: joint inputs and external generalized forces.	`None`

Returns:

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

Raises:

Type	Description
`ValueError`	If `actuation_args` has an unsupported length.

with_params ¶

with_params(params: ArticulatedSoftRobotParams) -> ArticulatedSoftRobot

Return an updated copy with a full typed parameter object.

update_params ¶

update_params(**updates: Array) -> ArticulatedSoftRobot

Return an updated copy with selected typed parameter fields replaced.

rollout_to ¶

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

Roll out the system dynamics in open loop using Diffrax.

Parameters:

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

Returns:

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

rollout_closed_loop_to ¶

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

Roll out the system dynamics in closed loop using Diffrax.

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

Parameters:

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

Returns:

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

rollout_discrete_closed_loop_to ¶

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

Roll out the system in discrete-time closed loop.

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

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

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

Parameters:

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

Returns:

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

precompute ¶

precompute() -> None

Optional hook for refreshing state-independent cached quantities.

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

with_actuator_params ¶

with_actuator_params(index: int, params) -> SoftRobot

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

update_actuator_params ¶

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

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

with_passive_element_params ¶

with_passive_element_params(index: int, params) -> SoftRobot

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

update_passive_element_params ¶

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

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

forward_kinematics ¶

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

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

Parameters:

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

Returns:

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

forward_kinematics_batched ¶

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

Compute the forward kinematics at multiple points along the robot.

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

Parameters:

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

Returns:

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

forward_kinematics_arc_length_derivative ¶

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

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

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

forward_kinematics_and_arc_length_derivative ¶

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

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

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

jacobian ¶

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

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

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

Parameters:

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

Returns:

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

jacobian_batched ¶

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

Compute the Jacobian at multiple points along the robot.

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

Parameters:

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

Returns:

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

jacobian_arc_length_derivative ¶

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

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

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

jacobian_and_arc_length_derivative ¶

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

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

Returns:

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

jacobian_and_time_derivative ¶

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

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

Parameters:

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

Returns:

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

jacobian_and_time_derivative_batched ¶

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

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

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

Parameters:

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

Returns:

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

jacobian_bodyframe ¶

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

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

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

jacobian_bodyframe_batched ¶

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

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

jacobian_and_time_derivative_bodyframe ¶

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

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

The default differentiates jacobian_bodyframe with respect to the generalized coordinates.

jacobian_and_time_derivative_bodyframe_batched ¶

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

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

integration_kinematics ¶

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

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

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

Returns:

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

gravitational_force ¶

gravitational_force(q: Array) -> Array

Compute the gravitational force.

Parameters:

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

Returns:

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

potential_force ¶

potential_force(q: Array) -> Array

Compute the total conservative generalized force.

This is the sum of gravitational and elastic forces.

Parameters:

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

Returns:

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

actuator_coordinates ¶

actuator_coordinates(q: Array) -> Array

Return all work-conjugate actuator coordinates in control order.

actuator_velocities ¶

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

Return all actuator-coordinate velocities in control order.

actuation_matrix ¶

actuation_matrix(q: Array) -> Array

Return the concatenated transmission moment matrix.

actuator_efforts ¶

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

Map ordered user controls to ordered work-conjugate efforts.

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.

Articulated Soft Robot¶

Overview¶

Usage¶

API Reference¶

soromox.systems.articulated.articulated_soft_robot ¶

ArticulatedSoftRobot ¶

Notes¶

is_planar property ¶

supports_articulated_tendon_routing property ¶

segment_length property ¶

L_cum property ¶

total_length property ¶

tangent_eps property ¶

actuator_input_metadata property ¶

length property ¶

base_transform property ¶

classify_segment ¶

cross_section_geometry ¶

forward_kinematics_joints ¶

forward_kinematics_coms ¶

forward_kinematics_tips ¶

jacobian_coms ¶

jacobian_tips ¶

jacobian_joints ¶

jacobian_and_time_derivatives_tips ¶

inertia_matrix ¶

coriolis_matrix ¶

stiffness_matrix ¶

elastic_force ¶

damping_matrix ¶

forward_dynamics ¶

with_params ¶

update_params ¶

rollout_to ¶

rollout_closed_loop_to ¶

rollout_discrete_closed_loop_to ¶

precompute ¶

with_actuator_params ¶

update_actuator_params ¶

with_passive_element_params ¶

update_passive_element_params ¶

forward_kinematics ¶

forward_kinematics_batched ¶

forward_kinematics_arc_length_derivative ¶

forward_kinematics_and_arc_length_derivative ¶

jacobian ¶

jacobian_batched ¶

jacobian_arc_length_derivative ¶

jacobian_and_arc_length_derivative ¶

jacobian_and_time_derivative ¶

jacobian_and_time_derivative_batched ¶

jacobian_bodyframe ¶

jacobian_bodyframe_batched ¶

jacobian_and_time_derivative_bodyframe ¶

jacobian_and_time_derivative_bodyframe_batched ¶

integration_kinematics ¶

gravitational_force ¶

potential_force ¶

actuator_coordinates ¶

actuator_velocities ¶

actuation_matrix ¶

actuator_efforts ¶

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 ¶

is_planar `property` ¶

supports_articulated_tendon_routing `property` ¶

segment_length `property` ¶

L_cum `property` ¶

total_length `property` ¶

tangent_eps `property` ¶

actuator_input_metadata `property` ¶

length `property` ¶

base_transform `property` ¶