Gymnasium Wrappers

Gymnasium wrappers for MyoSuite environments.

Available wrappers

MjInstabilityTerminationWrapper

Converts MuJoCo physics instability warnings into episode termination.

AttributeForwardingWrapper

Forwards public attributes (e.g. mj_render) to the wrapped env.

DictObservationWrapper

Exposes structured Dict observations instead of a flat Box vector.

PerturbationWrapper

Injects scheduled external forces/torques to named bodies for perturbation experiments (motor control, reactive balance, neuroscience lesion studies).

Muscle-command wrappers

None of them is active by default (a plain env runs only its own map): the myoFati*, myoReaf* and myoSarc* ids register the matching wrapper, and noise additionally needs a nonzero level. These install one ordered stage in the env’s action pipeline (see myosuite.envs.muscle_stages): map (env) -> noise -> fatigue -> reroute -> custom stages -> ctrl. The built-in order is fixed by the stage, whatever the wrapping order; custom stages run after them in installation order. Each stage can be installed once per env: a second wrapper of the same kind raises a ValueError (the myoFati* and myoReaf* ids already contain theirs, so wrap the base id to configure it, e.g. FatigueWrapper(make_env(base_id), fatigue_reset_random=True), or change the options with env.set_fatigue_reset_random(...) / env.set_motor_noise(...)).

MotorNoiseWrapper

Signal-dependent + constant Gaussian noise on the muscle excitations.

FatigueWrapper

3CC-r muscle fatigue (myoFati* envs).

ReafferentationWrapper

EIP command rerouted to EPL (myoReaf* envs).

SarcopeniaWrapper

Muscle force reduction applied to the model (myoSarc* envs).

ExcitationStageWrapper

A portable custom stage on the muscle excitations (filter, cap, gains, …) at an order of your choice; runs on the CPU env and on its mjlab twin.

CtrlStageWrapper

Like it, but env-aware and CPU only.

class myosuite.envs.wrappers.AttributeForwardingWrapper(env)

Bases: _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

Outermost wrapper of envs registered without an instability wrapper.

Parameters:

env (gym.Env)

class myosuite.envs.wrappers.MjInstabilityTerminationWrapper(env)

Bases: _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

Upgrade MuJoCo instability checks into termination after each step.

Parameters:

env (gym.Env)

step(action, **kwargs)

Uses the step() of the env that can be overwritten to change the returned data.

Return type:

tuple[Any, Any, Any, Any, Any]

Parameters:
class myosuite.envs.wrappers.DictObservationWrapper(env)

Bases: RecordConstructorArgs, ObservationWrapper

Expose structured observations as a gymnasium.spaces.Dict space.

MyoGymnasiumEnv flattens all observation terms into a single Box vector. This wrapper re-packages the env’s observation dict (the info["obs_dict"] of each step; recomputed with get_obs_dict() at reset, whose info carries none) into a proper Dict observation so that modular or hierarchical policies can consume named sub-observations directly without manual slicing. The Dict space is built at construction, so vector envs and SB3 see it before the first reset.

The action space and physics are unmodified.

Example:

env = make_env("myoElbowPose1D6MRandom-v0")
env = DictObservationWrapper(env)
obs, info = env.reset()
print(list(obs.keys()))  # ['qpos', 'qvel', 'pose_err']
print(obs["qpos"].shape)
Parameters:

env (Env) – A MyoGymnasiumEnv instance.

observation(obs)

Dict observation of the current state (obs is the flat vector).

Return type:

dict[str, ndarray]

Parameters:

obs (ndarray)

reset(**kwargs)

Modifies the env after calling reset(), returning a modified observation using self.observation().

Return type:

tuple[dict[str, ndarray], dict[str, Any]]

Parameters:

kwargs (Any)

step(action)

Modifies the env after calling step() using self.observation() on the returned observations.

Return type:

tuple[dict[str, ndarray], float, bool, bool, dict[str, Any]]

Parameters:

action (Any)

class myosuite.envs.wrappers.PerturbationWrapper(env)

Bases: RecordConstructorArgs, Wrapper

Apply scheduled external forces/torques to named bodies at runtime.

Enables perturbation-response experiments — reactive balance, motor adaptation, and neuroscience lesion studies — without modifying env source code. Perturbations are injected into MuJoCo’s data.xfrc_applied before each physics substep. Every step the wrapper rewrites the rows of the bodies it perturbs as the sum of the active perturbations (zero once none is active).

A perturbation is a dict with the following keys:

  • "body" (str) — MuJoCo body name.

  • "force" (array-like, shape (3,), optional) — world-frame force in N.

  • "torque" (array-like, shape (3,), optional) — world-frame torque in N·m.

  • "start" (int) — step index to begin applying (inclusive).

  • "end" (int, optional) — step index to stop (exclusive); -1 means apply forever. Defaults to -1.

Example:

env = make_env("myoLegWalk-v0")
env = PerturbationWrapper(env)

# Trip: lateral push to pelvis for two steps, starting at step 50
env.add_perturbation({
    "body": "pelvis",
    "force": [0, 200, 0],
    "start": 50,
    "end": 52,
})

obs, info = env.reset()
for _ in range(200):
    obs, r, term, trunc, info = env.step(env.action_space.sample())

# Selective muscle "lesion": zero a muscle by disabling its output
# (set via xfrc_applied; full muscle disable requires env modification).
Parameters:

env (Env) – A MyoGymnasiumEnv instance.

add_perturbation(perturbation)

Register a perturbation.

Parameters:

perturbation (dict[str, Any]) – Dict with keys body, force (optional), torque (optional), start, end (optional, default -1).

Return type:

None

clear_perturbations()

Remove all registered perturbations.

Return type:

None

reset(**kwargs)

Uses the reset() of the env that can be overwritten to change the returned data.

Return type:

tuple[Any, dict[str, Any]]

Parameters:

kwargs (Any)

step(action)

Uses the step() of the env that can be overwritten to change the returned data.

Return type:

tuple[Any, float, bool, bool, dict[str, Any]]

Parameters:

action (Any)

class myosuite.envs.wrappers.MotorNoiseWrapper(env, motor_noise=None)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

Gaussian motor noise on the muscle excitations (off by default).

The applied excitation is clip(u + signal_dependent_std * u * n1 + constant_std * n2, 0, 1) with independent standard normals per muscle and control step, drawn from the env’s seeded np_random after the env’s action-to-excitation map and before fatigue (see MotorNoiseCfg). A disabled config draws nothing, so the random stream of the env is unchanged.

Example:

env = MotorNoiseWrapper(
    make_env("myoElbowPose1D6MRandom-v0"), MotorNoiseCfg.van_beers_2004()
)
Parameters:
  • env (Env) – Env whose pipeline runs muscle stages.

  • motor_noise (Optional[Any]) – A MotorNoiseCfg, a dict of its fields or None (off). Call env.set_motor_noise(...) to change the levels during a run.

set_motor_noise(motor_noise)

Change the noise levels (a cfg, a dict of its fields or None: off).

Unlike assigning env.motor_noise, which only reaches this wrapper when it is the outermost one, the call is forwarded through the wrappers on top.

Return type:

None

Parameters:

motor_noise (Any)

class myosuite.envs.wrappers.FatigueWrapper(env, fatigue_reset_vec=None, fatigue_reset_random=False, muscles=None)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

3CC-r muscle fatigue on the muscle excitations.

The fatigue state (env.muscle_fatigue, a CumulativeFatigue) is reset with the env from its seeded np_random, at the place the env reset its muscle state.

Parameters:
  • env (Env) – Env whose pipeline runs muscle stages.

  • fatigue_reset_vec (Optional[Any]) – Initial fatigue (MF) of every muscle at reset, or None.

  • fatigue_reset_random (bool) – Draw a random initial fatigue at reset.

  • muscles (Optional[Any]) – Fatigue only these muscle actuators (names or ids; the rest pass unchanged), indexing the env’s actuator ctrl. Default: the env’s muscle excitations. The mjlab twin fatigues the same muscles.

set_fatigue_reset_random(fatigue_reset_random)

Randomise the fatigue state at every reset (or stop doing so).

Return type:

None

Parameters:

fatigue_reset_random (bool)

class myosuite.envs.wrappers.ReafferentationWrapper(env)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

Reafferentation: the command of EIP drives EPL and EIP is silenced.

Parameters:

env (gym.Env)

class myosuite.envs.wrappers.SarcopeniaWrapper(env, force_scale=0.5)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

Sarcopenia: scale the muscle forces of the env’s model (applied once, at wrapping).

Wrap an env once: a second SarcopeniaWrapper, or one on a myoSarc* id (which already has it), raises a ValueError instead of scaling the forces twice.

Parameters:
  • env (Env) – Env with a compiled model.

  • force_scale (float) – Factor on the maximum isometric muscle force.

Raises:

ValueError – If sarcopenia is already applied to the env.

class myosuite.envs.wrappers.ExcitationStageWrapper(env, make_stage)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

A portable custom stage on the muscle excitations: CPU env and mjlab twin.

The stage is an ExcitationStage (its name and optional order say where it runs: by default after the built-in stages, in installation order; see CtrlStageWrapper for the order scale). It sees the muscle excitations only and is written for numpy and torch, so the same registration configures both backends: the mjlab twin builds the stage from the same factory for every env of the scene. Two stages with the same explicit order raise a StageOrderWarning.

Example:

env = ExcitationStageWrapper(
    make_env("myoElbowPose1D6MRandom-v0"), functools.partial(LowPassStage, 0.3)
)
Parameters:
  • env (Env) – Env whose pipeline runs muscle stages.

  • make_stage (Callable[[], ExcitationStage]) – A zero-argument factory (a class, or functools.partial) that returns an ExcitationStage; use a module-level callable so that the wrapped env can be pickled.

class myosuite.envs.wrappers.CtrlStageWrapper(env, apply, name, order=None, reset=None)

Bases: _PicklableStage, _ForwardPublicAttributes, RecordConstructorArgs, Wrapper

An env-aware custom stage on the muscle excitations (CPU only).

The stage runs after the env’s action-to-excitation map and the built-in stages (noise 20, fatigue 30, reroute 40), right before ctrl is written, in the order the custom stages were installed. To insert it earlier give it an explicit order (the env’s map is 10 and the ctrl write 100). To act on the raw [-1, 1] action instead, use a plain gym.ActionWrapper on the outside.

Two stages with the same explicit order run in installation order and raise a StageOrderWarning. This stage gets the host env and so runs on the CPU only; for a stage that also runs on the mjlab twin, write an ExcitationStage and use ExcitationStageWrapper.

Example:

def rate_limit(env, ctrl):
    idx = env._stage_muscle_index()
    ctrl[idx] = np.clip(ctrl[idx], 0.0, 0.8)  # cap the excitation
    return ctrl

env = CtrlStageWrapper(make_env("myoElbowPose1D6MRandom-v0"), rate_limit,
                       name="cap")  # after the built-in stages; order=25 puts it after noise
Parameters:
  • env (Env) – Env whose pipeline runs muscle stages.

  • apply (Callable[[Any, ndarray], ndarray]) – apply(env, ctrl) -> ctrl with the host env and the excitation vector (edit it in place or return a new one). Use a module-level function so that the wrapped env can be pickled.

  • name (str) – A unique stage name (not one of the built-in names).

  • order (Optional[float]) – None (default): after the built-in stages, in installation order; or a priority strictly between 10 and 100 to insert it earlier.

  • reset (Optional[Callable[[Any], None]]) – Optional reset(env) called where the env resets its muscle state.

Raises:

ValueError – If the name is built-in or already installed, or an explicit order is out of range.

myosuite.envs.wrappers.condition_wrapper_specs(condition, **kwargs)

Registration wrapper specs of a muscle condition.

Parameters:
  • condition (str) – "sarcopenia", "fatigue" or "reafferentation".

  • **kwargs (Any) – Constructor arguments of the wrapper (JSON-serialisable).

Return type:

tuple[WrapperSpec, ...]

Returns:

One WrapperSpec, for the additional_wrappers of myosuite.core.registry.register_env().

Raises:

ValueError – If condition is unknown.

myosuite.envs.wrappers.wrapper_spec(wrapper, **kwargs)

Spec of a muscle-command wrapper, for EnvConfig.features or a registration.

Parameters:
  • wrapper (type) – A wrapper class of this module (MotorNoiseWrapper, …).

  • **kwargs (Any) – Its constructor arguments after the env.

Return type:

WrapperSpec

Returns:

The WrapperSpec.

myosuite.envs.wrappers.normalize_features(features)

Turn the entries of EnvConfig.features into wrapper specs.

Parameters:

features (Iterable[Any]) – Each entry is a WrapperSpec, a wrapper class (no arguments), or a (wrapper class, kwargs dict) pair.

Return type:

tuple[WrapperSpec, ...]

Returns:

The wrapper specs, in the given order.

Raises:

TypeError – If an entry has another form.

myosuite.envs.wrappers.apply_features(env, features)

Wrap env in the wrappers of features (the stage order is fixed, not the list’s).

Parameters:
Return type:

Env

Returns:

The wrapped env.