improved readme instructions

README.md

@@ -4,17 +4,44 @@ license: gpl-2.0
 
 # AugMPCModels
 
-Deployment bundles for [AugMPC](https://github.com/AndrePatri/AugMPC), published alongside the preprint:
+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 environment, workspace layout, and training-data mounts used by the published bundles.
+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 first set up the container following the instructions in `ibrido-containers`, and then point AugMPC to the local bundle path under the mounted `training_data/AugMPCModels` repository.
+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
 
@@ -26,11 +53,11 @@ Each model is distributed as a **bundle**, not just as a checkpoint file. A bund
 - controller/world-interface helpers needed for reproduction
 - a `bundle.yaml` manifest describing the contents
 
-Current layout:
+Layout:
 
 ```text
 bundles/
-  centauro/
+  <robot_name>/
     <bundle_name>/
       bundle.yaml
       <checkpoint>_model
@@ -40,14 +67,3 @@ bundles/
       *.srdf
       other/
 ```
-
-## Usage model
-
-The intended runtime flow is:
-
-1. resolve or download a bundle locally,
-2. read `bundle.yaml`,
-3. locate the checkpoint file and companion configs,
-4. launch AugMPC using the resolved local bundle path.
-
-This repository is therefore meant to back a bundle resolver, rather than a direct `torch.load()` call on a remote file.