README.md

---
license: gpl-2.0
---

# AugMPCModels

Demo bundles for [AugMPC](https://github.com/AndrePatri/AugMPC):

- Andrea Patrizi, Carlo Rizzardo, Arturo Laurenzi, Francesco Ruscelli, Luca Rossini, Nikos G. Tsagarakis
- *RL-Augmented MPC for Non-Gaited Legged and Hybrid Locomotion*
- IEEE Robotics and Automation Letters (RA-L)
- arXiv: [2603.10878](https://arxiv.org/abs/2603.10878)

## Preferred usage

The preferred way to run these models is through the dedicated [ibrido-containers](https://github.com/AndrePatri/ibrido-containers) setup. The containers provide the expected runtime environments, MPC implementations, workspace layout, and `training_data` mounts used by the published bundles.

In practice, users should:

1. set up the container following the instructions in `ibrido-containers`;
2. pick the desired container : `ibrido-containers/ibrido_u22` ships with IsaacSim, `ibrido-containers/ibrido_u20` for cheap single environment transfer evaluations on MujoCo. 
3. pick a matching configuration file associated with the target robot under `ibrido-containers/ibrido_u*/singularity/files/training_cfgs/<robot_name>/`; configs for the same robot may change crucial MPC parameters, so it's important that this matches the one used during training.
3. configure the config to load the chosen model bundle by modyfing these variables:

```bash
export EVAL=1 # run framework in eval mode
export DET_EVAL=1 # run deterministic policy evaluation
export EVAL_ON_CPU=1 # eval on CPU
export OVERRIDE_ENV=0 # if 0, will load the exact same environment as used during training
export OVERRIDE_AGENT_REFS=1 # if 1 user can send refs to the agent using the keyboard or joystick utilities in AugMPC
export MPATH="/root/training_data/AugMPCModels/bundles/<robot_name>/<bundle_name>" # path to the bundle
export MNAME="<bundle_name>_model" # torch model name within the bundle path
#...
export N_ENVS=1 # you can add more if you want to run multiple environments (if chosen world interface supports vectorized simulation)
```

For instance:

```bash
export MPATH="/root/training_data/AugMPCModels/bundles/centauro/d2026_03_07_h19_m22_s30-CentauroCloopPartialNoYawUb_FakePosTrackingEnv"
export MNAME="d2026_03_07_h19_m22_s30-CentauroCloopPartialNoYawUb_FakePosTrackingEnv_model" # or any other checkpoint available
```

Within the existing `ibrido-containers` logic, `EVAL=1` triggers evaluation mode using the policy pointed to by `MPATH` and `MNAME`. Users can verify that the evaluation configuration is aligned with the original training setup by inspecting the preserved training script stored in the bundle under `bundles/<robot_name>/<bundle_name>/ibrido_run_*/training_cfg_*.sh`.

## Repository structure

Each model is distributed as a **bundle**, not just as a checkpoint file. A bundle may include:

- the policy checkpoint
- environment and deployment configuration files
- robot description files (`URDF`, `SRDF`)
- controller/world-interface helpers needed for reproduction
- a `bundle.yaml` manifest describing the contents

Layout:

```text
bundles/
  <robot_name>/
    <bundle_name>/
      bundle.yaml
      <checkpoint>_model
      *.yaml
      *.py
      *.urdf
      *.srdf
      other/
```
## Training runs
The training runs associated to the public models are made available [here](https://wandb.ai/andrepatriteam/AugMPCModels?nw=nwuserandrepatri).