Physics & Biomechanics
Biomechanics and physics utilities for MyoSuite environments.
Available classes
CumulativeFatigueNumPy implementation of the 3CC-r cumulative muscle fatigue model (Xia & Frey Law, 2008). Backend: CPU (numpy).
CumulativeFatigueJaxJAX-compatible version of the same fatigue model for use in MJX environments. Backend: MJX (jax.numpy).
Quaternion math
All three array backends share the same function signatures. Use the dispatcher so call sites stay backend-agnostic:
from myosuite.physics.quat import get_quat_ops
qm = get_quat_ops(accessor.array_module())
q = qm.mul_quat(qa, qb)
Direct backend imports (when the backend is statically known):
myosuite.physics.quat_math— NumPymyosuite.physics.quat_math_jax— JAX / MJXmyosuite.physics.quat_math_torch— PyTorch / mjlab
- class myosuite.physics.CumulativeFatigue(mj_model, frame_skip=1, sex=None, seed=None, use_uniform_params=False, muscles=None, rest_threshold=0.01)
Bases:
object3CC-r cumulative fatigue model (Xia & Frey Law 2008, Looft et al. 2018).
Tracks the active (MA), fatigued (MF), and resting (MR) compartments for each muscle actuator. By default uses per-muscle fatigue / recovery constants derived from biomechanical functional muscle groups (FMG).
The recovery multiplier
racts only at rest, as in Rakshit et al. (2021, Eqs. 1, 3 and 7; theirkisrhere):dMR/dt = -C(t) + r(k, TL) x R x MF,dMF/dt = F x MA - r(k, TL) x R x MFwithr = k if TL = 0andr = 1 if TL > 0. Rest isTL <= rest_threshold(defaultFATIGUE_REST_THRESHOLD, 0.01): a command of (nearly) zero, plus the negative commands of[-1, 1]control ranges, which MuJoCo’s muscle dynamics clamp to zero excitation. The threshold lets a command mapped through the muscle sigmoid, which never reaches exactly zero, rest.- Parameters:
mj_model (
Any) – Compiled MuJoCo model. Used to read muscle actuator time constants (tauact / taudeact) and to look up per-muscle fatigue parameters viaMUSCLE_FATIGUE_PARAMS.frame_skip (
int) – Number of physics steps per control step. Together withmj_model.opt.timestepthis defines the stored_dtused when dt is not provided tocompute_act().sex (
Optional[str]) – Optional sex specifier ("F"or"M") selects sex-specific rows inMUSCLE_FATIGUE_PARAMS.seed (
Optional[int]) – Random seed for stochastic resets viareset(fatigue_reset_random=True)()when nonp_randomgenerator is passed to it.use_uniform_params (
bool) – IfTrue, bypass per-muscle lookup and use the"Default_v2_4"row ofMUSCLE_FATIGUE_PARAMSfor all muscles: the single F/R/r of the legacy (v2.x) model, which the JAX model inmyo_sim.physics.fatigue_jaxalso uses.muscles (
Optional[Sequence[int|str]]) – Muscle actuators to track (ids or names), in the order the excitations are passed; default every muscle in model order.rest_threshold (
float) – CommandsTL <= rest_thresholdcount as rest, where the recovery multiplierrapplies. Raise it above the noise floor of estimated (e.g. tracked) excitations so that a relaxed muscle rests. Must lie in[0, 1).
- Raises:
ValueError – If rest_threshold is outside
[0, 1).
Example
>>> fatigue = CumulativeFatigue(mj_model, frame_skip=5) >>> ma, _, _ = fatigue.compute_act(excitation) >>> # or use the convenience wrapper: >>> eff = fatigue.step(excitation, dt=0.01)
- step(excitation, dt=None)
One control-step wrapper: returns effective muscle activation (MA).
For callers that just want the effective excitation after fatigue (e.g. MyoSuite’s
ModularTaskEnv).
- compute_act(act, dt=None)
Advance fatigue state by one step and return updated compartments.
The step is exact for any
dtunder a constant command (three_cc_r_step()).
- get_effort()
Return the effort
||MA - TL||of the lastcompute_act()call.Same as the legacy model and the JAX
get_effort: how far the active compartment falls short of (or exceeds) the commanded target load.- Return type:
- reset(fatigue_reset_vec=None, fatigue_reset_random=False, np_random=None)
Reset fatigue state.
- Parameters:
fatigue_reset_vec (
Optional[ndarray]) – If provided, set MF to this vector and MR = 1 - fatigue_reset_vec. Shape(na,). The vector is copied.fatigue_reset_random (
bool) – IfTrue, sample a random fatigue state. Cannot be combined with fatigue_reset_vec.np_random (
Optional[Generator]) – Generator for the random state, typically the env’s seedednp_randomso thatenv.reset(seed=...)is reproducible. Defaults to the model’s own RNG (seeseed()).
- Return type:
- state_dict()
Return serialisable snapshot of the fatigue compartments.
- load_state_dict(state)
Restore fatigue compartments from a
state_dict()snapshot.- Parameters:
state (
dict[str,list]) – Dict produced bystate_dict().- Return type:
- seed(seed=None)
Set random seed used by stochastic reset.
Same generator as
gymnasium.utils.seeding.np_random(seed).- Raises:
ValueError – If seed is not
Noneor a non-negativeint.- Return type:
- Parameters:
seed (int | None)
- property MA: ndarray
- property MF: ndarray
- property MR: ndarray
- property F: ndarray
- property R: ndarray
- property r: ndarray