Gymnasium Wrappers
Gymnasium wrappers for MyoSuite environments.
Available wrappers
MjInstabilityTerminationWrapperConverts MuJoCo physics instability warnings into episode termination.
AttributeForwardingWrapperForwards public attributes (e.g.
mj_render) to the wrapped env.DictObservationWrapperExposes structured
Dictobservations instead of a flatBoxvector.PerturbationWrapperInjects 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(...)).
MotorNoiseWrapperSignal-dependent + constant Gaussian noise on the muscle excitations.
FatigueWrapper3CC-r muscle fatigue (
myoFati*envs).ReafferentationWrapperEIP command rerouted to EPL (
myoReaf*envs).SarcopeniaWrapperMuscle force reduction applied to the model (
myoSarc*envs).ExcitationStageWrapperA 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.
CtrlStageWrapperLike it, but env-aware and CPU only.
- class myosuite.envs.wrappers.AttributeForwardingWrapper(env)
Bases:
_ForwardPublicAttributes,RecordConstructorArgs,WrapperOutermost wrapper of envs registered without an instability wrapper.
- Parameters:
env (gym.Env)
- class myosuite.envs.wrappers.MjInstabilityTerminationWrapper(env)
Bases:
_ForwardPublicAttributes,RecordConstructorArgs,WrapperUpgrade MuJoCo instability checks into termination after each step.
- Parameters:
env (gym.Env)
- class myosuite.envs.wrappers.DictObservationWrapper(env)
Bases:
RecordConstructorArgs,ObservationWrapperExpose structured observations as a
gymnasium.spaces.Dictspace.MyoGymnasiumEnv flattens all observation terms into a single
Boxvector. This wrapper re-packages the env’s observation dict (theinfo["obs_dict"]of each step; recomputed withget_obs_dict()at reset, whose info carries none) into a properDictobservation so that modular or hierarchical policies can consume named sub-observations directly without manual slicing. TheDictspace 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) – AMyoGymnasiumEnvinstance.
- observation(obs)
Dict observation of the current state (obs is the flat vector).
- class myosuite.envs.wrappers.PerturbationWrapper(env)
Bases:
RecordConstructorArgs,WrapperApply 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_appliedbefore 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);-1means 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.
- class myosuite.envs.wrappers.MotorNoiseWrapper(env, motor_noise=None)
Bases:
_PicklableStage,_ForwardPublicAttributes,RecordConstructorArgs,WrapperGaussian 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 seedednp_randomafter the env’s action-to-excitation map and before fatigue (seeMotorNoiseCfg). 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]) – AMotorNoiseCfg, a dict of its fields orNone(off). Callenv.set_motor_noise(...)to change the levels during a run.
- class myosuite.envs.wrappers.FatigueWrapper(env, fatigue_reset_vec=None, fatigue_reset_random=False, muscles=None)
Bases:
_PicklableStage,_ForwardPublicAttributes,RecordConstructorArgs,Wrapper3CC-r muscle fatigue on the muscle excitations.
The fatigue state (
env.muscle_fatigue, aCumulativeFatigue) is reset with the env from its seedednp_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, orNone.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 actuatorctrl. Default: the env’s muscle excitations. The mjlab twin fatigues the same muscles.
- class myosuite.envs.wrappers.ReafferentationWrapper(env)
Bases:
_PicklableStage,_ForwardPublicAttributes,RecordConstructorArgs,WrapperReafferentation: 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,WrapperSarcopenia: scale the muscle forces of the env’s model (applied once, at wrapping).
Wrap an env once: a second
SarcopeniaWrapper, or one on amyoSarc*id (which already has it), raises aValueErrorinstead of scaling the forces twice.- Parameters:
- Raises:
ValueError – If sarcopenia is already applied to the env.
- class myosuite.envs.wrappers.ExcitationStageWrapper(env, make_stage)
Bases:
_PicklableStage,_ForwardPublicAttributes,RecordConstructorArgs,WrapperA portable custom stage on the muscle excitations: CPU env and mjlab twin.
The stage is an
ExcitationStage(itsnameand optionalordersay where it runs: by default after the built-in stages, in installation order; seeCtrlStageWrapperfor 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 aStageOrderWarning.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, orfunctools.partial) that returns anExcitationStage; 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,WrapperAn 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
ctrlis written, in the order the custom stages were installed. To insert it earlier give it an explicitorder(the env’s map is 10 and thectrlwrite 100). To act on the raw[-1, 1]action instead, use a plaingym.ActionWrapperon 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 anExcitationStageand useExcitationStageWrapper.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) -> ctrlwith 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]]) – Optionalreset(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:
- Return type:
- Returns:
One
WrapperSpec, for theadditional_wrappersofmyosuite.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.featuresor a registration.- Parameters:
- Return type:
- Returns:
The
WrapperSpec.
- myosuite.envs.wrappers.normalize_features(features)
Turn the entries of
EnvConfig.featuresinto wrapper specs.- Parameters:
features (
Iterable[Any]) – Each entry is aWrapperSpec, a wrapper class (no arguments), or a(wrapper class, kwargs dict)pair.- Return type:
- 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:
env (
Env) – A CPU env (as made bymake_env).features (
Iterable[WrapperSpec]) – Wrapper specs, e.g. fromwrapper_spec().
- Return type:
- Returns:
The wrapped env.