Continuum Robot Components¶

PCS and GVS use the same public vocabulary for continuum links, cross-sections, isotropic materials, and joints. This page describes the physical meaning and ownership of those shared components. For construction, immutable replacement, and gradient-based identification workflows, see Parameters and Optimization.

Model composition¶

Continuum-system parameters use shallow composition:

PCSParams / PlanarPCSParams
└── link: ContinuumLinkParams
    └── cross_section: CrossSectionParams

GVSParams
├── link: ContinuumLinkParams
│   └── cross_section: CrossSectionParams
└── joint: JointParams

The hierarchy expresses physical ownership rather than a different material model for every system. A link owns its geometry, reference strain, mass properties, stiffness, and damping. A GVS joint separately owns joint stiffness and damping. System-level parameters own the base pose and gravity.

Cross-sections¶

CrossSectionParams.coefficients is a two-dimensional array with one row per link. The static system structure determines how each row is interpreted:

a scalar dimension defines a constant profile;
LinearProfile(base, tip) defines a base-to-tip linear profile;
rows are zero-padded when different GVS links require different numbers of coefficients.

The supported solid cross-sections are circular, rectangular, and elliptical. CrossSectionGeometry identifies the family, while shared geometry utilities calculate area and second moments of area. Geometry dimensions are finite and strictly positive. Shared evaluators and robot.cross_section_geometry(...) use [height, width] for rectangular sections and [semi_major, semi_minor] for elliptical sections.

LinkSpec provides the ergonomic construction interface:

from soromox.systems import LinearProfile, LinkSpec

circular = LinkSpec.circular(
    length=0.2,
    radius=0.012,
    density=1000.0,
    young_modulus=1.0e6,
    shear_modulus=3.4e5,
    material_damping_coefficient=1.0e4,
    reference_strain=[0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
)

tapered_rectangle = LinkSpec.rectangular(
    length=0.25,
    height=LinearProfile(base=0.03, tip=0.02),
    width=0.025,
    density=1000.0,
    young_modulus=1.0e6,
    shear_modulus=3.4e5,
    material_damping_coefficient=1.0e4,
    reference_strain=[0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
)

PCS currently accepts constant circular links. GVS accepts constant or linear circular, rectangular, and elliptical cross-sections.

Continuum links¶

ContinuumLinkParams stores the canonical numeric values used at runtime:

Field	Shape	Meaning
`length`	`(N,)`	Link backbone lengths
`density`	`(N,)`	Volumetric mass densities
`reference_strain`	`(N, strain_dimension)`	Stress-free strain fields
`cross_section.coefficients`	`(N, max_coefficients)`	Packed geometry profiles
`stiffness`	`(N, generalized_dimension, generalized_dimension)`	Generalized link stiffness
`damping`	same as `stiffness`	Generalized link damping

Stiffness and damping are finite symmetric matrices. They are not required to be diagonal or positive definite, which permits anisotropic, coupled, fitted, and learned constitutive models. Link lengths and densities must be finite and strictly positive; reference strains must be finite.

The generalized dimension depends on the system:

System	Canonical link matrix shape
Spatial PCS	`(N, 6, 6)`
PlanarPCS	`(N, 3, 3)`
GVS	`(N, max_dof, max_dof)`

GVS matrices are zero-padded beyond each link's active basis coordinates.

Isotropic material model¶

Young's modulus, either shear modulus or Poisson's ratio, and optional material damping are useful construction and identification variables, but they are not duplicated in the runtime robot parameters. Instead, callers keep an IsotropicMaterialParams PyTree:

from soromox.systems import IsotropicMaterialParams

young = 1.0e6
material = IsotropicMaterialParams(
    young_modulus=young,
    poisson_ratio=0.45,
)

Each active field may be scalar or contain one value per link. Scalar values are broadcast when the material is applied. Exactly one of shear_modulus and poisson_ratio is required. Young's and shear moduli must be finite and strictly positive, Poisson's ratio must lie in (-1, 0.5), and material damping must be finite and nonnegative when supplied. Omitting material damping produces a zero damping matrix.

The optional-field pattern is structural: shear-modulus, Poisson-ratio, damped, and undamped materials have different PyTree structures. JIT compilation therefore specializes on these choices, while the active arrays remain normal differentiable leaves.

Geometry, link length, strain basis, rotational scaling, and quadrature are projected into unit-response operators. Material matrices are then evaluated as

\[ K_i = E_i K_{i,E} + G_i K_{i,G}, \qquad D_i = \eta_i D_{i,\eta}\quad\text{or}\quad 0, \]

For the Young/Poisson parameterization, \(G_i = E_i / (2 (1 + \nu_i))\) is evaluated inside this mapping so gradients propagate through both \(E_i\) and \(\nu_i\).

Equivalently, the unit operators represent the discretized integrals

\[ K_i = \int B_i(s)^\mathsf{T} C_i(s) B_i(s)\,\mathrm{d}s, \qquad D_i = \int B_i(s)^\mathsf{T} V_i(s) B_i(s)\,\mathrm{d}s. \]

link_matrices_from_material evaluates the mapping without modifying the robot. with_isotropic_material returns a robot containing the resulting canonical matrices. It does not store the material PyTree.

Geometry updates refresh the unit-response operators but leave explicitly stored matrices unchanged. Reapply with_isotropic_material when matrices should follow updated material or geometry values. This prevents geometry updates from silently overwriting an explicitly supplied constitutive model.

Joints¶

GVS segments may start with a fixed, revolute, prismatic, helical, cylindrical, planar, spherical, or free joint. JointSpec accepts stiffness and damping in active joint coordinates. Omitted values create zero matrices.

At runtime, JointParams stores both matrices with the same GVS padding as the link matrices:

import jax.numpy as jnp

from soromox.systems import JointSpec

joint = JointSpec.revolute(
    axis="z",
    stiffness=jnp.array([[0.3]]),
    damping=jnp.array([[0.02]]),
)

The GVS global matrices interleave joint and link contributions before projection into active coordinates. PCS has no separate joint component.

Construction specs, params, and structure¶

The three object categories have different lifetimes:

Category	Purpose	Typical examples
Specs	Convenient user input during construction	`LinkSpec`, `JointSpec`, `GVSSegment`, `StrainBasisSpec`
Params	Dynamic numeric JAX PyTrees	`ContinuumLinkParams`, `JointParams`, `PCSParams`, `GVSParams`
Structure	Static choices affecting layout or compilation	`PCSStructure`, `GVSStructure`

Specs may contain either isotropic material values or explicit generalized matrices. Construction resolves them to one canonical runtime representation. Changing numeric params with the same layout supports JAX transformations; changing segment count, basis order, active strains, or padding requires reconstruction with a new structure.

API reference¶

soromox.systems.components ¶

Reusable link, joint, cross-section, and material components.

CrossSectionGeometry ¶

Bases: IntEnum


              flowchart TD
              soromox.systems.components.CrossSectionGeometry[CrossSectionGeometry]

              

              click soromox.systems.components.CrossSectionGeometry href "" "soromox.systems.components.CrossSectionGeometry"

Supported solid cross-section families.

CrossSectionParams ¶

Bases: BaseSystemParams


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

                              soromox.systems.params.BaseSystemParams --> soromox.systems.components.CrossSectionParams
                


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

Batched dynamic cross-section coefficients.

Static geometry, profile kinds, and coefficient names live in each system's structure. Rows are zero-padded to the largest coefficient count in the model.

Attributes:

Name	Type	Description
`coefficients`	`Array`	Cross-section coefficients with shape `(num_links, max_num_coefficients)`. Each row contains the coefficients required by that link's static geometry and profile declarations, followed by zero padding when necessary.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return an immutable copy with selected fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Parameter field names and their replacement values. Nested parameter components should first be replaced with their own `replace` method, then supplied as a top-level field.	`{}`

Returns:

Type	Description
`BaseSystemParams`	A validated parameter PyTree of the same concrete class.

Raises:

Type	Description
`KeyError`	If any update names an unknown parameter field.
`TypeError`	If a replacement cannot be inserted into the PyTree.
`ValueError`	If validation of the resulting parameters fails.

validate ¶

validate() -> None

Validate both parameter structure and eager numeric values.

validate_for_update ¶

validate_for_update() -> None

Validate values when concrete and structure when dynamically traced.

validate_structure_compatibility ¶

validate_structure_compatibility(structure: Any) -> None

Validate statically observable compatibility with a model structure.

validate_value_compatibility ¶

validate_value_compatibility(structure: Any) -> None

Validate eager value compatibility with a model structure.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate parameters fully against static construction choices.

Parameters:

Name	Type	Description	Default
`structure`	`Any`	System-specific static structure to validate against.	required

Returns:

Type	Description
`None`	`None` after successful validation.

Raises:

Type	Description
`ValueError`	If intrinsic or structure-dependent validation fails.

validate_for_update_against_structure ¶

validate_for_update_against_structure(structure: Any) -> None

Validate concrete values and traced structure against a model.

validate_structure ¶

validate_structure() -> None

Validate the batched cross-section coefficient array shape.

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If `coefficients` is not a nonempty two-dimensional array.

validate_values ¶

validate_values() -> None

Validate eager cross-section coefficient values.

LinearProfile `dataclass` ¶

LinearProfile(base: float, tip: float)

A scalar cross-section dimension varying linearly along a link.

Attributes:

Name	Type	Description
`base`	`float`	Dimension at normalized arc length zero.
`tip`	`float`	Dimension at normalized arc length one.

__post_init__ ¶

__post_init__() -> None

Validate the endpoint dimensions.

Raises:

Type	Description
`ValueError`	If either endpoint is non-finite or not strictly positive.

JointParams ¶

Bases: BaseSystemParams


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

                              soromox.systems.params.BaseSystemParams --> soromox.systems.components.JointParams
                


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

Canonical batched generalized joint matrices.

Attributes:

Name	Type	Description
`stiffness`	`Array`	Padded joint stiffness matrices with shape `(num_joints, generalized_dimension, generalized_dimension)`.
`damping`	`Array`	Padded joint damping matrices with the same shape as `stiffness`.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return an immutable copy with selected fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Parameter field names and their replacement values. Nested parameter components should first be replaced with their own `replace` method, then supplied as a top-level field.	`{}`

Returns:

Type	Description
`BaseSystemParams`	A validated parameter PyTree of the same concrete class.

Raises:

Type	Description
`KeyError`	If any update names an unknown parameter field.
`TypeError`	If a replacement cannot be inserted into the PyTree.
`ValueError`	If validation of the resulting parameters fails.

validate ¶

validate() -> None

Validate both parameter structure and eager numeric values.

validate_for_update ¶

validate_for_update() -> None

Validate values when concrete and structure when dynamically traced.

validate_structure_compatibility ¶

validate_structure_compatibility(structure: Any) -> None

Validate statically observable compatibility with a model structure.

validate_value_compatibility ¶

validate_value_compatibility(structure: Any) -> None

Validate eager value compatibility with a model structure.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate parameters fully against static construction choices.

Parameters:

Name	Type	Description	Default
`structure`	`Any`	System-specific static structure to validate against.	required

Returns:

Type	Description
`None`	`None` after successful validation.

Raises:

Type	Description
`ValueError`	If intrinsic or structure-dependent validation fails.

validate_for_update_against_structure ¶

validate_for_update_against_structure(structure: Any) -> None

Validate concrete values and traced structure against a model.

validate_structure ¶

validate_structure() -> None

Validate joint matrix shapes.

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If stiffness is not a batch of square matrices or damping has a different shape.

validate_values ¶

validate_values() -> None

Validate eager joint matrix finiteness and symmetry.

JointSpec `dataclass` ¶

JointSpec(type: JointType, axis: Literal['x', 'y', 'z'] = 'x', plane: Literal['xy', 'yz', 'xz'] = 'xy', pitch: float = 0.0, stiffness: Array | list = list(), damping: Array | list = list())

Kinematic and generalized viscoelastic specification of one joint.

Attributes:

Name	Type	Description
`type`	`JointType`	Joint family name.
`axis`	`Literal['x', 'y', 'z']`	Axis used by revolute, prismatic, helical, and cylindrical joints.
`plane`	`Literal['xy', 'yz', 'xz']`	Motion plane used by planar joints.
`pitch`	`float`	Translation per radian for a helical joint.
`stiffness`	`Array \| list`	Stiffness matrix in active joint coordinates. An empty value requests a zero matrix.
`damping`	`Array \| list`	Damping matrix in active joint coordinates. An empty value requests a zero matrix.

fixed `classmethod` ¶

fixed() -> JointSpec

Create a zero-degree-of-freedom fixed joint.

Returns:

Type	Description
`JointSpec`	A fixed-joint specification with zero stiffness and damping.

revolute `classmethod` ¶

revolute(axis: Literal['x', 'y', 'z'] = 'x', stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a one-degree-of-freedom revolute joint.

Parameters:

Name	Type	Description	Default
`axis`	`Literal['x', 'y', 'z']`	Rotation axis in the joint material frame.	`'x'`
`stiffness`	`Array \| list \| None`	Optional `(1, 1)` stiffness matrix in active coordinates. `None` produces zero stiffness.	`None`
`damping`	`Array \| list \| None`	Optional `(1, 1)` damping matrix in active coordinates. `None` produces zero damping.	`None`

Returns:

Type	Description
`JointSpec`	A revolute-joint specification.

Raises:

Type	Description
`ValueError`	If the axis is invalid or a matrix has an invalid shape, non-finite entries, or asymmetry.

prismatic `classmethod` ¶

prismatic(axis: Literal['x', 'y', 'z'] = 'x', stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a one-degree-of-freedom prismatic joint.

Parameters:

Name	Type	Description	Default
`axis`	`Literal['x', 'y', 'z']`	Translation axis in the joint material frame.	`'x'`
`stiffness`	`Array \| list \| None`	Optional `(1, 1)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(1, 1)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A prismatic-joint specification.

Raises:

Type	Description
`ValueError`	If the axis or either matrix is invalid.

helical `classmethod` ¶

helical(axis: Literal['x', 'y', 'z'] = 'x', pitch: float = 0.0, stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a one-degree-of-freedom helical joint.

Parameters:

Name	Type	Description	Default
`axis`	`Literal['x', 'y', 'z']`	Coupled rotation and translation axis.	`'x'`
`pitch`	`float`	Translation per radian of rotation.	`0.0`
`stiffness`	`Array \| list \| None`	Optional `(1, 1)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(1, 1)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A helical-joint specification.

Raises:

Type	Description
`ValueError`	If the axis or either matrix is invalid.

cylindrical `classmethod` ¶

cylindrical(axis: Literal['x', 'y', 'z'] = 'x', stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a cylindrical joint with rotation and translation.

Parameters:

Name	Type	Description	Default
`axis`	`Literal['x', 'y', 'z']`	Shared rotation and translation axis.	`'x'`
`stiffness`	`Array \| list \| None`	Optional `(2, 2)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(2, 2)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A two-degree-of-freedom cylindrical-joint specification.

Raises:

Type	Description
`ValueError`	If the axis or either matrix is invalid.

planar `classmethod` ¶

planar(plane: Literal['xy', 'yz', 'xz'] = 'xy', stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a three-degree-of-freedom planar joint.

Parameters:

Name	Type	Description	Default
`plane`	`Literal['xy', 'yz', 'xz']`	Plane in which the joint translates and rotates.	`'xy'`
`stiffness`	`Array \| list \| None`	Optional `(3, 3)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(3, 3)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A planar-joint specification.

Raises:

Type	Description
`ValueError`	If the plane or either matrix is invalid.

spherical `classmethod` ¶

spherical(stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a three-degree-of-freedom spherical joint.

Parameters:

Name	Type	Description	Default
`stiffness`	`Array \| list \| None`	Optional `(3, 3)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(3, 3)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A spherical-joint specification.

Raises:

Type	Description
`ValueError`	If either matrix is invalid.

free `classmethod` ¶

free(stiffness: Array | list | None = None, damping: Array | list | None = None) -> JointSpec

Create a free six-degree-of-freedom spatial joint.

Parameters:

Name	Type	Description	Default
`stiffness`	`Array \| list \| None`	Optional `(6, 6)` active-coordinate stiffness matrix.	`None`
`damping`	`Array \| list \| None`	Optional `(6, 6)` active-coordinate damping matrix.	`None`

Returns:

Type	Description
`JointSpec`	A free-joint specification.

Raises:

Type	Description
`ValueError`	If either matrix is invalid.

ContinuumLinkParams ¶

Bases: BaseSystemParams


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

                              soromox.systems.params.BaseSystemParams --> soromox.systems.components.ContinuumLinkParams
                


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

Canonical batched dynamic parameters for continuum links.

Attributes:

Name	Type	Description
`length`	`Array`	Link lengths with shape `(num_links,)`.
`density`	`Array`	Volumetric mass densities with shape `(num_links,)`.
`reference_strain`	`Array`	Reference strain rows with shape `(num_links, strain_dimension)`.
`cross_section`	`CrossSectionParams`	Batched cross-section coefficients shared by all continuum-system families.
`stiffness`	`Array`	Canonical generalized link stiffness matrices with shape `(num_links, generalized_dimension, generalized_dimension)`.
`damping`	`Array`	Canonical generalized link damping matrices with the same shape as `stiffness`.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return an immutable copy with selected fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Parameter field names and their replacement values. Nested parameter components should first be replaced with their own `replace` method, then supplied as a top-level field.	`{}`

Returns:

Type	Description
`BaseSystemParams`	A validated parameter PyTree of the same concrete class.

Raises:

Type	Description
`KeyError`	If any update names an unknown parameter field.
`TypeError`	If a replacement cannot be inserted into the PyTree.
`ValueError`	If validation of the resulting parameters fails.

validate ¶

validate() -> None

Validate both parameter structure and eager numeric values.

validate_for_update ¶

validate_for_update() -> None

Validate values when concrete and structure when dynamically traced.

validate_structure_compatibility ¶

validate_structure_compatibility(structure: Any) -> None

Validate statically observable compatibility with a model structure.

validate_value_compatibility ¶

validate_value_compatibility(structure: Any) -> None

Validate eager value compatibility with a model structure.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate parameters fully against static construction choices.

Parameters:

Name	Type	Description	Default
`structure`	`Any`	System-specific static structure to validate against.	required

Returns:

Type	Description
`None`	`None` after successful validation.

Raises:

Type	Description
`ValueError`	If intrinsic or structure-dependent validation fails.

validate_for_update_against_structure ¶

validate_for_update_against_structure(structure: Any) -> None

Validate concrete values and traced structure against a model.

validate_structure ¶

validate_structure() -> None

Validate link-array and canonical matrix shapes.

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If link fields disagree on `num_links`, reference strain or coefficient arrays are not two-dimensional, or canonical matrices are not equally shaped square batches.

validate_values ¶

validate_values() -> None

Validate eager link values and canonical matrix properties.

LinkSpec `dataclass` ¶

LinkSpec(cross_section_geometry: CrossSectionGeometry, length: float, density: float, reference_strain: Array | list[float], cross_section_coefficients: tuple[float, ...], cross_section_profile_types: tuple[ProfileType, ...], cross_section_profile_parameter_counts: tuple[int, ...], cross_section_coefficient_names: tuple[str, ...], young_modulus: float | None = None, shear_modulus: float | None = None, poisson_ratio: float | None = None, material_damping_coefficient: float | None = None, stiffness: Array | None = None, damping: Array | None = None)

Construction specification for one continuum link.

Prefer the geometry-specific :meth:circular, :meth:rectangular, and :meth:elliptical factories. Stiffness must be described by an explicit stiffness matrix or by young_modulus together with exactly one of shear_modulus and poisson_ratio. Damping may use material_damping_coefficient or an explicit damping matrix; omitting both disables damping.

Attributes:

Name	Type	Description
`cross_section_geometry`	`CrossSectionGeometry`	Static cross-section family.
`length`	`float`	Link length.
`density`	`float`	Volumetric mass density.
`reference_strain`	`Array \| list[float]`	Reference strain vector for this link.
`cross_section_coefficients`	`tuple[float, ...]`	Packed constant or linear profile coefficients.
`cross_section_profile_types`	`tuple[ProfileType, ...]`	Profile kind for each geometric dimension.
`cross_section_profile_parameter_counts`	`tuple[int, ...]`	Number of packed coefficients occupied by each geometric dimension.
`cross_section_coefficient_names`	`tuple[str, ...]`	Human-readable names corresponding to the packed coefficients.
`young_modulus`	`float \| None`	Optional isotropic Young's modulus.
`shear_modulus`	`float \| None`	Optional isotropic shear modulus.
`poisson_ratio`	`float \| None`	Optional isotropic Poisson's ratio.
`material_damping_coefficient`	`float \| None`	Optional isotropic material damping value. Omitting it together with `damping` disables damping.
`stiffness`	`Array \| None`	Optional explicit generalized stiffness matrix.
`damping`	`Array \| None`	Optional explicit generalized damping matrix.

circular `classmethod` ¶

circular(*, length: float, radius: float | LinearProfile, density: float, reference_strain: Array | list[float], young_modulus: float | None = None, shear_modulus: float | None = None, poisson_ratio: float | None = None, material_damping_coefficient: float | None = None, stiffness: Array | None = None, damping: Array | None = None) -> LinkSpec

Create a solid circular-link specification.

Parameters:

Name	Type	Description	Default
`length`	`float`	Link length.	required
`radius`	`float \| LinearProfile`	Constant radius or a base-to-tip linear radius profile.	required
`density`	`float`	Volumetric mass density.	required
`reference_strain`	`Array \| list[float]`	Reference strain vector. Spatial systems use six entries and planar PCS uses three entries.	required
`young_modulus`	`float \| None`	Young's modulus used with `shear_modulus` to build generalized stiffness. Mutually exclusive with `stiffness`.	`None`
`shear_modulus`	`float \| None`	Shear modulus used with `young_modulus`. Mutually exclusive with `poisson_ratio`.	`None`
`poisson_ratio`	`float \| None`	Poisson's ratio used with `young_modulus` to derive the shear modulus. Mutually exclusive with `shear_modulus`.	`None`
`material_damping_coefficient`	`float \| None`	Isotropic damping value used to build generalized damping. Mutually exclusive with `damping`. If both are omitted, damping is disabled.	`None`
`stiffness`	`Array \| None`	Explicit generalized stiffness matrix.	`None`
`damping`	`Array \| None`	Explicit generalized damping matrix.	`None`

Returns:

Type	Description
`LinkSpec`	A circular :class:`LinkSpec` ready for PCS or GVS construction.

Raises:

Type	Description
`ValueError`	If material and explicit sources are missing, incomplete, or supplied together, or if an explicit matrix is not finite, square, and symmetric, or if a physical dimension, density, length, or material scalar is outside its valid domain.

rectangular `classmethod` ¶

rectangular(*, length: float, height: float | LinearProfile, width: float | LinearProfile, density: float, reference_strain: Array | list[float], young_modulus: float | None = None, shear_modulus: float | None = None, poisson_ratio: float | None = None, material_damping_coefficient: float | None = None, stiffness: Array | None = None, damping: Array | None = None) -> LinkSpec

Create a solid rectangular-link specification.

Parameters:

Name	Type	Description	Default
`length`	`float`	Link length.	required
`height`	`float \| LinearProfile`	Constant height or base-to-tip linear height profile.	required
`width`	`float \| LinearProfile`	Constant width or base-to-tip linear width profile.	required
`density`	`float`	Volumetric mass density.	required
`reference_strain`	`Array \| list[float]`	Reference strain vector for the link.	required
`young_modulus`	`float \| None`	Young's modulus used with `shear_modulus` to build generalized stiffness. Mutually exclusive with `stiffness`.	`None`
`shear_modulus`	`float \| None`	Shear modulus used with `young_modulus`. Mutually exclusive with `poisson_ratio`.	`None`
`poisson_ratio`	`float \| None`	Poisson's ratio used with `young_modulus` to derive the shear modulus. Mutually exclusive with `shear_modulus`.	`None`
`material_damping_coefficient`	`float \| None`	Isotropic damping value used to build generalized damping. Mutually exclusive with `damping`. If both are omitted, damping is disabled.	`None`
`stiffness`	`Array \| None`	Explicit generalized stiffness matrix.	`None`
`damping`	`Array \| None`	Explicit generalized damping matrix.	`None`

Returns:

Type	Description
`LinkSpec`	A rectangular :class:`LinkSpec` ready for GVS construction.

Raises:

Type	Description
`ValueError`	If material and explicit sources are missing, incomplete, or supplied together, or if an explicit matrix is not finite, square, and symmetric, or if a physical dimension, density, length, or material scalar is outside its valid domain.

elliptical `classmethod` ¶

elliptical(*, length: float, semi_major: float | LinearProfile, semi_minor: float | LinearProfile, density: float, reference_strain: Array | list[float], young_modulus: float | None = None, shear_modulus: float | None = None, poisson_ratio: float | None = None, material_damping_coefficient: float | None = None, stiffness: Array | None = None, damping: Array | None = None) -> LinkSpec

Create a solid elliptical-link specification.

Parameters:

Name	Type	Description	Default
`length`	`float`	Link length.	required
`semi_major`	`float \| LinearProfile`	Constant semi-major axis or base-to-tip linear profile.	required
`semi_minor`	`float \| LinearProfile`	Constant semi-minor axis or base-to-tip linear profile.	required
`density`	`float`	Volumetric mass density.	required
`reference_strain`	`Array \| list[float]`	Reference strain vector for the link.	required
`young_modulus`	`float \| None`	Young's modulus used with `shear_modulus` to build generalized stiffness. Mutually exclusive with `stiffness`.	`None`
`shear_modulus`	`float \| None`	Shear modulus used with `young_modulus`. Mutually exclusive with `poisson_ratio`.	`None`
`poisson_ratio`	`float \| None`	Poisson's ratio used with `young_modulus` to derive the shear modulus. Mutually exclusive with `shear_modulus`.	`None`
`material_damping_coefficient`	`float \| None`	Isotropic damping value used to build generalized damping. Mutually exclusive with `damping`. If both are omitted, damping is disabled.	`None`
`stiffness`	`Array \| None`	Explicit generalized stiffness matrix.	`None`
`damping`	`Array \| None`	Explicit generalized damping matrix.	`None`

Returns:

Type	Description
`LinkSpec`	An elliptical :class:`LinkSpec` ready for GVS construction.

Raises:

Type	Description
`ValueError`	If material and explicit sources are missing, incomplete, or supplied together, or if an explicit matrix is not finite, square, and symmetric, or if a physical dimension, density, length, or material scalar is outside its valid domain.

IsotropicMaterialParams ¶

Bases: BaseSystemParams


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

                              soromox.systems.params.BaseSystemParams --> soromox.systems.components.IsotropicMaterialParams
                


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

Caller-owned isotropic material variables.

These values are construction and optimization variables rather than canonical robot runtime parameters. Pass an instance to link_matrices_from_material or with_isotropic_material to map it to generalized link matrices.

Attributes:

Name	Type	Description
`young_modulus`	`Array`	Scalar or per-link Young's modulus values.
`shear_modulus`	`Array \| None`	Optional scalar or per-link shear modulus values. Exactly one of `shear_modulus` and `poisson_ratio` must be provided.
`poisson_ratio`	`Array \| None`	Optional scalar or per-link Poisson-ratio values.
`material_damping_coefficient`	`Array \| None`	Optional scalar or per-link isotropic material damping values. `None` disables material damping.

The presence of shear_modulus, poisson_ratio, and material_damping_coefficient is part of the PyTree structure. JIT-compiled functions therefore specialize on the chosen stiffness parameterization and on whether material damping is active, while the numeric arrays remain differentiable leaves.

replace ¶

replace(**updates: Any) -> BaseSystemParams

Return an immutable copy with selected fields replaced.

Parameters:

Name	Type	Description	Default
`**updates`	`Any`	Parameter field names and their replacement values. Nested parameter components should first be replaced with their own `replace` method, then supplied as a top-level field.	`{}`

Returns:

Type	Description
`BaseSystemParams`	A validated parameter PyTree of the same concrete class.

Raises:

Type	Description
`KeyError`	If any update names an unknown parameter field.
`TypeError`	If a replacement cannot be inserted into the PyTree.
`ValueError`	If validation of the resulting parameters fails.

validate ¶

validate() -> None

Validate both parameter structure and eager numeric values.

validate_for_update ¶

validate_for_update() -> None

Validate values when concrete and structure when dynamically traced.

validate_structure_compatibility ¶

validate_structure_compatibility(structure: Any) -> None

Validate statically observable compatibility with a model structure.

validate_value_compatibility ¶

validate_value_compatibility(structure: Any) -> None

Validate eager value compatibility with a model structure.

validate_against_structure ¶

validate_against_structure(structure: Any) -> None

Validate parameters fully against static construction choices.

Parameters:

Name	Type	Description	Default
`structure`	`Any`	System-specific static structure to validate against.	required

Returns:

Type	Description
`None`	`None` after successful validation.

Raises:

Type	Description
`ValueError`	If intrinsic or structure-dependent validation fails.

validate_for_update_against_structure ¶

validate_for_update_against_structure(structure: Any) -> None

Validate concrete values and traced structure against a model.

validate_structure ¶

validate_structure() -> None

Validate the material parameterization and static array layout.

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If both or neither of `shear_modulus` and `poisson_ratio` are provided; any active material field has more than one dimension; or a one-dimensional field is empty.

validate_values ¶

validate_values() -> None

Validate eager material physical values.

Returns:

Type	Description
`None`	None.

Raises:

Type	Description
`ValueError`	If either modulus is non-finite or not strictly positive; Poisson's ratio is outside `(-1, 0.5)`; or the material damping coefficient is non-finite or negative.

broadcast ¶

broadcast(num_links: int) -> IsotropicMaterialParams

Broadcast scalar material fields to one value per link.

Parameters:

Name	Type	Description	Default
`num_links`	`int`	Number of links in the target robot.	required

Returns:

Type	Description
`IsotropicMaterialParams`	A new material PyTree whose active fields all have shape
`IsotropicMaterialParams`	`(num_links,)`. Inactive optional fields remain `None`.

Raises:

Type	Description
`ValueError`	If a non-scalar field does not have shape `(num_links,)`.

evaluate_profile ¶

evaluate_profile(coefficients: Array, profile_type: ProfileType, normalized_arclength: Array) -> Array

Evaluate a cross-section profile at normalized arc-length positions.

Parameters:

Name	Type	Description	Default
`coefficients`	`Array`	Coefficients for one profile. A constant profile uses the first entry; a linear profile uses `[base, tip]`.	required
`profile_type`	`ProfileType`	Either `"constant"` or `"linear"`.	required
`normalized_arclength`	`Array`	Scalar or array of positions measured from zero at the link base to one at the link tip.	required

Returns:

Type	Description
`Array`	Profile values with the same shape as `normalized_arclength`.

Raises:

Type	Description
`ValueError`	If `profile_type` is not supported.

section_properties ¶

section_properties(geometry: CrossSectionGeometry | int, dimensions: Array) -> tuple[Array, Array, Array, Array]

Return (I_x, I_y, I_z, area) for a solid section.

The material-frame x-axis is longitudinal. Rectangular dimensions are ordered [height, width] and elliptical dimensions are ordered [semi_major, semi_minor].

Parameters:

Name	Type	Description	Default
`geometry`	`CrossSectionGeometry \| int`	Cross-section family, supplied as a :class:`CrossSectionGeometry` value or its integer value.	required
`dimensions`	`Array`	Geometry dimensions. Circular sections use `[radius]`; rectangular sections use `[height, width]`; elliptical sections use `[semi_major, semi_minor]`.	required

Returns:

Type	Description
`Array`	A tuple `(I_x, I_y, I_z, area)` containing the polar second moment
`Array`	about the longitudinal material x-axis, the transverse second moments,
`Array`	and the section area.

Raises:

Type	Description
`ValueError`	If `geometry` does not identify a supported section.

joint_dof ¶

joint_dof(joint_type: str) -> int

Return the active-coordinate dimension of a supported joint type.

Parameters:

Name	Type	Description	Default
`joint_type`	`str`	Lower-case joint family name.	required

Returns:

Type	Description
`int`	Number of active joint coordinates.

Raises:

Type	Description
`ValueError`	If `joint_type` is unknown.

shear_modulus_from_poisson_ratio ¶

shear_modulus_from_poisson_ratio(young_modulus: Array | float, poisson_ratio: Array | float) -> Array

Compute the shear modulus of an isotropic material.

Parameters:

Name	Type	Description	Default
`young_modulus`	`Array \| float`	Young's modulus `E` as a scalar or array.	required
`poisson_ratio`	`Array \| float`	Poisson's ratio `nu` as a scalar or array broadcastable with `young_modulus`.	required

Returns:

Type	Description
`Array`	The shear modulus `G = E / (2 (1 + nu))` with the broadcasted input
`Array`	shape.

Continuum Robot Components¶

Model composition¶

Cross-sections¶

Continuum links¶

Isotropic material model¶

Joints¶

Construction specs, params, and structure¶

API reference¶

soromox.systems.components ¶

CrossSectionGeometry ¶

CrossSectionParams ¶

replace ¶

validate ¶

validate_for_update ¶

validate_structure_compatibility ¶

validate_value_compatibility ¶

validate_against_structure ¶

validate_for_update_against_structure ¶

validate_structure ¶

validate_values ¶

LinearProfile dataclass ¶

__post_init__ ¶

JointParams ¶

replace ¶

validate ¶

validate_for_update ¶

validate_structure_compatibility ¶

validate_value_compatibility ¶

validate_against_structure ¶

validate_for_update_against_structure ¶

validate_structure ¶

validate_values ¶

JointSpec dataclass ¶

fixed classmethod ¶

revolute classmethod ¶

prismatic classmethod ¶

helical classmethod ¶

cylindrical classmethod ¶

planar classmethod ¶

spherical classmethod ¶

free classmethod ¶

ContinuumLinkParams ¶

replace ¶

validate ¶

validate_for_update ¶

validate_structure_compatibility ¶

validate_value_compatibility ¶

validate_against_structure ¶

validate_for_update_against_structure ¶

validate_structure ¶

validate_values ¶

LinkSpec dataclass ¶

circular classmethod ¶

rectangular classmethod ¶

elliptical classmethod ¶

IsotropicMaterialParams ¶

replace ¶

validate ¶

validate_for_update ¶

validate_structure_compatibility ¶

validate_value_compatibility ¶

validate_against_structure ¶

validate_for_update_against_structure ¶

validate_structure ¶

validate_values ¶

broadcast ¶

evaluate_profile ¶

section_properties ¶

joint_dof ¶

shear_modulus_from_poisson_ratio ¶

LinearProfile `dataclass` ¶

JointSpec `dataclass` ¶

fixed `classmethod` ¶

revolute `classmethod` ¶

prismatic `classmethod` ¶

helical `classmethod` ¶

cylindrical `classmethod` ¶

planar `classmethod` ¶

spherical `classmethod` ¶

free `classmethod` ¶

LinkSpec `dataclass` ¶

circular `classmethod` ¶

rectangular `classmethod` ¶

elliptical `classmethod` ¶