This repository contains the ARLab-VT reflex-recovery study for perturbed, muscle-actuated human walking. It extends the upstream MuscleMimic framework with reproducible perturbations, phase-dependent reflex residuals, recovery gating, frozen-policy comparisons, scientific metrics, plots, and videos.
| Resource | Purpose |
|---|---|
| Executable study notebook | Main implementation narrative, file map, validation cells, plots, and video comparisons. |
| Simulation study specification | Complete scientific plan, phases, experiments, metrics, ablations, and acceptance gates. |
| Codebase audit | Model/action-path evidence and implementation decisions. |
| Reflex-recovery package | Reusable perturbation, reflex, delay, gate, recovery, action-composition, and metric modules. |
| Experiment configurations | Smoke, training, evaluation, ablation, and walking-disturbance Hydra configurations. |
| Focused tests | Unit and integration checks for the scientific implementation. |
| Repository maintenance guide | Branching, upstream synchronization, validation, artifact, and release workflow. |
The released base policy, deterministic baseline, perturbation-only rollout, and base-plus-reflex rollout are validated. Residual recovery-policy training and multi-seed robustness claims remain gated by the acceptance criteria in the study specification. The notebook labels completed, partial, and open phases explicitly so exploratory results are not presented as final evidence.
Generated checkpoints, gated datasets, rollout arrays, caches, and videos are intentionally excluded from Git. They can be regenerated with the documented commands and should be distributed through an appropriate artifact store or a versioned release rather than committed to source history.
This study is derived from amathislab/musclemimic. The upstream Git history, attribution, and Apache License 2.0 are retained. Study changes are developed on reviewable branches and synchronized with the upstream project as described in the maintenance guide.
MuscleMimic is a JAX-based motion imitation learning benchmark for biomechanically accurate, muscle-actuated models. It targets full-body locomotion and manipulation with GPU-parallel training, MuJoCo/MJWarp dynamics, and retargeted motion datasets.
- 2026-06: Added C3D browser tooling for fitting motion-capture markers, exporting AMASS/SMPL-H-compatible motion, and retargeting to MuscleMimic trajectories. See the web viewer guide.
- 2026-03: MuscleMimic preprint released on arXiv.
- 2026-02: MuscleMimic blog post released at https://cnai.epfl.ch/mm-blog/.
- Muscle-actuated dynamics: Hill-type muscle models with physiological activation dynamics.
- Accelerated training: JAX JIT compilation with the MuJoCo Warp backend, supporting thousands of parallel environments.
- Generalist imitation policies: DeepMimic-style rewards and validation metrics for diverse motion datasets.
- Retargeting tools: GMR-Fit support for AMASS/SMPL motions and C3D marker data.
| Model | Type | Joints | Muscles | DoFs | Focus |
|---|---|---|---|---|---|
| MyoBimanualArm | Fixed-base | 76 (36*) | 126 (64*) | 54 (14*) | Upper-body manipulation |
| MyoFullBody | Free-root | 123 (83*) | 416 (354*) | 72 (32*) | Locomotion and manipulation |
*Configurations with finger muscles disabled.
Training requires Linux with an NVIDIA GPU. Inference and evaluation are supported on Linux and macOS.
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/amathislab/musclemimic
cd musclemimic
uv sync --extra cudaThe first-time path uses pre-retargeted demo motions, so no AMASS download is needed. The demo dataset is gated on Hugging Face: amathislab/demo_dataset.
uv run hf auth login
uv run python -c "from musclemimic.utils.demo_cache import setup_demo_for_bimanual; setup_demo_for_bimanual()"
uv run python -c "from musclemimic.utils.demo_cache import setup_demo_for_myo_fullbody; setup_demo_for_myo_fullbody()"Start a short demo training run. These configs log to Weights & Biases with
wandb.mode=online by default:
uv run bimanual/experiment.py --config-name=conf_bimanual_demo
uv run fullbody/experiment.py --config-name=conf_fullbody_demoEvaluate a released MyoFullBody checkpoint with the MuJoCo viewer:
uv run mjpython fullbody/eval.py \
--path hf://amathislab/mm-10m-2 \
--motion_path KIT/314/walking_medium09_poses \
--use_mujoco \
--stochastic \
--eval_seed 0 \
--n_steps 1000 \
--mujoco_viewerOn Linux, a regular python entrypoint is sufficient for viewer-based MuJoCo
commands. On macOS, use mjpython.
| Model | Checkpoints | Retargeted dataset |
|---|---|---|
| MyoBimanualArm | amathislab/mm-bimanual-v0 | amathislab/musclemimic-bimanual-retargeted |
| MyoFullBody | amathislab/mm-fullbody-base | amathislab/musclemimic-retargeted |
Pre-retargeted GMR caches can be downloaded directly:
uv run musclemimic-download-gmr-caches --dataset-group KIT_KINESIS_TRAINING_MOTIONS
uv run musclemimic-download-gmr-caches --dataset-group AMASS_BIMANUAL_TRAIN_MOTIONS --env-name MyoBimanualArmFor full AMASS setup, C3D conversion, finetuning from checkpoints, and viewer workflows, see Detailed Workflows.
- Detailed workflows: demo cache, evaluation variants, GMR caches, full AMASS retargeting, finetuning, and Viser visualization.
- C3D web viewer: C3D marker viewing, SMPL-X/SMPL-H fitting, cache layout, and browser retargeting.
- Contributing: local development, testing, and review guidelines.
make install-dev
make precommit-install
make cipre-commit currently targets a curated subset of files while the repository is
being migrated toward broader coverage. make lint and make format follow
that same scoped set rather than reformatting the whole repository.
If you use this code in your research, please cite:
@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}
}This project is licensed under the Apache License. Model checkpoints, datasets, SMPL-family assets, and other third-party software may be licensed separately; review each provider's terms before use.
Inspired by and built on MyoSuite, MuJoCo Warp, Kinesis, LocoMuJoCo, SMPL-X, PureJaxRL, and MuJoCo Playground.