Metadata-Version: 2.4
Name: MyoSuite
Version: 3.1.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<4
Requires-Dist: Pillow>=13.0.0; python_version >= "3.11"
Requires-Dist: Pillow<13,>=12.3.0; python_version < "3.11"
Requires-Dist: filelock>=4.2.5; python_version >= "3.11"
Requires-Dist: colorednoise>=2.2.0
Requires-Dist: packaging
Requires-Dist: ml-collections>=0.1.1
Requires-Dist: myo-sim==0.2.5
Requires-Dist: onnxruntime<1.21; python_version < "3.14"
Requires-Dist: onnxruntime>=1.24.1; python_version >= "3.14" and python_version < "3.15"
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: onnx
Requires-Dist: onnxruntime<1.21; python_version < "3.14" and extra == "onnx"
Requires-Dist: onnxruntime>=1.24.1; python_version >= "3.14" and extra == "onnx"
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<4,>=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: warp-lang>=1.11; (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<4,>=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>=26.10.1; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: license-file

<!-- =================================================
# Copyright (c) MyoSuite Authors
================================================= -->
<img src="https://raw.githubusercontent.com/MyoHub/myosuite/main/docs/source/images/Full%20Color%20Horizontal%20wider.png" 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://img.shields.io/readthedocs/myosuite/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](https://github.com/MyoHub/myosuite/tree/dev/tutorials) · [Task list](https://myosuite.readthedocs.io/en/latest/environments.html)

<img width="1240" alt="MyoSuite tasks" src="https://raw.githubusercontent.com/MyoHub/myosuite/main/docs/source/images/MyoSuiteHeader.png">


<details> <summary><strong><big>What's new in MyoSuite 3</big></strong></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 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 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.11 --extra rl`.

From PyPI: `pip install -U myosuite`.

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.
