msgym

KO | EN

gitlite — search

#python #hacktoberfest #react #ai #android #rust #linux #macos #java #kubernetes #security #pytorch #ios #open-source

(★ 34)

Gymnasium Environments for MusculoSkeletal Models

msgym Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# msgym: Gymnasium Environments for MusculoSkeletal Models

[Gymnasium](https://gymnasium.farama.org/) environments for the **MS-Human-700** full-body human musculoskeletal model in [MuJoCo](https://mujoco.readthedocs.io/). 
This repository provides reinforcement learning–ready simulation environments for locomotion and manipulation tasks.

<p align="center">
  <a href="https://lnsgroup.cc/research/MS-Human">Project Page</a> | <a href="https://github.com/LNSGroup/MS-Human-700">MS-Human-700 Model</a>
</p>

## Overview

MS-Human-700 is a whole-body human musculoskeletal model with anatomically detailed body, joint, and muscle parameters. It includes 700 muscle–tendon units.

Related papers:
- [MS-Human-700 (ICRA 2024)](https://arxiv.org/abs/2312.05473)
- [DynSyn (ICML 2024)](https://arxiv.org/abs/2407.11472)
- [MPC2 (ICLR 2025)](https://arxiv.org/abs/2505.08238)
- [QFlex (ICLR 2026)](https://arxiv.org/abs/2601.19707)
- [and more (on balance & fall, contact-rich & deformable, vision language model ...)](https://lnsgroup.cc/research/MS-Human#papers)

This repository wraps MS-Human-700 as a Python package **msgym** so you can use it with `gymnasium.make()` after a standard install.

## Installation

### 1. Clone the repository with submodules

The MuJoCo model and assets live in the **MS-Human-700** submodule. Clone with recursion so it is included:

```bash
git clone https://github.com/LNSGroup/msgym.git --recursive 
cd msgym
```

If you already cloned without `--recursive`, initialize and update submodules:

```bash
git submodule update --init --recursive
```

### 2. Install the package

We recommend using [uv](https://github.com/astral-sh/uv) for fast dependency management (Python 3.12 by default):

```bash
uv python pin 3.12
uv sync
uv pip install -e .
```

After this, `import msgym` and `gymnasium.make("msgym/...")` work in your environment.

### Optional: DynSyn-SAC training

For [DynSyn](https://lnsgroup.cc/research/DynSyn) reinforcement learning training, install the optional dependency set.

```bash
uv sync --extra dynsyn
```

## Usage

Environments are registered with Gymnasium on `import msgym`. Use them as follows:

```python
import gymnasium as gym
import msgym

env = gym.make("msgym/LocomotionFullEnv-v1", render_mode="human", gait_cycles=5)
obs, info = env.reset()
# ... step, render
env.close()
```

**Registered environment IDs:**

| Environment ID                    | Description                          |
|-----------------------------------|--------------------------------------|
| `msgym/LocomotionFullEnv-v1`      | Full-body locomotion imitation       |
| `msgym/LocomotionLegsEnv-v1`      | Legs-only locomotion imitation       |
| `msgym/ManipulationEnv-v1`         | Right-arm manipulation (grasp/lift)   |

Run the test script from the repo root:

```bash
uv run python env_test.py
```

> **Headless / no display:**  
> 1. Use `render_mode="rgb_array"` (or omit rendering).  
> 2. For offscreen rendering, set `MUJOCO_GL=egl` (e.g. `export MUJOCO_GL=egl` or `$env:MUJOCO_GL="egl"` on Windows).

## Training (DynSyn-SAC)

Controllers can be trained with the DynSyn-SAC algorithm.

**Training:**

```bash
CUDA_VISIBLE_DEVICES=0 MUJOCO_GL=egl uv run python DynSyn-SAC/SB3-Scripts/train.py -f DynSyn-SAC/configs/locomotionFull.json
```

**Evaluation:**

```bash
CUDA_VISIBLE_DEVICES=0 MUJOCO_GL=egl uv run python DynSyn-SAC/SB3-Scripts/eval.py -f DynSyn-SAC/logs/LocomotionFull
```

Trained checkpoints are available from GitHub Releases.

## License

This project is released under the [Apache-2.0 License](LICENSE).

## Citation

If you use MS-Human-700 or msgym, please cite our ICRA 2024 paper and other related ones.

```bibtex
@inproceedings{zuo2024self,
  title={Self model for embodied intelligence: Modeling full-body human musculoskeletal system and locomotion control with hierarchical low-dimensional representation},
  author={Zuo, Chenhui and He, Kaibo and Shao, Jing and Sui, Yanan},
  booktitle={2024 IEEE International Conference on Robotics and Automation (ICRA)},
  pages={13062--13069},
  year={2024},
  organization={IEEE}
}
```

## Control Demos

[**DynSyn**](https://lnsgroup.cc/research/DynSyn) control results:

[**QFlex**](https://lnsgroup.cc/research/Qflex) control results:

**High-Fidelity Motion Tracking** results:

Leveraging MuJoCo Warp for massively parallel **GPU** simulation enables the rapid and efficient training of control policies capable of high-precision motion tracking across diverse and dynamic trajectories.

The demos below illustrate these tracking capabilities of the MS-Human model:
*   **Overlap**: The model and reference trajectory are rendered directly to visualize tracking accuracy.
*   **Separate**: The model and reference trajectory are rendered with an offset to showcase motion details.

<table>
  <tr>
    <td align="center" width="25%">
      <img src="https://github.com/user-attachments/assets/0350ff08-2ab3-4019-a4be-bef6fbc276ad" alt="running_overlap" width="100%"><br>
      Running: Overlap
    </td>
    <td align="center" width="25%">
      <img src="https://github.com/user-attachments/assets/16084e8c-41f5-45a3-96b7-b69307c78e0c" alt="running_separate" width="100%"><br>
      Running: Separate
    </td>
  </tr>
  <tr>
    <td align="center" width="25%">
      <img src="https://github.com/user-attachments/assets/9aea44e9-3277-4d81-a096-6865e2dcc5e4" alt="walking_ovelap" width="100%"><br>
      Walking: Overlap
    </td>
    <td align="center" width="25%">
      <img src="https://github.com/user-attachments/assets/9c32033c-0ca6-4b0c-a6fd-f61f66481ee9" alt="walking_separate" width="100%"><br>
      Walking: Separate
    </td>
  </tr>
</table>

msgym

msgym Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

msgym

msgym Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README