Physics & Biomechanics

Biomechanics and physics utilities for MyoSuite environments.

Available classes

CumulativeFatigue

NumPy implementation of the 3CC-r cumulative muscle fatigue model (Xia & Frey Law, 2008). Backend: CPU (numpy).

CumulativeFatigueJax

JAX-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 — NumPy

  • myosuite.physics.quat_math_jax — JAX / MJX

  • myosuite.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: object

3CC-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 r acts only at rest, as in Rakshit et al. (2021, Eqs. 1, 3 and 7; their k is r here): dMR/dt = -C(t) + r(k, TL) x R x MF, dMF/dt = F x MA - r(k, TL) x R x MF with r = k if TL = 0 and r = 1 if TL > 0. Rest is TL <= rest_threshold (default FATIGUE_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 via MUSCLE_FATIGUE_PARAMS.

  • frame_skip (int) – Number of physics steps per control step. Together with mj_model.opt.timestep this defines the stored _dt used when dt is not provided to compute_act().

  • sex (Optional[str]) – Optional sex specifier ("F" or "M") selects sex-specific rows in MUSCLE_FATIGUE_PARAMS.

  • seed (Optional[int]) – Random seed for stochastic resets via reset(fatigue_reset_random=True)() when no np_random generator is passed to it.

  • use_uniform_params (bool) – If True, bypass per-muscle lookup and use the "Default_v2_4" row of MUSCLE_FATIGUE_PARAMS for all muscles: the single F/R/r of the legacy (v2.x) model, which the JAX model in myo_sim.physics.fatigue_jax also 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) – Commands TL <= rest_threshold count as rest, where the recovery multiplier r applies. 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).

Parameters:
  • excitation (ndarray) – Commanded muscle excitations, shape (na,).

  • dt (Optional[float]) – Control timestep in seconds. If None, uses self._dt.

Return type:

ndarray

Returns:

Effective excitation (= MA after update), shape (na,).

compute_act(act, dt=None)

Advance fatigue state by one step and return updated compartments.

The step is exact for any dt under a constant command (three_cc_r_step()).

Parameters:
  • act (ndarray) – Target activation (commanded excitation), shape (na,).

  • dt (Optional[float]) – Timestep in seconds. Defaults to self._dt.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

(MA, MR, MF) — updated active, resting, and fatigued compartments, each shape (na,).

get_effort()

Return the effort ||MA - TL|| of the last compute_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:

float

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) – If True, 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 seeded np_random so that env.reset(seed=...) is reproducible. Defaults to the model’s own RNG (see seed()).

Return type:

None

state_dict()

Return serialisable snapshot of the fatigue compartments.

Return type:

dict[str, list]

Returns:

Dict with keys "MA", "MR", "MF", each a flat list of length na.

load_state_dict(state)

Restore fatigue compartments from a state_dict() snapshot.

Parameters:

state (dict[str, list]) – Dict produced by state_dict().

Return type:

None

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 None or a non-negative int.

Return type:

list[int]

Parameters:

seed (int | None)

property n_muscles: int
property MA: ndarray
property MF: ndarray
property MR: ndarray
property F: ndarray
property R: ndarray
property r: ndarray
property rest_threshold: float
set_FatigueCoefficient(F)
Return type:

None

Parameters:

F (float | ndarray)

set_RecoveryCoefficient(R)
Return type:

None

Parameters:

R (float | ndarray)

set_RecoveryMultiplier(r)
Return type:

None

Parameters:

r (float | ndarray)

set_RestThreshold(rest_threshold)

Set the command at or below which a muscle rests (see rest_threshold).

Return type:

None

Parameters:

rest_threshold (float)