microduck_rl/docs/superpowers/specs/2026-07-22-roller-slope-design.md

# Mode pente — `roller_slope` (descente passive équilibrée)

Date : 2026-07-22
Statut : design validé, prêt pour le plan d'implémentation.

## Objectif

Entraîner une politique dédiée où **microduck (sur rollers) démarre sur du plat
avec une petite impulsion vers l'avant, roule jusqu'à une rampe descendante, et
se laisse glisser jusqu'en bas en restant debout et équilibré**. Aucun pilotage
pendant la descente : le seul objectif de la politique est de **ne pas tomber**.

La politique doit gérer des rampes de raideur croissante (**~2° → ~20°**) grâce à
un curriculum de difficulté.

## Décisions cadrées (brainstorming)

| Sujet | Décision |
|---|---|
| Comportement | Descente passive équilibrée (la gravité fait avancer, pas de pédalage imposé) |
| Pilotage | Aucun — équilibre pur, commande `twist` forcée à zéro |
| Approche | **A** — tâche dédiée, isolée (comme `roller_crouch`) |
| Forme du terrain | **Rampe simple** : plat de départ + rampe descendante (pas de pyramide) |
| Scénario épisode | Spawn sur le plat → vitesse d'impulsion vers l'avant → glisse sur la rampe |
| Raideur | Curriculum **0/2° → 20°** |
| Déploiement | Flag `--slope <onnx>` + touche **`Y`** dans `infer_policy.py` (Y est libre) |

## Architecture

### 1. Nouvelle tâche

Fichier : `src/mjlab_microduck/tasks/microduck_roller_slope_env_cfg.py`, cloné de
`microduck_velocity_rollers_env_cfg.py`.

- Même robot rollers (`MICRODUCK_WALK_ROLLERS_ROBOT_CFG`), même physique, même
  domain randomization / bruit / délais.
- **Même observation 61D** (twist + head/body en zéro-padding) → la politique
  charge par le chemin `--new-cmd-obs` du runtime et reste interchangeable avec
  les autres politiques rollers.
- Enregistrement dans `src/mjlab_microduck/tasks/__init__.py` via
  `register_mjlab_task`, avec une config PPO `MicroduckRollerSlopeRlCfg`
  (`experiment_name`/`run_name` = `roller_slope`).

### 2. Terrain « plat + rampe » (custom)

Les terrains inclinés fournis par mjlab sont des pyramides ; on écrit donc un
`SubTerrainCfg` dédié (p. ex. `FlatRampTerrainCfg`) dont la méthode
`function(difficulty, spec, rng)` construit :

- une **zone plate de départ** (longueur ~1–2 m) où le robot spawne ;
- une **rampe descendante** à la suite, dont l'angle est
  **interpolé par `difficulty`** sur `[~2°, ~20°]`.

Le terrain est monté via `TerrainEntityCfg(terrain_type="generator", ...)` avec un
`TerrainGeneratorCfg` qui génère plusieurs niveaux de difficulté (donc plusieurs
angles de rampe). L'origine de chaque environnement doit tomber **sur la zone
plate**, la rampe devant lui.

> Risque d'implémentation à traiter dans le plan : positionnement de l'origine de
> spawn sur le plat (pas au centre de la tuile), et orientation de la rampe pour
> que « devant » = « vers le bas ».

### 3. Commande = aucune

Slot `twist` neutralisé : `rel_standing_envs = 1.0`, ranges de vitesse à 0,
`rel_heading_envs = 0.0`. Head/body restent en zéro-padding. La politique ne
reçoit aucune consigne de déplacement.

### 4. Reset & vitesse d'impulsion

- `reset_base` : spawn au repos sur le plat, hauteur `z` nominale rollers
  (~`0.1335–0.1435`, comme le roller env).
- **Vitesse d'entrée** injectée via le `velocity_range` de
  `reset_root_state_uniform` (état propre + range), **pas** via
  `push_by_setting_velocity` (qui s'additionne à l'état courant et peut faire
  diverger le free-joint → NaN — leçon déjà apprise sur `roller_crouch`) :
  `x ≈ (0.2, 0.5) m/s` vers l'avant.
- Pushs aléatoires légers conservés pendant l'épisode (robustesse), comme le
  roller env.

### 5. Récompenses

Cœur « rester droit + posture naturelle », anti-optimum-paresseux (éviter qu'il
s'écrase au sol pour maximiser la stabilité) :

- `upright` (tronc vertical) — **principale**
- `alive` (bonus de survie par pas)
- **pose debout nominale** : récompense vers la pose HOME (mécanique
  d'interpolation de pose reprise de `roller_crouch`, mais cible fixe = debout),
  pour garder une stance rollers normale plutôt qu'un accroupi défensif
- `feet_flat` (rollers à plat au sol)
- `body_ang_vel`, `angular_momentum` (pas de tremblement / vrille)
- `action_rate_l2`, `neck_action_rate_l2`, `joint_torques_l2`,
  `self_collisions` (douceur + sim2real)

> Pas de récompense de vitesse/frein : la descente est passive. On ne récompense
> pas « aller vite », seulement « rester droit en descendant ».

### 6. Terminaisons

- **Chute** : `bad_orientation` (tronc trop incliné).
- **Bas atteint** : `out_of_terrain_bounds` (le robot est arrivé en bas de la
  rampe → reset).
- `nan_state`, time-out.

### 7. Curriculum de difficulté (raideur)

Progression **doux → raide** : commencer sur des rampes quasi plates, augmenter
l'angle vers 20° au fur et à mesure des réussites.

> Risque d'implémentation : le curriculum standard `terrain_levels_vel` promeut
> selon la distance parcourue par rapport à la vitesse commandée. Ici la commande
> est nulle, donc **il faut un critère de promotion custom** : promouvoir si le
> robot a survécu / atteint le bas sans tomber, rétrograder s'il chute tôt.

### 8. Déploiement — bouton `Y`

Dans `scripts/infer_policy.py` :

- nouveau flag `--slope <onnx>` chargeant la politique pente comme session
  supplémentaire (même schéma que `--walking` / `--standing` / `--ground-pick`) ;
- `GLFW_KEY_Y = 89` (aujourd'hui **libre** — la tête est sur `H`) qui **bascule**
  la session active vers/depuis la politique pente ;
- ligne d'aide clavier ajoutée.

Aucun contrôle existant n'est cassé (contrairement à un partage de la touche `H`
du contrôle de la tête).

## Ce qui n'est PAS dans le périmètre (YAGNI)

- Pas de pilotage gauche/droite ni de freinage en descente.
- Pas de montée de pente ni de traversée.
- Pas de pyramide ni de terrains multi-directions.
- Pas de fine-tuning depuis les poids roller existants (entraînement from
  scratch).

## Livrables

1. `microduck_roller_slope_env_cfg.py` (env + `FlatRampTerrainCfg` + PPO cfg).
2. Enregistrement de la tâche dans `tasks/__init__.py`.
3. Récompenses/curriculum custom nécessaires dans `tasks/mdp.py` (pose-debout,
   promotion de niveau).
4. Branchement `--slope` + touche `Y` dans `scripts/infer_policy.py`.
5. Tests unitaires pour les fonctions pures (angle de rampe par difficulté,
   éventuel critère de promotion).