Actuation API reference¶
Bases: Module
flowchart TD
soromox.actuation.Actuator[Actuator]
click soromox.actuation.Actuator href "" "soromox.actuation.Actuator"
A transmission paired with an effort law and ordered channel metadata.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
validate_structure_for_robot(robot: SoftRobot) -> None
Validate tracer-safe component compatibility with robot.
ActuatorMetadata(*, labels: tuple[str, ...], units: str | tuple[str, ...], kind: ActuatorKind = 'generic', lower_bounds: Array | None = None, upper_bounds: Array | None = None)
Bases: Module
flowchart TD
soromox.actuation.ActuatorMetadata[ActuatorMetadata]
click soromox.actuation.ActuatorMetadata href "" "soromox.actuation.ActuatorMetadata"
Ordered labels, units, limits, and semantics for input channels.
Bases: EffortModel
flowchart TD
soromox.actuation.DirectEffort[DirectEffort]
soromox.actuation.core.EffortModel[EffortModel]
soromox.actuation.core.EffortModel --> soromox.actuation.DirectEffort
click soromox.actuation.DirectEffort href "" "soromox.actuation.DirectEffort"
click soromox.actuation.core.EffortModel href "" "soromox.actuation.core.EffortModel"
Stateless effort model for which effort is exactly the user control.
Bases: Module
flowchart TD
soromox.actuation.EffortModel[EffortModel]
click soromox.actuation.EffortModel href "" "soromox.actuation.EffortModel"
Map controls to efforts work-conjugate to transmission coordinates.
abstractmethod
¶
Return actuator effort for the current control and transmission state.
Bases: Actuator
flowchart TD
soromox.actuation.IdentityActuator[IdentityActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.IdentityActuator
click soromox.actuation.IdentityActuator href "" "soromox.actuation.IdentityActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Direct generalized-coordinate actuation used by default.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.IdentityActuatorParams[IdentityActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.IdentityActuatorParams
click soromox.actuation.IdentityActuatorParams href "" "soromox.actuation.IdentityActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Empty immutable parameter object for identity actuation.
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 |
{}
|
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 statically observable parameter structure.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
shapes, PyTree layout, or static topology. Implementations must be |
None
|
safe when array leaves are JAX tracers. |
Validate eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Bases: Transmission
flowchart TD
soromox.actuation.IdentityTransmission[IdentityTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.IdentityTransmission
click soromox.actuation.IdentityTransmission href "" "soromox.actuation.IdentityTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Identity generalized-coordinate transmission.
Bases: Module
flowchart TD
soromox.actuation.PassiveElement[PassiveElement]
click soromox.actuation.PassiveElement href "" "soromox.actuation.PassiveElement"
Independent passive contribution to robot mechanics.
Bases: Module
flowchart TD
soromox.actuation.Transmission[Transmission]
click soromox.actuation.Transmission href "" "soromox.actuation.Transmission"
Map robot configuration to work-conjugate actuator coordinates.
AffineGeneralizedCoordinateActuator(*, params: AffineGeneralizedCoordinateActuatorParams, labels: tuple[str, ...] | None = None, units: str | tuple[str, ...] = 'generalized effort', name: str = 'affine_generalized_coordinate_actuator')
Bases: Actuator
flowchart TD
soromox.actuation.AffineGeneralizedCoordinateActuator[AffineGeneralizedCoordinateActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.AffineGeneralizedCoordinateActuator
click soromox.actuation.AffineGeneralizedCoordinateActuator href "" "soromox.actuation.AffineGeneralizedCoordinateActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Apply signed controls through a constant affine coordinate map.
The actuator combines :class:AffineGeneralizedCoordinateTransmission with
:class:DirectEffort. For a routing matrix R, reference configuration
q_ref, and coordinate offset y_a0, its work-conjugate actuator
coordinates and velocities are
y_a = R @ (q - q_ref) + y_a0 and yd_a = R @ qd.
A user control is interpreted directly as the signed effort conjugate to
y_a. The generalized force is therefore tau = R.T @ control and
satisfies the power identity qd.T @ tau = yd_a.T @ control. This makes
the class suitable for direct joint torques, prismatic forces, selected
generalized-coordinate efforts, or fixed linear combinations of them. It
imposes no tendon-specific positivity, serial-routing, or host restrictions.
Input bounds are exposed through :attr:metadata for downstream consumers.
They are intentionally not enforced inside :meth:efforts; controls outside
those bounds still produce the corresponding linear generalized force.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
validate_values_for_robot(robot: SoftRobot) -> None
Validate concrete component values against robot.
validate_for_robot(robot: SoftRobot) -> None
Validate robot compatibility without concretizing dynamic leaves.
classmethod
¶
from_routing(routing_matrix: Array, *, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, lower_bounds: Array | float | None = None, upper_bounds: Array | float | None = None, labels: tuple[str, ...] | None = None, units: str | tuple[str, ...] = 'generalized effort', name: str = 'affine_generalized_coordinate_actuator') -> AffineGeneralizedCoordinateActuator
Construct signed direct actuation from an affine routing matrix.
Bounds are exposed through :class:ActuatorMetadata and are not
enforced by clipping. Omitting either bound makes it infinite.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.AffineGeneralizedCoordinateActuatorParams[AffineGeneralizedCoordinateActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.AffineGeneralizedCoordinateActuatorParams
click soromox.actuation.AffineGeneralizedCoordinateActuatorParams href "" "soromox.actuation.AffineGeneralizedCoordinateActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Parameters for signed direct effort through an affine coordinate map.
transmission defines actuator work coordinates
y_a = R @ (q - q_ref) + y_a0. The corresponding moment matrix is
A = R.T. lower_bounds and upper_bounds are ordered channel
metadata for controllers, trajectory optimization, and user interfaces;
they do not modify or clip controls passed to the actuator.
Attributes:
| Name | Type | Description |
|---|---|---|
transmission |
AffineGeneralizedCoordinateTransmissionParams
|
Affine generalized-coordinate transmission with one row per actuator channel and one column per robot coordinate. |
lower_bounds |
Array
|
Descriptive lower control bound for every channel. |
upper_bounds |
Array
|
Descriptive upper control bound for every channel. |
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
AffineGeneralizedCoordinateTransmission(params: AffineGeneralizedCoordinateTransmissionParams)
Bases: Transmission
flowchart TD
soromox.actuation.AffineGeneralizedCoordinateTransmission[AffineGeneralizedCoordinateTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.AffineGeneralizedCoordinateTransmission
click soromox.actuation.AffineGeneralizedCoordinateTransmission href "" "soromox.actuation.AffineGeneralizedCoordinateTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Affine actuator coordinates R @ (q - q_ref) + y_a0.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.AffineGeneralizedCoordinateTransmissionParams[AffineGeneralizedCoordinateTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.AffineGeneralizedCoordinateTransmissionParams
click soromox.actuation.AffineGeneralizedCoordinateTransmissionParams href "" "soromox.actuation.AffineGeneralizedCoordinateTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Parameters for an affine mapping to actuator coordinates.
Attributes:
| Name | Type | Description |
|---|---|---|
routing_matrix |
Array
|
Matrix |
reference_configuration |
Array
|
Generalized configuration |
coordinate_offset |
Array
|
Per-channel actuator coordinate |
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 |
{}
|
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 eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedTendonActuator(*, params: ArticulatedTendonActuatorParams, labels: tuple[str, ...] | None = None, name: str = 'articulated_tendons')
Bases: Actuator
flowchart TD
soromox.actuation.ArticulatedTendonActuator[ArticulatedTendonActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.ArticulatedTendonActuator
click soromox.actuation.ArticulatedTendonActuator href "" "soromox.actuation.ArticulatedTendonActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Positive-tension actuation through fixed signed joint routing.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
validate_for_robot(robot: SoftRobot) -> None
Validate robot compatibility without concretizing dynamic leaves.
classmethod
¶
from_routing(routing_matrix: Array, *, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, lower_bounds: Array | float = 0.0, upper_bounds: Array | float = inf, labels: tuple[str, ...] | None = None, name: str = 'articulated_tendons') -> ArticulatedTendonActuator
Construct direct-tension actuation from signed joint routing.
The resulting actuator coordinate is
routing_matrix @ (q - reference_configuration) + coordinate_offset.
Each routing row is the signed contraction Jacobian of one tendon.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
routing_matrix
|
Array
|
Signed tendon routing with one row per tendon and one column per generalized coordinate. |
required |
reference_configuration
|
Array | None
|
Configuration |
None
|
coordinate_offset
|
Array | float
|
Actuator coordinate |
0.0
|
lower_bounds
|
Array | float
|
Lower tension bounds, shared or per tendon. |
0.0
|
upper_bounds
|
Array | float
|
Upper tension bounds, shared or per tendon. |
inf
|
labels
|
tuple[str, ...] | None
|
Optional input label for each tendon. |
None
|
name
|
str
|
Component name used for identification and rendering. |
'articulated_tendons'
|
Returns:
| Type | Description |
|---|---|
ArticulatedTendonActuator
|
An articulated tendon actuator with direct tension effort. |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ArticulatedTendonActuatorParams[ArticulatedTendonActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ArticulatedTendonActuatorParams
click soromox.actuation.ArticulatedTendonActuatorParams href "" "soromox.actuation.ArticulatedTendonActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Physical parameters for direct-effort articulated tendons.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedTendonImpedance(*, params: ArticulatedTendonImpedanceParams, name: str = 'passive_articulated_tendons')
Bases: PassiveElement
flowchart TD
soromox.actuation.ArticulatedTendonImpedance[ArticulatedTendonImpedance]
soromox.actuation.core.PassiveElement[PassiveElement]
soromox.actuation.core.PassiveElement --> soromox.actuation.ArticulatedTendonImpedance
click soromox.actuation.ArticulatedTendonImpedance href "" "soromox.actuation.ArticulatedTendonImpedance"
click soromox.actuation.core.PassiveElement href "" "soromox.actuation.core.PassiveElement"
Passive spring-damper mechanics in affine tendon coordinates.
validate_for_robot(robot: SoftRobot) -> None
Validate robot compatibility without concretizing dynamic leaves.
classmethod
¶
from_routing(routing_matrix: Array, *, stiffness: Array, damping: Array, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, name: str = 'passive_articulated_tendons') -> ArticulatedTendonImpedance
Construct passive spring-damper mechanics in tendon coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
routing_matrix
|
Array
|
Signed tendon routing with one row per passive tendon and one column per generalized coordinate. |
required |
stiffness
|
Array
|
Actuator-space stiffness, one value per tendon. |
required |
damping
|
Array
|
Actuator-space damping, one value per tendon. |
required |
reference_configuration
|
Array | None
|
Configuration |
None
|
coordinate_offset
|
Array | float
|
Tendon deformation |
0.0
|
name
|
str
|
Component name used for identification and rendering. |
'passive_articulated_tendons'
|
Returns:
| Type | Description |
|---|---|
ArticulatedTendonImpedance
|
A passive articulated tendon impedance component. |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ArticulatedTendonImpedanceParams[ArticulatedTendonImpedanceParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ArticulatedTendonImpedanceParams
click soromox.actuation.ArticulatedTendonImpedanceParams href "" "soromox.actuation.ArticulatedTendonImpedanceParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Spring-damper parameters for articulated tendon coordinates.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedMcKibbenActuator(*, params: ArticulatedMcKibbenActuatorParams, labels: tuple[str, ...] | None = None, name: str = 'mckibben_muscles')
Bases: Actuator
flowchart TD
soromox.actuation.ArticulatedMcKibbenActuator[ArticulatedMcKibbenActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.ArticulatedMcKibbenActuator
click soromox.actuation.ArticulatedMcKibbenActuator href "" "soromox.actuation.ArticulatedMcKibbenActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Direct-pressure McKibben muscle actuator.
Controls are pressures in pascals. The transmission supplies equivalent volume coordinates, while diagnostic helpers expose effective lengths, endpoint segments, and signed axial forces. Installation requires a spatial articulated robot implementing the kinematic-frame contract; continuum hosts must use an appropriate continuum transmission instead.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
validate_for_robot(robot: SoftRobot) -> None
Validate robot compatibility without concretizing dynamic leaves.
classmethod
¶
empty(actuators_per_group: int = 4) -> ArticulatedMcKibbenActuator
Construct a zero-channel actuator with fixed empty group topology.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ArticulatedMcKibbenActuatorParams[ArticulatedMcKibbenActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ArticulatedMcKibbenActuatorParams
click soromox.actuation.ArticulatedMcKibbenActuatorParams href "" "soromox.actuation.ArticulatedMcKibbenActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
McKibben transmission and pressure bounds.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedMcKibbenTransmission(params: ArticulatedMcKibbenTransmissionParams)
Bases: Transmission
flowchart TD
soromox.actuation.ArticulatedMcKibbenTransmission[ArticulatedMcKibbenTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.ArticulatedMcKibbenTransmission
click soromox.actuation.ArticulatedMcKibbenTransmission href "" "soromox.actuation.ArticulatedMcKibbenTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Pressure-work transmission using McKibben volume coordinates.
The transmission owns fixed and moving attachment geometry for grouped universal joints on a spatial articulated host. It computes effective muscle lengths, the volume-like coordinate work-conjugate to pressure, its analytic moment matrix, and renderer-facing endpoint segments without embedding those mechanics in a particular articulated robot class.
velocities(robot: SoftRobot, q: Array, qd: Array) -> Array
Return transmission-coordinate velocities.
Return group-local fixed/moving endpoint segments.
Returns:
| Type | Description |
|---|---|
Array
|
Array with shape |
Array
|
Endpoint axis 2 is ordered as |
Return world-space actuator endpoint segments for rendering.
Returns:
| Type | Description |
|---|---|
Array
|
Array with shape |
Array
|
ordered as |
Return effective McKibben muscle lengths.
For actuator i, the effective length is its current geometric
endpoint distance minus reference_length[i] plus
length_offset[i].
Return pressure-work coordinates for all McKibben muscles.
The coordinate is (B**2 - length**2) * length / (4*pi*N**2) and has
volume units, making pressure its work-conjugate effort.
Return the analytic pressure-to-generalized-force matrix A(q).
Return per-muscle axial forces for the supplied pressures.
The sign convention and constitutive equation match the cached UMArm model and its MuJoCo implementation.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ArticulatedMcKibbenTransmissionParams[ArticulatedMcKibbenTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ArticulatedMcKibbenTransmissionParams
click soromox.actuation.ArticulatedMcKibbenTransmissionParams href "" "soromox.actuation.ArticulatedMcKibbenTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Attachment geometry and constitutive parameters for McKibben groups.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
classmethod
¶
from_cached_npz(path: str | Path) -> ArticulatedMcKibbenTransmissionParams
Load McKibben transmission fields from an existing UMArm cache.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.BaseThreadlikeRoutingParams[BaseThreadlikeRoutingParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.BaseThreadlikeRoutingParams
click soromox.actuation.BaseThreadlikeRoutingParams href "" "soromox.actuation.BaseThreadlikeRoutingParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Base PyTree contract for vectorized threadlike routing parameters.
Validate statically observable parameter structure.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
shapes, PyTree layout, or static topology. Implementations must be |
None
|
safe when array leaves are JAX tracers. |
Validate eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
replace(**updates: Any) -> BaseThreadlikeRoutingParams
Replace numeric fields while keeping routing topology immutable.
Bases: BaseThreadlikeRoutingParams
flowchart TD
soromox.actuation.LinearThreadlikeRoutingParams[LinearThreadlikeRoutingParams]
soromox.actuation.threadlike.BaseThreadlikeRoutingParams[BaseThreadlikeRoutingParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.actuation.threadlike.BaseThreadlikeRoutingParams --> soromox.actuation.LinearThreadlikeRoutingParams
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.BaseThreadlikeRoutingParams
click soromox.actuation.LinearThreadlikeRoutingParams href "" "soromox.actuation.LinearThreadlikeRoutingParams"
click soromox.actuation.threadlike.BaseThreadlikeRoutingParams href "" "soromox.actuation.threadlike.BaseThreadlikeRoutingParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Batched linear material-frame routing and contiguous segment spans.
intercept and slope have shape (num_paths, 3) in the local
material frame. Because SoRoMoX aligns the backbone with the local x-axis,
their x-components must be zero; the remaining components describe the
path within each material-frame cross-section.
replace(**updates: Any) -> BaseThreadlikeRoutingParams
Replace numeric fields while keeping routing topology immutable.
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ThreadlikeActuator(*, params: ThreadlikeActuatorParams, routing: ThreadlikeRouting | None = None, labels: tuple[str, ...], units: str | tuple[str, ...], name: str, kind: ThreadlikeKind)
Bases: Actuator
flowchart TD
soromox.actuation.ThreadlikeActuator[ThreadlikeActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.ThreadlikeActuator
click soromox.actuation.ThreadlikeActuator href "" "soromox.actuation.ThreadlikeActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Vectorized threadlike actuator with modality-specific presets.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ThreadlikeActuatorParams[ThreadlikeActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ThreadlikeActuatorParams
click soromox.actuation.ThreadlikeActuatorParams href "" "soromox.actuation.ThreadlikeActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Physical and control parameters for a threadlike actuator family.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ThreadlikeImpedance(*, routing: ThreadlikeRouting | BaseThreadlikeRoutingParams, stiffness: Array, damping: Array, rest_length: Array, name: str = 'passive_threadlike')
Bases: PassiveElement
flowchart TD
soromox.actuation.ThreadlikeImpedance[ThreadlikeImpedance]
soromox.actuation.core.PassiveElement[PassiveElement]
soromox.actuation.core.PassiveElement --> soromox.actuation.ThreadlikeImpedance
click soromox.actuation.ThreadlikeImpedance href "" "soromox.actuation.ThreadlikeImpedance"
click soromox.actuation.core.PassiveElement href "" "soromox.actuation.core.PassiveElement"
Passive spring-damper mechanics along fixed threadlike paths.
validate_for_robot(robot: SoftRobot) -> None
Validate robot compatibility without concretizing dynamic leaves.
Return the raw lengths of the passive routed paths.
Return the raw length rates of the passive routed paths.
Return passive routed-path positions at backbone coordinate s.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ThreadlikeImpedanceParams[ThreadlikeImpedanceParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ThreadlikeImpedanceParams
click soromox.actuation.ThreadlikeImpedanceParams href "" "soromox.actuation.ThreadlikeImpedanceParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Spring-damper parameters for passive routed paths.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Validate threadlike impedance parameter structure.
Bases: Module
flowchart TD
soromox.actuation.ThreadlikeRouting[ThreadlikeRouting]
click soromox.actuation.ThreadlikeRouting href "" "soromox.actuation.ThreadlikeRouting"
Runtime routing object for a batched fixed material-frame path family.
classmethod
¶
linear(*, intercept: Array, slope: Array | float = 0.0, start_segment_index: int | tuple[int, ...] | Array = 0, end_segment_index: int | tuple[int, ...] | Array = 0) -> ThreadlikeRouting
Construct linear cross-section paths in the local material frame.
The final array axis is [x, y, z]. Local x follows the backbone, so
the x-components of intercept and slope must both be zero.
offset(path_params: BaseThreadlikeRoutingParams, s: Array) -> Array
Evaluate one path's material-frame offset at s.
derivative(path_params: BaseThreadlikeRoutingParams, s: Array) -> Array
Evaluate one path's material-frame offset derivative at s.
ThreadlikeTransmission(params: ThreadlikeTransmissionParams, *, routing: ThreadlikeRouting | None = None)
Bases: Transmission
flowchart TD
soromox.actuation.ThreadlikeTransmission[ThreadlikeTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.ThreadlikeTransmission
click soromox.actuation.ThreadlikeTransmission href "" "soromox.actuation.ThreadlikeTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Transmission whose coordinates are scaled routed-path lengths.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.ThreadlikeTransmissionParams[ThreadlikeTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.ThreadlikeTransmissionParams
click soromox.actuation.ThreadlikeTransmissionParams href "" "soromox.actuation.ThreadlikeTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Routing parameters and constant work-coordinate scale per path.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Validate threadlike transmission parameter structure.
linear_threadlike_routing(params: LinearThreadlikeRoutingParams, s: Array) -> Array
Return material-frame offsets intercept + slope * s.
linear_threadlike_routing_derivative(params: LinearThreadlikeRoutingParams, s: Array) -> Array
Return the arc-length derivative of a linear routing offset.
Composable actuation primitives.
The actuation model follows a work-conjugate formulation. A transmission
defines actuator coordinates y_a(q) and their moment matrix
A(q) = dy_a/dq.T. An effort model maps user controls to efforts conjugate to
those coordinates, and generalized actuation forces are A(q) @ effort.
ActuatorMetadata(*, labels: tuple[str, ...], units: str | tuple[str, ...], kind: ActuatorKind = 'generic', lower_bounds: Array | None = None, upper_bounds: Array | None = None)
Bases: Module
flowchart TD
soromox.actuation.core.ActuatorMetadata[ActuatorMetadata]
click soromox.actuation.core.ActuatorMetadata href "" "soromox.actuation.core.ActuatorMetadata"
Ordered labels, units, limits, and semantics for input channels.
Bases: Module
flowchart TD
soromox.actuation.core.Transmission[Transmission]
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Map robot configuration to work-conjugate actuator coordinates.
Bases: Module
flowchart TD
soromox.actuation.core.EffortModel[EffortModel]
click soromox.actuation.core.EffortModel href "" "soromox.actuation.core.EffortModel"
Map controls to efforts work-conjugate to transmission coordinates.
abstractmethod
¶
Return actuator effort for the current control and transmission state.
Bases: EffortModel
flowchart TD
soromox.actuation.core.DirectEffort[DirectEffort]
soromox.actuation.core.EffortModel[EffortModel]
soromox.actuation.core.EffortModel --> soromox.actuation.core.DirectEffort
click soromox.actuation.core.DirectEffort href "" "soromox.actuation.core.DirectEffort"
click soromox.actuation.core.EffortModel href "" "soromox.actuation.core.EffortModel"
Stateless effort model for which effort is exactly the user control.
Bases: Module
flowchart TD
soromox.actuation.core.PassiveElement[PassiveElement]
click soromox.actuation.core.PassiveElement href "" "soromox.actuation.core.PassiveElement"
Independent passive contribution to robot mechanics.
Bases: Module
flowchart TD
soromox.actuation.core.Actuator[Actuator]
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
A transmission paired with an effort law and ordered channel metadata.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
validate_structure_for_robot(robot: SoftRobot) -> None
Validate tracer-safe component compatibility with robot.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.core.IdentityActuatorParams[IdentityActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.core.IdentityActuatorParams
click soromox.actuation.core.IdentityActuatorParams href "" "soromox.actuation.core.IdentityActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Empty immutable parameter object for identity actuation.
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 |
{}
|
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 statically observable parameter structure.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
shapes, PyTree layout, or static topology. Implementations must be |
None
|
safe when array leaves are JAX tracers. |
Validate eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Bases: Transmission
flowchart TD
soromox.actuation.core.IdentityTransmission[IdentityTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.core.IdentityTransmission
click soromox.actuation.core.IdentityTransmission href "" "soromox.actuation.core.IdentityTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Identity generalized-coordinate transmission.
Bases: Actuator
flowchart TD
soromox.actuation.core.IdentityActuator[IdentityActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.core.IdentityActuator
click soromox.actuation.core.IdentityActuator href "" "soromox.actuation.core.IdentityActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Direct generalized-coordinate actuation used by default.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Joint-space transmissions and articulated tendon mechanics.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.joint.AffineGeneralizedCoordinateTransmissionParams[AffineGeneralizedCoordinateTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.joint.AffineGeneralizedCoordinateTransmissionParams
click soromox.actuation.joint.AffineGeneralizedCoordinateTransmissionParams href "" "soromox.actuation.joint.AffineGeneralizedCoordinateTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Parameters for an affine mapping to actuator coordinates.
Attributes:
| Name | Type | Description |
|---|---|---|
routing_matrix |
Array
|
Matrix |
reference_configuration |
Array
|
Generalized configuration |
coordinate_offset |
Array
|
Per-channel actuator coordinate |
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 |
{}
|
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 eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
AffineGeneralizedCoordinateTransmission(params: AffineGeneralizedCoordinateTransmissionParams)
Bases: Transmission
flowchart TD
soromox.actuation.joint.AffineGeneralizedCoordinateTransmission[AffineGeneralizedCoordinateTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.joint.AffineGeneralizedCoordinateTransmission
click soromox.actuation.joint.AffineGeneralizedCoordinateTransmission href "" "soromox.actuation.joint.AffineGeneralizedCoordinateTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Affine actuator coordinates R @ (q - q_ref) + y_a0.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.joint.AffineGeneralizedCoordinateActuatorParams[AffineGeneralizedCoordinateActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.joint.AffineGeneralizedCoordinateActuatorParams
click soromox.actuation.joint.AffineGeneralizedCoordinateActuatorParams href "" "soromox.actuation.joint.AffineGeneralizedCoordinateActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Parameters for signed direct effort through an affine coordinate map.
transmission defines actuator work coordinates
y_a = R @ (q - q_ref) + y_a0. The corresponding moment matrix is
A = R.T. lower_bounds and upper_bounds are ordered channel
metadata for controllers, trajectory optimization, and user interfaces;
they do not modify or clip controls passed to the actuator.
Attributes:
| Name | Type | Description |
|---|---|---|
transmission |
AffineGeneralizedCoordinateTransmissionParams
|
Affine generalized-coordinate transmission with one row per actuator channel and one column per robot coordinate. |
lower_bounds |
Array
|
Descriptive lower control bound for every channel. |
upper_bounds |
Array
|
Descriptive upper control bound for every channel. |
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
AffineGeneralizedCoordinateActuator(*, params: AffineGeneralizedCoordinateActuatorParams, labels: tuple[str, ...] | None = None, units: str | tuple[str, ...] = 'generalized effort', name: str = 'affine_generalized_coordinate_actuator')
Bases: Actuator
flowchart TD
soromox.actuation.joint.AffineGeneralizedCoordinateActuator[AffineGeneralizedCoordinateActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.joint.AffineGeneralizedCoordinateActuator
click soromox.actuation.joint.AffineGeneralizedCoordinateActuator href "" "soromox.actuation.joint.AffineGeneralizedCoordinateActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Apply signed controls through a constant affine coordinate map.
The actuator combines :class:AffineGeneralizedCoordinateTransmission with
:class:DirectEffort. For a routing matrix R, reference configuration
q_ref, and coordinate offset y_a0, its work-conjugate actuator
coordinates and velocities are
y_a = R @ (q - q_ref) + y_a0 and yd_a = R @ qd.
A user control is interpreted directly as the signed effort conjugate to
y_a. The generalized force is therefore tau = R.T @ control and
satisfies the power identity qd.T @ tau = yd_a.T @ control. This makes
the class suitable for direct joint torques, prismatic forces, selected
generalized-coordinate efforts, or fixed linear combinations of them. It
imposes no tendon-specific positivity, serial-routing, or host restrictions.
Input bounds are exposed through :attr:metadata for downstream consumers.
They are intentionally not enforced inside :meth:efforts; controls outside
those bounds still produce the corresponding linear generalized force.
classmethod
¶
from_routing(routing_matrix: Array, *, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, lower_bounds: Array | float | None = None, upper_bounds: Array | float | None = None, labels: tuple[str, ...] | None = None, units: str | tuple[str, ...] = 'generalized effort', name: str = 'affine_generalized_coordinate_actuator') -> AffineGeneralizedCoordinateActuator
Construct signed direct actuation from an affine routing matrix.
Bounds are exposed through :class:ActuatorMetadata and are not
enforced by clipping. Omitting either bound makes it infinite.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.joint.ArticulatedTendonActuatorParams[ArticulatedTendonActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.joint.ArticulatedTendonActuatorParams
click soromox.actuation.joint.ArticulatedTendonActuatorParams href "" "soromox.actuation.joint.ArticulatedTendonActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Physical parameters for direct-effort articulated tendons.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedTendonActuator(*, params: ArticulatedTendonActuatorParams, labels: tuple[str, ...] | None = None, name: str = 'articulated_tendons')
Bases: Actuator
flowchart TD
soromox.actuation.joint.ArticulatedTendonActuator[ArticulatedTendonActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.joint.ArticulatedTendonActuator
click soromox.actuation.joint.ArticulatedTendonActuator href "" "soromox.actuation.joint.ArticulatedTendonActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Positive-tension actuation through fixed signed joint routing.
classmethod
¶
from_routing(routing_matrix: Array, *, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, lower_bounds: Array | float = 0.0, upper_bounds: Array | float = inf, labels: tuple[str, ...] | None = None, name: str = 'articulated_tendons') -> ArticulatedTendonActuator
Construct direct-tension actuation from signed joint routing.
The resulting actuator coordinate is
routing_matrix @ (q - reference_configuration) + coordinate_offset.
Each routing row is the signed contraction Jacobian of one tendon.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
routing_matrix
|
Array
|
Signed tendon routing with one row per tendon and one column per generalized coordinate. |
required |
reference_configuration
|
Array | None
|
Configuration |
None
|
coordinate_offset
|
Array | float
|
Actuator coordinate |
0.0
|
lower_bounds
|
Array | float
|
Lower tension bounds, shared or per tendon. |
0.0
|
upper_bounds
|
Array | float
|
Upper tension bounds, shared or per tendon. |
inf
|
labels
|
tuple[str, ...] | None
|
Optional input label for each tendon. |
None
|
name
|
str
|
Component name used for identification and rendering. |
'articulated_tendons'
|
Returns:
| Type | Description |
|---|---|
ArticulatedTendonActuator
|
An articulated tendon actuator with direct tension effort. |
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.joint.ArticulatedTendonImpedanceParams[ArticulatedTendonImpedanceParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.joint.ArticulatedTendonImpedanceParams
click soromox.actuation.joint.ArticulatedTendonImpedanceParams href "" "soromox.actuation.joint.ArticulatedTendonImpedanceParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Spring-damper parameters for articulated tendon coordinates.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedTendonImpedance(*, params: ArticulatedTendonImpedanceParams, name: str = 'passive_articulated_tendons')
Bases: PassiveElement
flowchart TD
soromox.actuation.joint.ArticulatedTendonImpedance[ArticulatedTendonImpedance]
soromox.actuation.core.PassiveElement[PassiveElement]
soromox.actuation.core.PassiveElement --> soromox.actuation.joint.ArticulatedTendonImpedance
click soromox.actuation.joint.ArticulatedTendonImpedance href "" "soromox.actuation.joint.ArticulatedTendonImpedance"
click soromox.actuation.core.PassiveElement href "" "soromox.actuation.core.PassiveElement"
Passive spring-damper mechanics in affine tendon coordinates.
classmethod
¶
from_routing(routing_matrix: Array, *, stiffness: Array, damping: Array, reference_configuration: Array | None = None, coordinate_offset: Array | float = 0.0, name: str = 'passive_articulated_tendons') -> ArticulatedTendonImpedance
Construct passive spring-damper mechanics in tendon coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
routing_matrix
|
Array
|
Signed tendon routing with one row per passive tendon and one column per generalized coordinate. |
required |
stiffness
|
Array
|
Actuator-space stiffness, one value per tendon. |
required |
damping
|
Array
|
Actuator-space damping, one value per tendon. |
required |
reference_configuration
|
Array | None
|
Configuration |
None
|
coordinate_offset
|
Array | float
|
Tendon deformation |
0.0
|
name
|
str
|
Component name used for identification and rendering. |
'passive_articulated_tendons'
|
Returns:
| Type | Description |
|---|---|
ArticulatedTendonImpedance
|
A passive articulated tendon impedance component. |
McKibben pneumatic-muscle transmission for spatial articulated robots.
This module's geometry is intentionally specific to grouped muscles spanning two-axis articulated joints. It requires a host that provides spatial kinematic frames; it is not a continuum-rod transmission. Continuum models can use threadlike muscle or equivalent pressure-chamber coordinates, while a future continuum McKibben model may reuse the constitutive equation with a different geometry contract.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.mckibben.ArticulatedMcKibbenTransmissionParams[ArticulatedMcKibbenTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.mckibben.ArticulatedMcKibbenTransmissionParams
click soromox.actuation.mckibben.ArticulatedMcKibbenTransmissionParams href "" "soromox.actuation.mckibben.ArticulatedMcKibbenTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Attachment geometry and constitutive parameters for McKibben groups.
classmethod
¶
from_cached_npz(path: str | Path) -> ArticulatedMcKibbenTransmissionParams
Load McKibben transmission fields from an existing UMArm cache.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedMcKibbenTransmission(params: ArticulatedMcKibbenTransmissionParams)
Bases: Transmission
flowchart TD
soromox.actuation.mckibben.ArticulatedMcKibbenTransmission[ArticulatedMcKibbenTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.mckibben.ArticulatedMcKibbenTransmission
click soromox.actuation.mckibben.ArticulatedMcKibbenTransmission href "" "soromox.actuation.mckibben.ArticulatedMcKibbenTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Pressure-work transmission using McKibben volume coordinates.
The transmission owns fixed and moving attachment geometry for grouped universal joints on a spatial articulated host. It computes effective muscle lengths, the volume-like coordinate work-conjugate to pressure, its analytic moment matrix, and renderer-facing endpoint segments without embedding those mechanics in a particular articulated robot class.
Return group-local fixed/moving endpoint segments.
Returns:
| Type | Description |
|---|---|
Array
|
Array with shape |
Array
|
Endpoint axis 2 is ordered as |
Return world-space actuator endpoint segments for rendering.
Returns:
| Type | Description |
|---|---|
Array
|
Array with shape |
Array
|
ordered as |
Return effective McKibben muscle lengths.
For actuator i, the effective length is its current geometric
endpoint distance minus reference_length[i] plus
length_offset[i].
Return pressure-work coordinates for all McKibben muscles.
The coordinate is (B**2 - length**2) * length / (4*pi*N**2) and has
volume units, making pressure its work-conjugate effort.
Return the analytic pressure-to-generalized-force matrix A(q).
Return per-muscle axial forces for the supplied pressures.
The sign convention and constitutive equation match the cached UMArm model and its MuJoCo implementation.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.mckibben.ArticulatedMcKibbenActuatorParams[ArticulatedMcKibbenActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.mckibben.ArticulatedMcKibbenActuatorParams
click soromox.actuation.mckibben.ArticulatedMcKibbenActuatorParams href "" "soromox.actuation.mckibben.ArticulatedMcKibbenActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
McKibben transmission and pressure bounds.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ArticulatedMcKibbenActuator(*, params: ArticulatedMcKibbenActuatorParams, labels: tuple[str, ...] | None = None, name: str = 'mckibben_muscles')
Bases: Actuator
flowchart TD
soromox.actuation.mckibben.ArticulatedMcKibbenActuator[ArticulatedMcKibbenActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.mckibben.ArticulatedMcKibbenActuator
click soromox.actuation.mckibben.ArticulatedMcKibbenActuator href "" "soromox.actuation.mckibben.ArticulatedMcKibbenActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Direct-pressure McKibben muscle actuator.
Controls are pressures in pascals. The transmission supplies equivalent volume coordinates, while diagnostic helpers expose effective lengths, endpoint segments, and signed axial forces. Installation requires a spatial articulated robot implementing the kinematic-frame contract; continuum hosts must use an appropriate continuum transmission instead.
classmethod
¶
empty(actuators_per_group: int = 4) -> ArticulatedMcKibbenActuator
Construct a zero-channel actuator with fixed empty group topology.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Fixed material-frame routing for threadlike continuum actuators.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.threadlike.BaseThreadlikeRoutingParams[BaseThreadlikeRoutingParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.BaseThreadlikeRoutingParams
click soromox.actuation.threadlike.BaseThreadlikeRoutingParams href "" "soromox.actuation.threadlike.BaseThreadlikeRoutingParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Base PyTree contract for vectorized threadlike routing parameters.
replace(**updates: Any) -> BaseThreadlikeRoutingParams
Replace numeric fields while keeping routing topology immutable.
Validate statically observable parameter structure.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
shapes, PyTree layout, or static topology. Implementations must be |
None
|
safe when array leaves are JAX tracers. |
Validate eager value-dependent parameter invariants.
Returns:
| Type | Description |
|---|---|
None
|
|
None
|
domains, symmetry, and other checks requiring concrete values. |
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Bases: BaseThreadlikeRoutingParams
flowchart TD
soromox.actuation.threadlike.LinearThreadlikeRoutingParams[LinearThreadlikeRoutingParams]
soromox.actuation.threadlike.BaseThreadlikeRoutingParams[BaseThreadlikeRoutingParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.actuation.threadlike.BaseThreadlikeRoutingParams --> soromox.actuation.threadlike.LinearThreadlikeRoutingParams
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.BaseThreadlikeRoutingParams
click soromox.actuation.threadlike.LinearThreadlikeRoutingParams href "" "soromox.actuation.threadlike.LinearThreadlikeRoutingParams"
click soromox.actuation.threadlike.BaseThreadlikeRoutingParams href "" "soromox.actuation.threadlike.BaseThreadlikeRoutingParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Batched linear material-frame routing and contiguous segment spans.
intercept and slope have shape (num_paths, 3) in the local
material frame. Because SoRoMoX aligns the backbone with the local x-axis,
their x-components must be zero; the remaining components describe the
path within each material-frame cross-section.
replace(**updates: Any) -> BaseThreadlikeRoutingParams
Replace numeric fields while keeping routing topology immutable.
Validate values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
Bases: Module
flowchart TD
soromox.actuation.threadlike.ThreadlikeRouting[ThreadlikeRouting]
click soromox.actuation.threadlike.ThreadlikeRouting href "" "soromox.actuation.threadlike.ThreadlikeRouting"
Runtime routing object for a batched fixed material-frame path family.
classmethod
¶
linear(*, intercept: Array, slope: Array | float = 0.0, start_segment_index: int | tuple[int, ...] | Array = 0, end_segment_index: int | tuple[int, ...] | Array = 0) -> ThreadlikeRouting
Construct linear cross-section paths in the local material frame.
The final array axis is [x, y, z]. Local x follows the backbone, so
the x-components of intercept and slope must both be zero.
offset(path_params: BaseThreadlikeRoutingParams, s: Array) -> Array
Evaluate one path's material-frame offset at s.
derivative(path_params: BaseThreadlikeRoutingParams, s: Array) -> Array
Evaluate one path's material-frame offset derivative at s.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.threadlike.ThreadlikeTransmissionParams[ThreadlikeTransmissionParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.ThreadlikeTransmissionParams
click soromox.actuation.threadlike.ThreadlikeTransmissionParams href "" "soromox.actuation.threadlike.ThreadlikeTransmissionParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Routing parameters and constant work-coordinate scale per path.
Validate threadlike transmission parameter structure.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ThreadlikeTransmission(params: ThreadlikeTransmissionParams, *, routing: ThreadlikeRouting | None = None)
Bases: Transmission
flowchart TD
soromox.actuation.threadlike.ThreadlikeTransmission[ThreadlikeTransmission]
soromox.actuation.core.Transmission[Transmission]
soromox.actuation.core.Transmission --> soromox.actuation.threadlike.ThreadlikeTransmission
click soromox.actuation.threadlike.ThreadlikeTransmission href "" "soromox.actuation.threadlike.ThreadlikeTransmission"
click soromox.actuation.core.Transmission href "" "soromox.actuation.core.Transmission"
Transmission whose coordinates are scaled routed-path lengths.
Bases: BaseSystemParams
flowchart TD
soromox.actuation.threadlike.ThreadlikeActuatorParams[ThreadlikeActuatorParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.ThreadlikeActuatorParams
click soromox.actuation.threadlike.ThreadlikeActuatorParams href "" "soromox.actuation.threadlike.ThreadlikeActuatorParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Physical and control parameters for a threadlike actuator family.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ThreadlikeActuator(*, params: ThreadlikeActuatorParams, routing: ThreadlikeRouting | None = None, labels: tuple[str, ...], units: str | tuple[str, ...], name: str, kind: ThreadlikeKind)
Bases: Actuator
flowchart TD
soromox.actuation.threadlike.ThreadlikeActuator[ThreadlikeActuator]
soromox.actuation.core.Actuator[Actuator]
soromox.actuation.core.Actuator --> soromox.actuation.threadlike.ThreadlikeActuator
click soromox.actuation.threadlike.ThreadlikeActuator href "" "soromox.actuation.threadlike.ThreadlikeActuator"
click soromox.actuation.core.Actuator href "" "soromox.actuation.core.Actuator"
Vectorized threadlike actuator with modality-specific presets.
efforts(robot: SoftRobot, q: Array, control: Array, qd: Array | None = None, *, transmission_matrix: Array | None = None) -> Array
Map controls to work-conjugate efforts for this actuator.
Only transmission coordinates and velocities required by the installed effort model are evaluated. A precomputed transmission matrix may be supplied to reuse it when evaluating actuator-coordinate velocities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
robot
|
SoftRobot
|
Soft robot on which the actuator is installed. |
required |
q
|
Array
|
Generalized coordinates of shape |
required |
control
|
Array
|
Controls for this actuator with shape
|
required |
qd
|
Array | None
|
Optional generalized velocities of shape
|
None
|
transmission_matrix
|
Array | None
|
Optional precomputed transmission matrix with
shape |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
e |
Array
|
Work-conjugate actuator efforts with shape
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Bases: BaseSystemParams
flowchart TD
soromox.actuation.threadlike.ThreadlikeImpedanceParams[ThreadlikeImpedanceParams]
soromox.systems.params.BaseSystemParams[BaseSystemParams]
soromox.systems.params.BaseSystemParams --> soromox.actuation.threadlike.ThreadlikeImpedanceParams
click soromox.actuation.threadlike.ThreadlikeImpedanceParams href "" "soromox.actuation.threadlike.ThreadlikeImpedanceParams"
click soromox.systems.params.BaseSystemParams href "" "soromox.systems.params.BaseSystemParams"
Spring-damper parameters for passive routed paths.
Validate threadlike impedance parameter structure.
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 |
{}
|
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 values when concrete and structure when dynamically traced.
Validate statically observable compatibility with a model structure.
Validate eager value compatibility with a model structure.
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
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If intrinsic or structure-dependent validation fails. |
Validate concrete values and traced structure against a model.
ThreadlikeImpedance(*, routing: ThreadlikeRouting | BaseThreadlikeRoutingParams, stiffness: Array, damping: Array, rest_length: Array, name: str = 'passive_threadlike')
Bases: PassiveElement
flowchart TD
soromox.actuation.threadlike.ThreadlikeImpedance[ThreadlikeImpedance]
soromox.actuation.core.PassiveElement[PassiveElement]
soromox.actuation.core.PassiveElement --> soromox.actuation.threadlike.ThreadlikeImpedance
click soromox.actuation.threadlike.ThreadlikeImpedance href "" "soromox.actuation.threadlike.ThreadlikeImpedance"
click soromox.actuation.core.PassiveElement href "" "soromox.actuation.core.PassiveElement"
Passive spring-damper mechanics along fixed threadlike paths.
linear_threadlike_routing(params: LinearThreadlikeRoutingParams, s: Array) -> Array
Return material-frame offsets intercept + slope * s.
linear_threadlike_routing_derivative(params: LinearThreadlikeRoutingParams, s: Array) -> Array
Return the arc-length derivative of a linear routing offset.