Parameters¶

Actuator and passive-element parameters follow the same immutable replacement style through indexed robot delegates. See Actuation parameter updates.

System parameters are represented as typed Equinox PyTrees. Shared base classes and cross-system tendon params live in soromox.systems.params; concrete params and structures live next to their system family, for example soromox.systems.gvs.params and soromox.systems.gvs.structures.

Overview¶

Each system separates dynamic numeric values from static model structure:

Params objects store JAX arrays that may be optimized, differentiated, vmapped, and replaced without changing the PyTree layout.
Structure objects store static choices such as quadrature counts, active strain masks, GVS joint/basis/cross-section choices, symbolic expression paths, and padding sizes. Changing structure means constructing a new system and may recompile jitted methods.
Spec objects are ergonomic construction inputs for model families that need richer setup. For GVS, GVSSegment, LinkSpec, JointSpec, and StrainBasisSpec may contain both static choices and numeric values; factory methods split them into params and structure objects.

The top-level soromox.systems package re-exports the public params, structures, and specs for convenient imports. Internally, concrete containers are family-local:

System family	Dynamic params	Static structures	Construction specs
PCS	`soromox.systems.pcs.params`	`soromox.systems.pcs.structures`	-
GVS	`soromox.systems.gvs.params`	`soromox.systems.gvs.structures`	`soromox.systems.gvs.specs`
HSA	`soromox.systems.hsa.params`	`soromox.systems.hsa.structures`	-
Pendulum	`soromox.systems.pendulum.params`	-	-
Articulated	`soromox.systems.articulated.params`	-	-

The public construction pattern is:

robot = PCS(params=PCSParams(...), structure=PCSStructure(...))
robot = robot.update_params(length=new_length)
robot = robot.with_params(new_params)

Same-shape, same-dtype parameter updates preserve the JAX compilation layout. Changing the number of segments, tendons, active strains, GVS basis layout, or quadrature layout is a structural change and requires reconstruction.

For GVS specifically, GVS.from_segments(...) is the recommended constructor. It accepts user-facing segment specs, stores numeric values only in GVSParams, and stores stripped static choices in GVSStructure. This avoids stale duplicates when updating values such as Young's modulus or link length.

Naming¶

Typed params use singular physical quantity names. A field name denotes the quantity for one indexed entity; array axes describe batching. For example, length stores one length per segment or link when its shape is (num_segments,) or (num_links,).

Field	Meaning
`length`	Per-segment or per-link length
`radius`	Per-segment circular cross-section radius
`density`	Per-segment material density
`young_modulus`	Per-segment Young's modulus
`shear_modulus`	Per-segment shear modulus
`material_damping_coefficient`	PCS material damping coefficient
`damping_matrix`	Custom generalized damping matrix
`gravity`	Gravity vector
`base_pose`	Base configuration as scalar-first quaternion pose
`reference_strain`	Reference strain vector
`joint_rest_configuration`	Joint coordinates where elastic joint force is zero

World Frame, Mounting, and Gravity Defaults¶

Soft-robot parameter objects use an upright mounting and Earth gravity when base_pose or gravity is omitted. Vertical is world y for planar systems and world z for spatial systems. Gravity is always expressed in the inertial/world frame; changing the base mounting does not rotate the gravity vector.

Mounting constructor	Planar backbone	Spatial backbone	Default gravity
`horizontal`	+x	+x	negative vertical
`upright`	+y	+z	negative vertical
`hanging`	-y	-z	negative vertical

The exact default values are:

Planar upright pose: [pi / 2, 0, 0]; gravity: [0, -9.81] m/s².
Spatial upright pose: [sqrt(0.5), 0, -sqrt(0.5), 0, 0, 0, 0]; gravity: [0, 0, -9.81] m/s².
Planar poses use [theta, x, y]. Spatial poses use scalar-first Hamilton quaternions in [qw, qx, qy, qz, x, y, z] order.

Omitting both fields selects the defaults:

params = PlanarPCSParams(
    length=length,
    radius=radius,
    density=density,
    young_modulus=young_modulus,
    shear_modulus=shear_modulus,
    damping_matrix=damping_matrix,
    reference_strain=reference_strain,
)

Use the inherited mounting constructors to make another common mounting explicit. base_position translates the mounting without changing its orientation:

horizontal = PlanarPCSParams.horizontal(**planar_params)
upright = PlanarPCSParams.upright(
    **planar_params, base_position=jnp.array([0.2, 0.1])
)
hanging = PCSParams.hanging(
    **spatial_params, base_position=jnp.array([0.0, 0.0, 0.5])
)

Pass an explicit vector for custom or zero gravity. Pass an explicit base_pose through the ordinary constructor for arbitrary orientations:

zero_gravity = PCSParams(..., gravity=jnp.zeros(3))
custom = PlanarPCSParams(
    ...,
    gravity=jnp.array([1.0, -9.7]),
    base_pose=jnp.array([0.3, 0.2, 0.1]),
)

Calling replace(base_pose=None) or replace(gravity=None) restores the dimension-appropriate default. The former identity fallback is available as .horizontal(...) or by passing an explicit identity pose.

Threadlike Actuation Parameters¶

Continuum routed actuation uses ThreadlikeRouting and explicit active or passive components. The leading array axis indexes paths, so each path can have distinct offsets, slopes, and a contiguous segment span.

import jax.numpy as jnp
from soromox.actuation import (
    ThreadlikeActuator,
    ThreadlikeImpedance,
    ThreadlikeRouting,
)

active_routing = ThreadlikeRouting.linear(
    intercept=jnp.array([[0.0, 0.01, 0.0], [0.0, -0.01, 0.0]]),
    slope=jnp.array([[0.0, 0.0, 0.0], [0.0, 0.002, 0.0]]),
    start_segment_index=(0, 0),
    end_segment_index=(0, 1),
)
active_tendons = ThreadlikeActuator.tendons(active_routing)

passive_routing = ThreadlikeRouting.linear(
    intercept=jnp.array([[0.0, 0.005, 0.004], [0.0, -0.005, 0.004]]),
    slope=jnp.zeros((2, 3)),
    start_segment_index=(0, 0),
    end_segment_index=(0, 1),
)

passive_impedance = ThreadlikeImpedance(
    routing=passive_routing,
    stiffness=jnp.array([10.0, 25.0]),
    damping=jnp.array([0.1, 0.3]),
    rest_length=jnp.array([0.2, 0.21]),
)

The number of paths and their segment-span topology are structural. Changing either requires reconstructing the component and robot; numeric coefficients and mechanical parameters use immutable component updates.

Structure Naming¶

The public static objects are named PCSStructure, GVSStructure, and PlanarHSAStructure. Topology was considered, but it is too narrow for objects that also contain quadrature counts, active strain masks, basis padding, and symbolic evaluation choices. Layout was also considered, but it reads as array-shape-only. Structure is the least misleading umbrella for static model choices that affect compilation.

Example¶

import jax.numpy as jnp
from soromox.systems import PCS, PCSParams, PCSStructure

params = PCSParams.upright(
    length=jnp.array([0.1, 0.1]),
    radius=jnp.array([0.01, 0.01]),
    density=jnp.array([1000.0, 1000.0]),
    young_modulus=jnp.array([1e6, 1e6]),
    shear_modulus=jnp.array([1e5, 1e5]),
    damping_matrix=jnp.eye(12),
    reference_strain=jnp.tile(jnp.array([0.0, 0.0, 0.0, 1.0, 0.0, 0.0]), 2),
)

robot = PCS(params=params, structure=PCSStructure(num_gauss_points=5))
updated_robot = robot.update_params(length=jnp.array([0.12, 0.1]))

API Reference¶

soromox.systems.params ¶

BaseSystemParams ¶

Bases: Module


              flowchart TD
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

              

              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Base class for dynamic system parameters stored as JAX PyTrees.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate ¶

validate() -> None

Validate parameter consistency.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

BaseSoftRobotParams ¶

Bases: BaseSystemParams


              flowchart TD
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                


              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Common dynamic parameters for soft robot systems.

base_pose and gravity are optional keyword-only constructor inputs. When omitted, the robot points upright and standard Earth gravity acts in the negative vertical world direction. Planar robots use base_pose = [theta, x, y] with 2D gravity, where theta is a right-handed angle in radians about the out-of-plane z-axis. Spatial robots use base_pose = [qw, qx, qy, qz, x, y, z] with 3D gravity. Spatial quaternions are scalar-first Hamilton quaternions, normalized before transform construction, and must have nonzero finite norm. Use :meth:horizontal, :meth:upright, or :meth:hanging for explicit common mounting configurations.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate ¶

validate() -> None

Validate parameter consistency.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

BaseContinuumSoftRobotParams ¶

Bases: BaseSoftRobotParams


              flowchart TD
              soromox.systems.params.BaseContinuumSoftRobotParams[BaseContinuumSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseContinuumSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                



              click soromox.systems.params.BaseContinuumSoftRobotParams href "" "soromox.systems.params.BaseContinuumSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Shared dynamic parameters for continuum soft robots.

Field names denote one segment's physical quantity; the leading axis stores the segment batch. reference_strain contains the flattened per-segment reference strain used by PCS-style continuum models.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate ¶

validate() -> None

Validate parameter consistency.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

BaseArticulatedSoftRobotParams ¶

Bases: BaseSoftRobotParams


              flowchart TD
              soromox.systems.params.BaseArticulatedSoftRobotParams[BaseArticulatedSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseArticulatedSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                



              click soromox.systems.params.BaseArticulatedSoftRobotParams href "" "soromox.systems.params.BaseArticulatedSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Shared dynamic parameters for articulated systems.

The leading axis indexes joints/links. Stiffness, damping, and reference coordinates are dynamic arrays so optimization can update them without changing the system structure. joint_rest_configuration is the joint coordinate at which the elastic joint force is zero.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate ¶

validate() -> None

Validate parameter consistency.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

validate_planar_base_pose ¶

validate_planar_base_pose(name: str, value: Array) -> None

Validate a planar base pose.

Parameters:

Name	Type	Description	Default
`name`	`str`	Parameter name used in error messages.	required
`value`	`Array`	Planar pose array with shape `(3,)` in `[theta, x, y]` order. `theta` is a right-handed rotation angle in radians about the out-of-plane z-axis. `x` and `y` are direct translation coordinates in the parent frame.	required

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If the shape is not `(3,)` or any concrete entry is non-finite. During JAX tracing, only the static shape check is performed.

validate_quaternion_base_pose ¶

validate_quaternion_base_pose(name: str, value: Array, expected_shape: tuple[int, ...], *, min_norm: float = 1e-12) -> None

Validate a scalar-first quaternion base pose.

Parameters:

Name	Type	Description	Default
`name`	`str`	Parameter name used in error messages.	required
`value`	`Array`	Base pose array whose first four entries are a scalar-first Hamilton quaternion in `[qw, qx, qy, qz]` order. Spatial systems use shape `(7,)` with `[qw, qx, qy, qz, x, y, z]`.	required
`expected_shape`	`tuple[int, ...]`	Required full pose shape, typically `(7,)`.	required
`min_norm`	`float`	Minimum allowed Euclidean norm for the quaternion component.	`1e-12`

Concrete parameter objects are checked for finite entries and nonzero quaternion norm. During JAX tracing, only the static shape check is performed; transform helpers still avoid zero-norm division to keep traced code finite.

Raises:

Type	Description
`ValueError`	If the shape is wrong, any entry is non-finite, or the quaternion component is zero or numerically too small to normalize safely.

soromox.systems.pcs.params ¶

PCSParams ¶

Bases: BaseContinuumSoftRobotParams


              flowchart TD
              soromox.systems.pcs.params.PCSParams[PCSParams]
              soromox.systems.params.BaseContinuumSoftRobotParams[BaseContinuumSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseContinuumSoftRobotParams --> soromox.systems.pcs.params.PCSParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseContinuumSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                




              click soromox.systems.pcs.params.PCSParams href "" "soromox.systems.pcs.params.PCSParams"
              click soromox.systems.params.BaseContinuumSoftRobotParams href "" "soromox.systems.params.BaseContinuumSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for the spatial PCS model.

length, radius, material parameters, and density use a leading segment axis. Damping can be supplied either as the preferred material_damping_coefficient or as a full flattened strain damping_matrix. material_damping_coefficient is a viscosity-like modulus in Pa*s (N*s/m^2); it may be scalar or have one value per segment. The assembled matrix includes geometry and length factors, so its entries have generalized-coordinate-dependent units rather than a single Pa*s unit. base_pose is the scalar-first quaternion SE(3) base pose vector [qw, qx, qy, qz, x, y, z] used to initialize the base transform. The quaternion is normalized before use and must have nonzero finite norm. Omitting base_pose and gravity selects upright spatial mounting and negative-z Earth gravity.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

PlanarPCSParams ¶

Bases: BaseContinuumSoftRobotParams


              flowchart TD
              soromox.systems.pcs.params.PlanarPCSParams[PlanarPCSParams]
              soromox.systems.params.BaseContinuumSoftRobotParams[BaseContinuumSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseContinuumSoftRobotParams --> soromox.systems.pcs.params.PlanarPCSParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseContinuumSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                




              click soromox.systems.pcs.params.PlanarPCSParams href "" "soromox.systems.pcs.params.PlanarPCSParams"
              click soromox.systems.params.BaseContinuumSoftRobotParams href "" "soromox.systems.params.BaseContinuumSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for the planar PCS model.

The leading axis of per-segment fields indexes planar constant-strain segments. base_pose stores the planar pose [theta, x, y] with shape (3,). theta is a right-handed angle in radians about the out-of-plane z-axis, and x/y are direct translations in the parent frame. material_damping_coefficient is a viscosity-like modulus in Pa*s (N*s/m^2); it may be scalar or have one value per segment. The assembled matrix includes geometry and length factors and therefore has generalized-coordinate-dependent entry units. Omitting base_pose and gravity selects upright planar mounting and negative-y Earth gravity.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

ISupportParams ¶

Bases: PCSParams


              flowchart TD
              soromox.systems.pcs.params.ISupportParams[ISupportParams]
              soromox.systems.pcs.params.PCSParams[PCSParams]
              soromox.systems.params.BaseContinuumSoftRobotParams[BaseContinuumSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.pcs.params.PCSParams --> soromox.systems.pcs.params.ISupportParams
                                soromox.systems.params.BaseContinuumSoftRobotParams --> soromox.systems.pcs.params.PCSParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseContinuumSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                





              click soromox.systems.pcs.params.ISupportParams href "" "soromox.systems.pcs.params.ISupportParams"
              click soromox.systems.pcs.params.PCSParams href "" "soromox.systems.pcs.params.PCSParams"
              click soromox.systems.params.BaseContinuumSoftRobotParams href "" "soromox.systems.params.BaseContinuumSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for the I-SUPPORT spatial pneumatic PCS model.

The leading axis of the standard PCS body fields indexes every physical rigid or pneumatic segment in robot order. ISupport expands these fields into the internal PCS layout using ISupportStructure. Chamber fields index only pneumatic segments, in their order of appearance. Chamber azimuth is right-handed about local +X, measured from +Y toward +Z; array index j is pressure channel j. If chamber_azimuth_angles is omitted, ISupport uses 0, 120, and 240 degrees for every pneumatic segment. chamber_effective_pressure_area scales each routed chamber-path length into its pressure-conjugate equivalent-volume coordinate. It contains one value per pneumatic segment and is shared by all chambers in that segment. When omitted, it is derived as pi * (chamber_outer_radius**2 - chamber_inner_radius**2). Damping can be supplied as material_damping_coefficient or as a full damping_matrix. A custom damping_matrix is expressed in flattened pneumatic-segment strain coordinates and must be block diagonal by pneumatic segment when the model is constructed.

pcs_segment_lengths optionally stores flattened PCS segment lengths in the order defined by ISupportStructure.pcs_segment_counts. If omitted, each pneumatic segment is split into equal-length PCS segments. The entries assigned to each pneumatic segment must sum to the corresponding length entry when the model is constructed.

Segment types are defined by ISupportStructure.rigid_segment_selector.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

soromox.systems.pcs.structures ¶

PCSStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.pcs.structures.PCSStructure[PCSStructure]

              

              click soromox.systems.pcs.structures.PCSStructure href "" "soromox.systems.pcs.structures.PCSStructure"

Static PCS layout that determines JAX compilation structure.

PlanarPCSStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.pcs.structures.PlanarPCSStructure[PlanarPCSStructure]

              

              click soromox.systems.pcs.structures.PlanarPCSStructure href "" "soromox.systems.pcs.structures.PlanarPCSStructure"

Static planar PCS layout.

ISupportStructure ¶

Bases: PCSStructure


              flowchart TD
              soromox.systems.pcs.structures.ISupportStructure[ISupportStructure]
              soromox.systems.pcs.structures.PCSStructure[PCSStructure]

                              soromox.systems.pcs.structures.PCSStructure --> soromox.systems.pcs.structures.ISupportStructure
                


              click soromox.systems.pcs.structures.ISupportStructure href "" "soromox.systems.pcs.structures.ISupportStructure"
              click soromox.systems.pcs.structures.PCSStructure href "" "soromox.systems.pcs.structures.PCSStructure"

Static I-SUPPORT PCS layout.

pcs_segment_counts defines how many constant-strain PCS segments are used for each physical pneumatic segment, in pneumatic-segment order. A scalar count applies the same count to every pneumatic segment. Child lengths live in ISupportParams.pcs_segment_lengths.

rigid_segment_selector has one entry per physical segment in ISupportParams. True marks a rigid segment and False a pneumatic segment. When omitted, segment types alternate from a rigid segment at index zero. If strain_selector is provided, it is interpreted on the expanded PCS layout; rigid-segment strains are always deactivated.

soromox.systems.gvs.params ¶

GVSLinkParams ¶

Bases: BaseSystemParams


              flowchart TD
              soromox.systems.gvs.params.GVSLinkParams[GVSLinkParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSystemParams --> soromox.systems.gvs.params.GVSLinkParams
                


              click soromox.systems.gvs.params.GVSLinkParams href "" "soromox.systems.gvs.params.GVSLinkParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic per-link arrays for all GVS segments.

Every field has leading shape (num_segments,); this is not a single-link object. It stores the numeric link values without duplicating the static cross-section family stored in GVSStructure.segments. length follows the singular per-link naming convention used by the other fields. Reference strain is intentionally stored on GVSParams because it belongs to the strain basis state, not the link cross-section/material data. damping_coefficient is a viscosity-like modulus in Pa*s (N*s/m^2).

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

GVSParams ¶

Bases: BaseSoftRobotParams


              flowchart TD
              soromox.systems.gvs.params.GVSParams[GVSParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSoftRobotParams --> soromox.systems.gvs.params.GVSParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                



              click soromox.systems.gvs.params.GVSParams href "" "soromox.systems.gvs.params.GVSParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for a GVS model.

link contains per-segment link arrays. reference_strain has shape (num_segments, 6) and is kept here, rather than in GVSLinkParams, because it parameterizes the strain basis/reference configuration rather than link geometry or material properties. joint_stiffness has shape (num_segments, max_dof, max_dof) and is padded to the static GVS layout. base_pose uses scalar-first quaternion SE(3) coordinates [qw, qx, qy, qz, x, y, z] with nonzero finite quaternion norm. Omitting base_pose and gravity selects upright spatial mounting and negative-z Earth gravity.

validate_against_structure ¶

validate_against_structure(structure) -> None

Validate dynamic GVS arrays against the static padded layout.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

soromox.systems.gvs.structures ¶

GVSLinkStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.gvs.structures.GVSLinkStructure[GVSLinkStructure]

              

              click soromox.systems.gvs.structures.GVSLinkStructure href "" "soromox.systems.gvs.structures.GVSLinkStructure"

Static link choices for one GVS segment.

This stores only choices that affect compilation or dispatch. Numeric link values such as length, material constants, and cross-section dimensions live in GVSParams.link.

GVSJointStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.gvs.structures.GVSJointStructure[GVSJointStructure]

              

              click soromox.systems.gvs.structures.GVSJointStructure href "" "soromox.systems.gvs.structures.GVSJointStructure"

Static joint choices for one GVS segment.

Joint stiffness is dynamic and lives in GVSParams.joint_stiffness.

GVSStrainBasisStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.gvs.structures.GVSStrainBasisStructure[GVSStrainBasisStructure]

              

              click soromox.systems.gvs.structures.GVSStrainBasisStructure href "" "soromox.systems.gvs.structures.GVSStrainBasisStructure"

Static strain-basis choices for one GVS segment.

Reference strain is dynamic and lives in GVSParams.reference_strain.

GVSSegmentStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.gvs.structures.GVSSegmentStructure[GVSSegmentStructure]

              

              click soromox.systems.gvs.structures.GVSSegmentStructure href "" "soromox.systems.gvs.structures.GVSSegmentStructure"

Static structure for one GVS segment.

GVSStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.gvs.structures.GVSStructure[GVSStructure]

              

              click soromox.systems.gvs.structures.GVSStructure href "" "soromox.systems.gvs.structures.GVSStructure"

Static GVS segment structure and padded layout choices.

segments stores stripped static segment structures: joint families, basis families/orders/active masks, quadrature counts, and cross-section families. Dynamic numeric values live in GVSParams.

soromox.systems.hsa.params ¶

PlanarHSAParams ¶

Bases: BaseSoftRobotParams


              flowchart TD
              soromox.systems.hsa.params.PlanarHSAParams[PlanarHSAParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseSoftRobotParams --> soromox.systems.hsa.params.PlanarHSAParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                



              click soromox.systems.hsa.params.PlanarHSAParams href "" "soromox.systems.hsa.params.PlanarHSAParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for planar HSA systems.

Field names denote one segment/platform quantity; leading axes store the batched values. Arrays store length, rod geometry, reference strain components, platform/cap dimensions, end-effector offset, and optional hysteresis coefficients used by the symbolic HSA expressions. base_pose stores the planar pose [theta, x, y] with shape (3,). theta is a right-handed angle in radians about the out-of-plane z-axis, and x/y are direct translations in the parent frame. Omitting base_pose and gravity selects upright mounting and negative-y Earth gravity.

from_npz `classmethod` ¶

from_npz(path: str | Path) -> PlanarHSAParams

Load planar HSA parameters from an explicit .npz file path.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

soromox.systems.hsa.structures ¶

PlanarHSAStructure ¶

Bases: Module


              flowchart TD
              soromox.systems.hsa.structures.PlanarHSAStructure[PlanarHSAStructure]

              

              click soromox.systems.hsa.structures.PlanarHSAStructure href "" "soromox.systems.hsa.structures.PlanarHSAStructure"

Static symbolic and layout choices for planar HSA.

soromox.systems.pendulum.params ¶

PendulumParams ¶

Bases: BaseArticulatedSoftRobotParams


              flowchart TD
              soromox.systems.pendulum.params.PendulumParams[PendulumParams]
              soromox.systems.params.BaseArticulatedSoftRobotParams[BaseArticulatedSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseArticulatedSoftRobotParams --> soromox.systems.pendulum.params.PendulumParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseArticulatedSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                




              click soromox.systems.pendulum.params.PendulumParams href "" "soromox.systems.pendulum.params.PendulumParams"
              click soromox.systems.params.BaseArticulatedSoftRobotParams href "" "soromox.systems.params.BaseArticulatedSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for planar pendulum chains.

The leading axis indexes links/joints. moment_inertia and center_of_mass_length are per link, while stiffness and damping are generalized-coordinate matrices inherited from the articulated base class. base_pose stores the planar pose [theta, x, y] with shape (3,). theta is a right-handed angle in radians about the out-of-plane z-axis, and x/y are direct translations in the parent frame. Omitting base_pose and gravity selects upright mounting and negative-y Earth gravity.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

soromox.systems.articulated.params ¶

ArticulatedSoftRobotParams ¶

ArticulatedSoftRobotParams(*, joint_screw: Array, parent_to_joint_transform: Array, tip_position: Array, center_of_mass_position: Array, mass: Array, center_of_mass_inertia: Array, gravity: Array | None = None, joint_stiffness: Array, joint_damping: Array, joint_rest_configuration: Array, radius: Array, base_pose: Array | None = None)

Bases: BaseArticulatedSoftRobotParams


              flowchart TD
              soromox.systems.articulated.params.ArticulatedSoftRobotParams[ArticulatedSoftRobotParams]
              soromox.systems.params.BaseArticulatedSoftRobotParams[BaseArticulatedSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.params.BaseArticulatedSoftRobotParams --> soromox.systems.articulated.params.ArticulatedSoftRobotParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseArticulatedSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                




              click soromox.systems.articulated.params.ArticulatedSoftRobotParams href "" "soromox.systems.articulated.params.ArticulatedSoftRobotParams"
              click soromox.systems.params.BaseArticulatedSoftRobotParams href "" "soromox.systems.params.BaseArticulatedSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for spatial articulated soft robots.

Per-joint screw axes and transforms define the dynamic link geometry used by the articulated model. The number of joints is fixed by array shapes. base_pose uses scalar-first quaternion SE(3) coordinates [qw, qx, qy, qz, x, y, z] with nonzero finite quaternion norm. Omitting base_pose and gravity selects upright mounting and negative-z Earth gravity.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

McKibbenActuatedUMArmParams ¶

McKibbenActuatedUMArmParams(*, joint_screw: Array, parent_to_joint_transform: Array, tip_position: Array, center_of_mass_position: Array, mass: Array, center_of_mass_inertia: Array, gravity: Array | None = None, joint_stiffness: Array, joint_damping: Array, joint_rest_configuration: Array, radius: Array, joint_armature: Array, base_pose: Array | None = None)

Bases: ArticulatedSoftRobotParams


              flowchart TD
              soromox.systems.articulated.params.McKibbenActuatedUMArmParams[McKibbenActuatedUMArmParams]
              soromox.systems.articulated.params.ArticulatedSoftRobotParams[ArticulatedSoftRobotParams]
              soromox.systems.params.BaseArticulatedSoftRobotParams[BaseArticulatedSoftRobotParams]
              soromox.systems.params.BaseSoftRobotParams[BaseSoftRobotParams]
              soromox.systems.params.BaseSystemParams[BaseSystemParams]

                              soromox.systems.articulated.params.ArticulatedSoftRobotParams --> soromox.systems.articulated.params.McKibbenActuatedUMArmParams
                                soromox.systems.params.BaseArticulatedSoftRobotParams --> soromox.systems.articulated.params.ArticulatedSoftRobotParams
                                soromox.systems.params.BaseSoftRobotParams --> soromox.systems.params.BaseArticulatedSoftRobotParams
                                soromox.systems.params.BaseSystemParams --> soromox.systems.params.BaseSoftRobotParams
                





              click soromox.systems.articulated.params.McKibbenActuatedUMArmParams href "" "soromox.systems.articulated.params.McKibbenActuatedUMArmParams"
              click soromox.systems.articulated.params.ArticulatedSoftRobotParams href "" "soromox.systems.articulated.params.ArticulatedSoftRobotParams"
              click soromox.systems.params.BaseArticulatedSoftRobotParams href "" "soromox.systems.params.BaseArticulatedSoftRobotParams"
              click soromox.systems.params.BaseSoftRobotParams href "" "soromox.systems.params.BaseSoftRobotParams"
              click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"

Dynamic parameters for the articulated UMArm body.

These parameters contain the rigid-link dynamics, compliant-joint mechanics, visualization radii, base pose, gravity, and per-joint rotor armature. The McKibben attachment geometry and pneumatic constitutive parameters belong to :class:soromox.actuation.ArticulatedMcKibbenActuatorParams, so body and actuator parameters can be updated independently.

from_cached_npz `classmethod` ¶

from_cached_npz(path: str | Path) -> McKibbenActuatedUMArmParams

Load the articulated UMArm body from the existing cache format.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return a copy with selected fields replaced.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate params against static construction choices.

horizontal `classmethod` ¶

horizontal(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters with the backbone pointing along world +x.

upright `classmethod` ¶

upright(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world +y (planar) or +z (spatial).

hanging `classmethod` ¶

hanging(*, base_position: Array | None = None, **kwargs: Any) -> BaseSoftRobotParams

Construct parameters pointing along world -y (planar) or -z (spatial).

Parameters¶

Overview¶

Naming¶

World Frame, Mounting, and Gravity Defaults¶

Threadlike Actuation Parameters¶

Structure Naming¶

Example¶

API Reference¶

soromox.systems.params ¶

BaseSystemParams ¶

replace ¶

validate ¶

validate_against_structure ¶

BaseSoftRobotParams ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

replace ¶

validate ¶

validate_against_structure ¶

BaseContinuumSoftRobotParams ¶

replace ¶

validate ¶

validate_against_structure ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

BaseArticulatedSoftRobotParams ¶

replace ¶

validate ¶

validate_against_structure ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

validate_planar_base_pose ¶

validate_quaternion_base_pose ¶

soromox.systems.pcs.params ¶

PCSParams ¶

replace ¶

validate_against_structure ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

PlanarPCSParams ¶

replace ¶

validate_against_structure ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

ISupportParams ¶

replace ¶

validate_against_structure ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

soromox.systems.pcs.structures ¶

PCSStructure ¶

PlanarPCSStructure ¶

ISupportStructure ¶

soromox.systems.gvs.params ¶

GVSLinkParams ¶

replace ¶

validate_against_structure ¶

GVSParams ¶

validate_against_structure ¶

replace ¶

horizontal classmethod ¶

upright classmethod ¶

hanging classmethod ¶

soromox.systems.gvs.structures ¶

GVSLinkStructure ¶

GVSJointStructure ¶

GVSStrainBasisStructure ¶

GVSSegmentStructure ¶

GVSStructure ¶

soromox.systems.hsa.params ¶

PlanarHSAParams ¶

from_npz classmethod ¶

replace ¶

validate_against_structure ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

from_npz `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶

from_cached_npz `classmethod` ¶

horizontal `classmethod` ¶

upright `classmethod` ¶

hanging `classmethod` ¶