Plant dynamics

feedbax.mechanics.plant.PlantState (Module, Generic[StateT])

The state of a biomechanical model.

Some models may only possess a skeleton, with forces input directly by a controller.

Attributes. skeleton: The state of the skeleton. muscles: The state of the muscles, if included in the model.

feedbax.mechanics.plant.AbstractPlant (AbstractStagedModel[PlantState], AbstractDynamicalSystem[PlantState])

Base class for models of muscoloskeletal systems.

These models describe both 1) the continuous dynamics, and 2) instantaneous dependencies between variables.

For example, we may model 1) the rate of change of skeletal joint angles given torques applied to the joints, but also 2) the force generated by a muscle, which is not described by a differential equation but is directly dependent in each instant on the skeletal geometry.

Kinematic/geometric updates are specified in model_spec, and dynamic updates in dynamics_spec. Calling an AbstractPlant instance will only perform the kinematic updates defined in model_spec. Normally we wrap the instance in a Mechanics instance to discretize the dynamics—then, calling the Mechanics instance will perform both sets of updates.

Attributes:

Name	Type	Description
skeleton	AbstractVar[AbstractSkeleton]	The model of skeletal dynamics.
muscle_model	AbstractVar[AbstractSkeleton]	The muscle model, if the model includes muscles.
clip_states	AbstractVar[bool]	Whether to clip the state to its bounds.

vector_field (t: Scalar,state: PlantState,input: PyTree[Array]) -> PlantState

Return the time derivatives of musculoskeletal variables, where those derivatives are defined.

Aggregates vector fields for different substates of the plant state, as described by dynamics_spec.

Parameters:

Name	Type	Description	Default
t	Scalar	The simulation time. Typically this is unused by any of the constituent fields.	required
state	PlantState	The state of the musculoskeletal system.	required
input	PyTree[Array]	The control inputs to the musculoskeletal system.	required

init (*,key: PRNGKeyArray) -> PlantState

abstractmethod

Returns a default state for the plant.

model_spec () -> OrderedDict[str, ModelStage[Self, PlantState]]

Specifies kinematic updates to the musculoskeletal state.

dynamics_spec () -> Mapping[str, DynamicsComponent[PlantState]]

Aggregates differential equations for different substates of the musculoskeletal state.

input_size () -> int

Number of control inputs.

feedbax.mechanics.plant.DirectForceInput (AbstractPlant)

Model of a skeleton controlled directly by forces/torques—no muscles.

This is essentially a wrapper for an AbstractSkeleton, it skeleton conforms with the interface expected by Mechanics.

It also adds optional state clipping.

Attributes:

Name	Type	Description
skeleton	AbstractSkeleton	The model of skeletal dynamics.
muscle_model	AbstractSkeleton	None.
clip_states	bool	Whether to clip the state to its bounds.
intervenors	ModelIntervenors[PlantState]	Intervenors associated with each model stage.

model_spec: OrderedDict[str, ModelStage[Self, PlantState]] property

Specifies at most one model stage: state clipping, if it is enabled.

dynamics_spec: Mapping[str, DynamicsComponent[PlantState]] property

Specifies a single dynamical component: the skeleton.

input_size: int property

Equal to the skeleton's input size.

__init__ (skeleton: AbstractSkeleton,clip_states: bool = True,intervenors: Optional[ArgIntervenors] = None,*,key: Optional[PRNGKeyArray] = None)

Parameters:

Name	Type	Description	Default
skeleton	AbstractSkeleton	The model of skeletal dynamics.	required
clip_states	bool	Whether to clip the state to its bounds.	True
intervenors	Optional[ArgIntervenors]	Intervenors associated with each model stage.	None

init (*,key: PRNGKeyArray) -> PlantState

Return a default state for the plant.

feedbax.mechanics.plant.MuscledArm (AbstractMuscledPlant)

Model of a two-link arm actuated by muscles.

Attributes:

Name	Type	Description
skeleton	AbstractSkeleton	The model of skeletal dynamics.
muscle_model	AbstractMuscle	The muscle model.
activator	AbstractDynamicalSystem	The muscle activator, such as ActivationFilter.
clip_states	bool	Whether to clip the states to their bounds.
n_muscles	int	The number of muscles.
moment_arms	Float[Array, 'links=2 muscles']	The moment arms of the muscles with respect to the joints.
theta0	Float[Array, 'links=2 muscles']	The optimal angles of the muscles with respect to the joints.
l0	Float[Array, muscles]	The optimal length for each muscle.
f0	Float[Array, muscles]	The maximum isometric force for each muscle.
intervenors	ModelIntervenors[PlantState]	Intervenors associated with each model stage.

model_spec: OrderedDict[str, ModelStage[Self, PlantState]] property

Specifies kinematic updates to the musculoskeletal state.

dynamics_spec: Mapping[str, DynamicsComponent[PlantState]] property

Specifies the components of the muscled arm dynamics.

input_size: int property

Equal to the number of muscles.

__init__ (muscle_model: AbstractMuscle,activator: AbstractDynamicalSystem,skeleton: AbstractSkeleton = TwoLinkArm(),clip_states: bool = True,moment_arms: Float[Array, 'links=2 muscles'] | Sequence[Sequence[float]] = jnp.array(((2.0, -2.0, 0.0, 0.0, 1.5, -2.0), (0.0, 0.0, 2.0, -2.0, 2.0, -1.5))),theta0: Float[Array, 'links=2 muscles'] | Sequence[Sequence[float]] = 2 * jnp.pi * jnp.array(((15.0, 4.88, 0.0, 0.0, 4.5, 2.12), (0.0, 0.0, 80.86, 109.32, 92.96, 91.52))) / 360.0,l0: Float[Array, muscles] | Sequence[float] = jnp.array((7.32, 3.26, 6.4, 4.26, 5.95, 4.04)),f0: Float[Array, muscles] | Sequence[float] = jnp.array((1.0, 1.0, 1.0, 1.0, 1.0, 1.0)),intervenors: Optional[ArgIntervenors] = None,*,key: Optional[PRNGKeyArray] = None)

Parameters:

Name	Type	Description	Default
muscle_model	AbstractMuscle	The muscle model.	required
activator	AbstractDynamicalSystem	The muscle activator.	required
skeleton	AbstractSkeleton	The model of skeletal dynamics.	TwoLinkArm()
clip_states	bool	Whether to clip the state to its bounds.	True
moment_arms	Float[Array, 'links=2 muscles'] | Sequence[Sequence[float]]	The moment arms of the muscles with respect to the joints.	array(((2.0, -2.0, 0.0, 0.0, 1.5, -2.0), (0.0, 0.0, 2.0, -2.0, 2.0, -1.5)))
theta0	Float[Array, 'links=2 muscles'] | Sequence[Sequence[float]]	The optimal angles of the muscles with respect to the joints (radians).	2 * pi * array(((15.0, 4.88, 0.0, 0.0, 4.5, 2.12), (0.0, 0.0, 80.86, 109.32, 92.96, 91.52))) / 360.0
l0	Float[Array, muscles] | Sequence[float]	The optimal length for each muscle.	array((7.32, 3.26, 6.4, 4.26, 5.95, 4.04))
f0	Float[Array, muscles] | Sequence[float]	The maximum isometric force for each muscle.	array((1.0, 1.0, 1.0, 1.0, 1.0, 1.0))
intervenors	Optional[ArgIntervenors]	Intervenors associated with each model stage.	None

init (*,key: PRNGKeyArray) -> PlantState

Return a default state for the muscled arm.