Metadata-Version: 2.4
Name: MyoSuite
Version: 3.0.0
Summary: Musculoskeletal environments simulated in MuJoCo
Author-email: Vittorio Caggiano <caggiano@gmail.com>, Balint Hodossy <hodossy@gmail.com>, Florian Fischer <florian.fischer26@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.myosuite.org
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.3
Requires-Dist: imageio[ffmpeg]
Requires-Dist: gymnasium<1.3
Requires-Dist: termcolor
Requires-Dist: flatten_dict
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: osqp
Requires-Dist: mujoco
Requires-Dist: Pillow>=10.1.0
Requires-Dist: colorednoise>=2.2.0
Requires-Dist: packaging
Requires-Dist: ml-collections>=0.1.1
Requires-Dist: myo-sim==0.2.3
Requires-Dist: onnxruntime<1.21; python_version < "3.14"
Requires-Dist: onnxruntime>=1.24.1; python_version >= "3.14"
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: joblib>=1.5.3
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mjviser>=0.0.14
Requires-Dist: loop-rate-limiters>=1.2.0
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: rl
Requires-Dist: stable-baselines3>=2.7.1; extra == "rl"
Requires-Dist: matplotlib>=3.9.0; extra == "rl"
Requires-Dist: joblib>=1.5.3; extra == "rl"
Requires-Dist: scikit-learn>=1.6.1; extra == "rl"
Requires-Dist: wandb>=0.25.0; extra == "rl"
Requires-Dist: tensorboard>=2.20.0; extra == "rl"
Provides-Extra: examples
Requires-Dist: mink; (python_version >= "3.10" and python_version < "3.14") and extra == "examples"
Requires-Dist: mink>=1.3.0; python_version >= "3.14" and extra == "examples"
Provides-Extra: mjlab
Requires-Dist: torch>=2.13.0; python_version >= "3.10" and extra == "mjlab"
Requires-Dist: mjlab>=1.4.0; (python_version >= "3.10" and python_version < "3.14") and extra == "mjlab"
Requires-Dist: mujoco-warp>=3.7.0; (python_version >= "3.10" and python_version < "3.14") and extra == "mjlab"
Requires-Dist: warp-lang>=1.12.0; python_version >= "3.10" and extra == "mjlab"
Requires-Dist: wandb<0.29.0,>=0.22.3; (python_version >= "3.10" and python_version < "3.14") and extra == "mjlab"
Provides-Extra: mjx
Requires-Dist: jax<0.5.3,>=0.4.20; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: jaxlib<0.5.3,>=0.4.20; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: brax>=0.10.0; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: flax>=0.8.0; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: optax>=0.1.7; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: orbax-checkpoint<0.11.24,>=0.11.22; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: ml-collections>=0.1.1; (python_version >= "3.10" and sys_platform != "win32" and sys_platform != "darwin") and extra == "mjx"
Requires-Dist: etils[epath]>=1.3.0; (python_version >= "3.10" and sys_platform != "win32") and extra == "mjx"
Requires-Dist: playground>=0.0.5; (python_version >= "3.10" and sys_platform != "win32") and extra == "mjx"
Requires-Dist: mediapy>=1.2.0; (python_version >= "3.10" and sys_platform != "win32") and extra == "mjx"
Requires-Dist: imageio>=2.31.0; (python_version >= "3.10" and sys_platform != "win32") and extra == "mjx"
Requires-Dist: wandb>=0.21.0; (python_version >= "3.10" and sys_platform != "win32") and extra == "mjx"
Requires-Dist: mujoco>=3.7; extra == "mjx"
Requires-Dist: mujoco-mjx>=3.7; extra == "mjx"
Provides-Extra: mjx-cuda
Requires-Dist: myosuite[mjx]; extra == "mjx-cuda"
Requires-Dist: jax[cuda12]<0.5.3,>=0.4.30; (python_version >= "3.10" and sys_platform != "darwin") and extra == "mjx-cuda"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Provides-Extra: musclemimic
Requires-Dist: musclemimic_models==1.0.6; extra == "musclemimic"
Requires-Dist: huggingface_hub>=0.20; extra == "musclemimic"
Requires-Dist: scikit-learn>=1.6.1; extra == "musclemimic"
Requires-Dist: joblib>=1.4.0; extra == "musclemimic"
Provides-Extra: dev
Requires-Dist: myosuite[rl]; extra == "dev"
Requires-Dist: myosuite[musclemimic]; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-xvfb; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

<!-- =================================================
# Copyright (c) MyoSuite Authors
================================================= -->
<img src="https://github.com/myohub/myosuite/blob/main/docs/source/images/Full%20Color%20Horizontal%20wider.png?raw=true" width=800>

[![Support Ukraine](https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat&labelColor=005BBB)](https://opensource.facebook.com/support-ukraine)
[![PyPI](https://img.shields.io/pypi/v/myosuite)](https://pypi.org/project/MyoSuite/)
[![Documentation Status](https://readthedocs.org/projects/myosuite/badge/?version=latest)](https://myosuite.readthedocs.io/en/latest/)
![PyPI - License](https://img.shields.io/pypi/l/myosuite)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/myohub/myosuite/blob/main/docs/CONTRIBUTING.md)
[![Downloads](https://static.pepy.tech/badge/myosuite)](https://pepy.tech/project/myosuite)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/MyoHub/myosuite/blob/main/tutorials/1.1_Get_Started.ipynb)
[![Slack](https://img.shields.io/badge/Slack-4A154B?style=for-the-badge&logo=slack&logoColor=white)](https://join.slack.com/t/myosuite/shared_invite/zt-1zkpw2zzk-NhVhVlSDxhoMHbzROD8gMA)
[![Twitter Follow](https://img.shields.io/twitter/follow/MyoSuite?style=social)](https://twitter.com/MyoSuite)

**MyoSuite** is a collection of musculoskeletal environments and tasks simulated with the [MuJoCo](http://www.mujoco.org/) physics engine. It serves researchers and practitioners across biomechanics, neuroscience, machine learning, sports medicine, and physical rehabilitation.

[Documentation](https://myosuite.readthedocs.io/en/latest/) · [Tutorials](tutorials/) · [Task list](https://myosuite.readthedocs.io/en/latest/environments.html)

<img width="1240" alt="TasksALL" src="./docs/source/images/MyoSuiteHeader.png?raw=true">


<details>
  <summary><h2>What's new in MyoSuite 3</h2></summary>

MyoSuite 3 brings the whole suite to fast, scalable training while keeping the simple interface you know:

- **Much faster learning.** Train with thousands of environments in parallel on a single GPU, then replay the policy on the CPU.
- **One task, several backends.** The same `env_id` runs on your **CPU** through the standard [Gymnasium](https://gymnasium.farama.org/) interface (to explore, debug and replay policies, or to train with libraries such as Stable-Baselines3), on **mjlab** for massively parallel GPU training, and on an **experimental MJX** (JAX) path.
- **Muscle conditions as features.** Motor noise, fatigue, sarcopenia and reafferentation are wrappers, not env arguments. `make_env(EnvConfig(env_id, features=...))` applies them identically on the CPU env and the GPU twin, together with the episode length and control step ([cross-backend contract](docs/wiki/cross-backend-contract.md)).
- **MuscleMimic support.** Run, evaluate and train full-body and bimanual **MuscleMimic** policies, with ready-to-use checkpoints and motion datasets.
- **Updated musculoskeletal models.** `myo-sim` moved from a moving `dev` branch to a pinned PyPI release (0.2.3) with some model updates, including a torso/pelvis frame fix for the leg models ([myo_sim#132](https://github.com/MyoHub/myo_sim/pull/132)).
- **The complete MyoChallenge suite** as Gymnasium environments: Baoding, Bimanual, Chase Tag, Die Reorient, OSL Run, Relocate, Soccer and Table Tennis.
- **New tasks in a few lines.** Describe a task with a compact spec and reuse the shared observation, reward and model-building blocks instead of writing an environment class.
- **Some existing environments changed.** Observations are no longer clipped and are read after a fresh forward step (55 env ids), the `motorFinger*` envs have 4x stronger motors, the Random finger-reach tasks now sample only targets the fingertip can reach, and several reset and seed behaviours were corrected. Policies trained with MyoSuite 2.x or earlier snapshots may need retraining; see [`CHANGELOG.md`](CHANGELOG.md) for the full list.
- **Ready to use.** Default trained policies on [Hugging Face](https://huggingface.co/myohub/myosuite-3-baselines) (see [`docs/baseline_checkpoints.md`](docs/baseline_checkpoints.md) for the full list and success rates) with evaluation videos, plus updated tutorials from the first rollout to GPU training and MuscleMimic. See the [changelog](CHANGELOG.md) for everything that changed since v2.12.
</details>

## Start here

| I am a…                    | Start here                                                   |
| --------------------------- | ------------------------------------------------------------ |
| **ML / RL**           | [ML guide](docs/source/quickstart_ml.rst)                     |
| **Biomechanics**      | [Biomechanics guide](docs/source/quickstart_biomechanics.rst) |
| **Neuroscience**      | [Neuroscience guide](docs/source/quickstart_neuroscience.rst) |
| **Rehab / sports**    | [Rehab guide](docs/source/quickstart_rehabilitation.rst)      |
| **Changing the code** | [Developer getting started](docs/wiki/getting-started.md)     |


## Install

Python 3.10–3.14 is supported (the GPU `[mjlab]` extra needs Python ≤3.13). From source (recommended):

```bash
git clone https://github.com/MyoHub/myosuite.git
cd myosuite
pip install -e ".[rl]"          # CPU training (Stable-Baselines3)
# uv pip install -e ".[mjlab]" --torch-backend=auto   # GPU (NVIDIA, Linux or Windows), picks the torch
                                 # build for your driver; with pip see docs/source/install.rst
```

Or: `uv sync -p 3.10 --extra rl`.

From PyPI: `pip install -U myosuite`.

**Models.** The musculoskeletal models ship in the `myo-sim` package, pinned to 0.2.3 and installed from PyPI together with MyoSuite, so no git submodules and no separate model install are needed. The few MPL, YCB and furniture assets the tasks use are bundled in `myosuite/envs/myo/assets/`. Environments compose their models with `ModelBuilder` (see the [model builder guide](docs/source/model_builder.rst)). A different `myo-sim` version can change joints and ranges (the thumb joints did in 0.2.0), so the baseline policies are only valid for the pinned version.

Verify (replace "onscreen" with "offscreen" when running on a remote, headless machine):

```bash
python -c "import myosuite; print(len(myosuite.myosuite_env_suite), 'envs')"
python -m myosuite.utils.examine_env --env_name myoElbowPose1D6MRandom-v0 --render onscreen
# macOS viewer: mjpython -m myosuite.utils.examine_env --env_name myoElbowPose1D6MRandom-v0 --render onscreen
```

Run these from a directory that does not directly contain a folder named `myosuite` (for example not the parent of your clone); otherwise Python imports that folder as a namespace package and fails with `cannot import name ... from 'myosuite' (unknown location)`.


## Quick start

```python
from myosuite import make_env

env = make_env("myoElbowPose1D6MRandom-v0")
obs, info = env.reset(seed=0)
for _ in range(1000):
    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    if terminated or truncated:
        obs, info = env.reset()
env.close()
```

`info["obs_dict"]` and `info["rwd_dict"]` break down the observation and reward every step.

Train on CPU:

```python
from stable_baselines3 import PPO
from myosuite import make_env

env = make_env("myoElbowPose1D6MRandom-v0")
model = PPO("MlpPolicy", env, device="cpu")
model.learn(total_timesteps=100_000)
```

Or use the ready-made script (PPO, SAC or TD3; saves the model and scores the policy at the end):

```bash
python scripts/train_sb3.py myoElbowPose1D6MRandom-v0 --timesteps 500000
```

Train on GPU (same `env_id`, mjlab / RSL-RL):

```bash
python scripts/train_mjlab.py myoElbowPose1D6MRandom-v0 --env.scene.num-envs 1024
```

No step count is needed: it runs the task's default number of PPO iterations (`--agent.max-iterations`, 1000 unless the task sets another) and stops early once the deterministic policy reaches 95% success (`--stop-on-success False` turns that off).

The same call builds either backend, and an `EnvConfig` overrides the registered defaults (episode length, control step,
muscle-command features such as motor noise and fatigue) for both:

```python
from myosuite import make_env
from myosuite.core.config import EnvConfig
from myosuite.envs.wrappers import FatigueWrapper, MotorNoiseWrapper

env_cpu = make_env("myoElbowPose1D6MRandom-v0")                               # CPU, registered defaults
env_gpu = make_env("myoElbowPose1D6MRandom-v0", backend="mjlab", num_envs=1024)  # GPU twin (needs the mjlab extra)

cfg = EnvConfig(
    "myoElbowPose1D6MRandom-v0",
    max_episode_steps=300,
    features=((MotorNoiseWrapper, {"motor_noise": {"constant_std": 0.05}}), FatigueWrapper),
)
env_cpu = make_env(cfg)                               # CPU with noise and fatigue
env_gpu = make_env(cfg, backend="mjlab", num_envs=1024)  # the same on the GPU
```

Muscle-condition variants of an env are separate ids with a prefix: `myoSarcElbowPose1D6MRandom-v0` (sarcopenia), `myoFatiElbowPose1D6MRandom-v0` (fatigue), `myoReafHandPoseRandom-v0` (reafferentation). Each is the base env registered with the matching wrapper; to use these features (noise, fatigue, ...) on any env, or to register your own variant, see the [neuroscience guide](docs/source/quickstart_neuroscience.rst) (examples) and the [cross-backend contract](docs/wiki/cross-backend-contract.md#muscle-command-features-wrappers) (how features are registered and which envs and backends support them).



## Environments

| Body      | Example IDs                                                     |
| --------- | --------------------------------------------------------------- |
| Elbow     | `myoElbowPose1D6MRandom-v0`, `myoFatiElbowPose1D6MRandom-v0` |
| Finger    | `myoFingerPoseRandom-v0`, `myoFingerReachRandom-v0`         |
| Hand      | `myoHandPoseRandom-v0`, `myoChallengeBaodingP2-v1`          |
| Arm       | `myoArmReachRandom-v0`                                        |
| Leg       | `myoLegWalk-v0`, `myoLegDirectionalForward-v0`              |
| Full body | `myoMimicFullbody-v0`                                         |

List every registered CPU ID: `python -c "import myosuite; print('\n'.join(myosuite.myosuite_env_suite))"`. Annotated catalog: [environments](https://myosuite.readthedocs.io/en/latest/environments.html).

### Backends

| Backend | Use | Build an env in Python | Train |
| --- | --- | --- | --- |
| **CPU** (Gymnasium) | playback, debug, SB3 | `make_env(env_id)` | `scripts/train_sb3.py <env_id>` (PPO, SAC or TD3) |
| **mjlab** (MuJoCo Warp) | parallel GPU training | `make_env(env_id, backend="mjlab", num_envs=...)` | `scripts/train_mjlab.py <env_id>` |

The mjlab backend needs `pip install -e ".[mjlab]"`. `make_env` only builds the env (to step it, evaluate a policy or write your own training loop); `scripts/train_sb3.py` (CPU) and `scripts/train_mjlab.py` (GPU) are the ready-made training scripts.

A task’s CPU and mjlab halves share one `env_id` (see [cross-backend contract](docs/wiki/cross-backend-contract.md)). `make_env(EnvConfig(env_id, backend=..., features=...))` builds either half with the same episode length, control step and muscle-command features. An MJX (JAX) path also exists; it is **experimental** and not the supported training route.


## Tutorials

All notebooks are listed, with what each needs, in the [tutorial index](tutorials/README.md).

Start with [1.1 Get Started](tutorials/1.1_Get_Started.ipynb), then [2.1 Train SB3 Policy](tutorials/2.1_Train_SB3_Policy.ipynb) (CPU).

GPU walk-through: [2.2 Train MjLab Policy](tutorials/2.2_Train_MjLab_Policy.ipynb).

Full-body MuscleMimic: [5.1 Load Policy](tutorials/5.1_Fullbody_Load_Policy.ipynb) (playback) and [5.3 Train with mjlab](tutorials/5.3_Fullbody_Train_MjLab_Policy.ipynb); background, data and checkpoints in the [MuscleMimic README](myosuite/integrations/musclemimic/README.md).


## License

[Apache License](LICENSE).

## Citation

If you use MyoSuite, please cite the MyoSuite paper:

```bibtex
@inproceedings{Caggiano2022MyoSuite,
  title     = {{MyoSuite} -- A contact-rich simulation suite for musculoskeletal motor control},
  author    = {Caggiano, Vittorio and Wang, Huawei and Durandau, Guillaume and Sartori, Massimo and Kumar, Vikash},
  booktitle = {Learning for Dynamics and Control (L4DC)},
  year      = {2022},
  doi       = {10.48550/ARXIV.2205.13600},
  url       = {https://arxiv.org/abs/2205.13600},
}
```

For MyoSuite 3 (the GPU backends, the muscle conditions, the MyoChallenge envs), cite it as software:

```bibtex
@misc{MyoSuite2026,
  title        = {{MyoSuite} 3.0 -- A multimodal platform for efficient and scalable musculoskeletal motor control},
  author       = {Caggiano, Vittorio and Hodossy, Balint and Fischer, Florian and Wang, Cheryl and {MyoSuite Team}},
  year         = {2026},
  howpublished = {\url{https://github.com/myohub/myosuite}},
}
```

If you use the full-body MuscleMimic models, checkpoints, retargeted motions or tutorials 5.1-5.5, also cite:

```bibtex
@article{Li2026MuscleMimic,
  title   = {Towards Embodied AI with {MuscleMimic}: Unlocking full-body musculoskeletal motor learning at scale},
  author  = {Li, Chengkun and Wang, Cheryl and Ziliotto, Bianca and Simos, Merkourios and Kovecses, Jozsef and Durandau, Guillaume and Mathis, Alexander},
  journal = {arXiv preprint arXiv:2603.25544},
  year    = {2026},
}
```

The motion data behind MuscleMimic comes from [AMASS](https://amass.is.tue.mpg.de) (Mahmood et al., ICCV 2019), whose
KIT subset (Mandery et al., 2015, 2016) provides the locomotion clips, retargeted with GMR (Araújo et al., 2025). The
retargeted datasets are for non-commercial research under the AMASS license and ask you to cite AMASS and MuscleMimic.

Further papers use or build on MyoSuite: MyoSim (ICRA 2022), MyoDex (ICML 2023), SAR (RSS 2023), MyoChallenge 2022,
DEP-RL (ICLR 2023), Lattice (NeurIPS 2023), MyoInteract (DIS 2026, a GUI framework for prototyping
biomechanical HCI tasks on top of MyoSuite) and the Virtual Gait Lab for testing prosthetics with simulated
users (IEEE T-MRB 2026). The sources behind the models, the muscle fatigue model, the
controllers and the motion data are collected in [`docs/source/references.rst`](docs/source/references.rst) (page
*References* of the documentation); `CITATION.cff` holds the machine-readable citation.
