msgym: Gymnasium Environments for MusculoSkeletal Models

Gymnasium environments for the MS-Human-700 full-body human musculoskeletal model in MuJoCo. This repository provides reinforcement learning–ready simulation environments for locomotion and manipulation tasks.

Project Page | MS-Human-700 Model

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)
• DynSyn (ICML 2024)
• MPC2 (ICLR 2025)
• QFlex (ICLR 2026)
• and more (on balance & fall, contact-rich & deformable, vision language model ...)

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:

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

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

git submodule update --init --recursive

2. Install the package

We recommend using uv for fast dependency management (Python 3.12 by default):

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 reinforcement learning training, install the optional dependency set.

uv sync --extra dynsyn

Usage

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

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:

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:

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

Evaluation:

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.

Citation

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

@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 control results:

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.

Running: Overlap	Running: Separate
Walking: Overlap	Walking: Separate