TL;DR
- Installez MuJoCo 3.2.0 via
pip install mujocoet vérifiez avecpython -c "import mujoco; print(mujoco.__version__)"→3.2.0. - Modélisez des robots en MJCF (XML) avec les balises
<world>,<body>,<joint>et<actuator>. Exemple : XML minimal pour humanoïde. - Ajustez la physique avec les balises
<contact>(frottement, rigidité) et<solver>(itérations, tolérance). Frottement par défaut :mu=0.5,mu2=0.0. - Exécutez des simulations parallèles sur GPU avec MJX (nécessite CUDA). Exemple :
python -m mujoco.mjx_simulate --gpu. - Chargez les environnements Gymnasium via
gymnasium.make("Humanoid-v4")et entraînez avec Stable Baselines3. - Transfert sim-to-real : Utilisez l’identification de système (ex.
scipy.optimizepour l’ajustement des paramètres) et enregistrez les données avec les structuresmjData.
1. Installation et bases du MJCF
Les bindings Python de MuJoCo (mujoco) sont la méthode la plus rapide pour commencer. Le MJCF (MuJoCo XML Format) est le langage de modélisation central—considérez-le comme un fichier CAD conscient de la physique.
Installer MuJoCo 3.2.0
# Linux (Ubuntu/Debian)
sudo apt-get install -y libgl1-mesa-dev libxinerama-dev libxcursor-dev
pip install mujoco==3.2.0 # Version stable verrouillée
# Vérification de l'installation
python -c "import mujoco; print(f'MuJoCo {mujoco.__version__} installé avec succès')"
Sortie attendue :
MuJoCo 3.2.0 installé avec succès
MJCF : La structure XML de base
Les modèles MuJoCo sont définis dans des fichiers XML (.xml). Voici un exemple minimal pour un pendule 2D :
<mujoco model="pendule">
<worldbody>
<light name="lumière" pos="0 0 3"/>
<camera name="caméra" pos="0 0 1.5" xyaxes="1 0 0 0 1 0"/>
<body name="pendule" pos="0 0 0">
<joint name="charnière" type="hinge" axis="0 0 1"/>
<geom name="poids" type="sphere" size="0.1" rgba="0.8 0.6 0.4 1"/>
</body>
<actuator name="moteur">
<motor joint="charnière"/>
</actuator>
</worldbody>
</mujoco>
Balises clés :
<worldbody>: Conteneur racine pour tous les objets physiques.<body>: Corps rigides (ex. : segments de robot).<joint>: Définit les degrés de liberté (hinge,slide,ball).<geom>: Géométrie de collision (box,sphere,mesh).<actuator>: Moteurs, forces ou couples.
Piège à éviter : Oublier de fermer les balises (ex. : <body> sans </body>) fera planter le simulateur. Utilisez un validateur comme XMLLint.
2. Modélisation d’un robot : Corps, articulations et actionneurs
Construisons un bras robotisé à 7 degrés de liberté (DoF) avec le MJCF. Concentrez-vous sur :
- Corps : Segments avec masse/inertie.
- Articulations : Reliez les corps avec des contraintes.
- Actionneurs : Appliquez des forces/couples.
Exemple : Bras à 7 DoF en MJCF
<mujoco model="bras7dof">
<asset>
<mesh file="bras.mesh" scale="0.1"/>
</asset>
<worldbody>
<!-- Base -->
<body name="base" pos="0 0 0.5">
<freejoint/>
<geom type="box" size="0.2 0.2 0.1" rgba="0.5 0.5 0.5 1"/>
</body>
<!-- Segments du bras (articulations entre eux) -->
<body name="segment1" pos="0 0 0.3">
<joint name="articulation1" type="hinge" axis="0 1 0" damping="0.1"/>
<geom type="box" size="0.1 0.1 0.3" rgba="0.8 0.6 0.4 1"/>
</body>
<!-- Répétez pour les segments 2-7... -->
<!-- Actionneurs (un par articulation) -->
<actuator name="moteur1">
<motor joint="articulation1" gear="100"/>
</actuator>
</worldbody>
</mujoco>
Paramètres critiques :
damping: Réduit les oscillations des articulations (valeur par défaut :0.0).gear: Simule les rapports de transmission (ex. :gear="100"= réduction 100:1).size: Dimensions de la géométrie (doivent correspondre au CAD si utilisation de<mesh>).
Piège à éviter : MuJoCo utilise les unités SI (mètres, kilogrammes, secondes). Une boîte de size="0.1" mesure 10 cm de large.
3. Contacts, frottement et réglages du solveur
La précision physique de MuJoCo dépend de la modélisation des contacts et de l’optimisation du solveur.
Propriétés des contacts
Modifiez les balises <contact> pour contrôler le frottement, la restitution (élasticité) et la rigidité :
<contact>
<geom1>corps1</geom1>
<geom2>corps2</geom2>
<friction>0.3 0.01 0.001</friction> <!-- mu, mu2, mu3 -->
<restitution>0.5</restitution> <!-- Élasticité (0-1) -->
<solref>0.01 1.0</solref> <!-- Référence du solveur (pénétration, rigidité) -->
</contact>
Valeurs par défaut :
- Frottement :
mu=0.5,mu2=0.0(statique/dynamique). - Restitution :
0.0(pas de rebond).
Réglage du solveur
Ajustez le solveur pour assurer la stabilité :
<solver>
<iterations>100</iterations> <!-- Par défaut : 100 -->
<tolerance>1e-8</tolerance> <!-- Par défaut : 1e-8 -->
<constraint>LRP</constraint> <!-- "LRP" ou "NCP" -->
</solver>
Quand ajuster :
- Nombre élevé d’itérations (200+) : Pour des contacts complexes (ex. : mains dextres).
- Tolérance plus faible (1e-6) : Plus rapide mais moins précis.
Piège à éviter : Si votre simulation explose, augmentez solref ou réduisez iterations. Si elle est raide, diminuez restitution.
4. MJX pour la simulation parallèle accélérée par GPU
MJX (MuJoCo eXtended) permet des simulations parallèles accélérées par GPU, essentielles pour l’entraînement en apprentissage par renforcement (RL).
Installer MJX
pip install mujoco==3.2.0 mjx # MJX est inclus avec mujoco>=3.2.0
Vérification du support CUDA :
python -c "import mjx; print(mjx.cuda.is_available())" # Doit retourner True
Exécuter une simulation de pendule sur GPU
import mjx
import numpy as np
# Charger le modèle
model = mjx.make("pendule.xml")
sim = mjx.Sim(model)
# Exécuter 100 étapes
for _ in range(100):
sim.step()
Résultat attendu : Le pendule oscille en douceur (visualisable via sim.render()).
Piège à éviter : MJX nécessite CUDA 11.8+. Vérifiez la compatibilité avec :
nvcc --version
5. Exécution d’un apprentissage par renforcement avec les environnements Gymnasium
MuJoCo alimente les benchmarks robotiques de Gymnasium (ex. : Humanoid-v4). Voici comment entraîner un agent RL.
Installer Gymnasium avec MuJoCo
pip install gymnasium[mujoco] # Inclut MuJoCo 3.2.0
Charger et entraîner un agent
import gymnasium as gym
from stable_baselines3 import PPO
# Initialiser l'environnement
env = gym.make("Humanoid-v4", render_mode="human")
obs, _ = env.reset()
# Entraîner avec PPO
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=10000)
# Tester
obs, _ = env.reset()
for _ in range(1000):
action, _ = model.predict(obs)
obs, _, terminated, truncated, _ = env.step(action)
if terminated or truncated:
obs, _ = env.reset()
Environnements clés :
Humanoid-v4: Déplacement humanoïde en 3D.Ant-v4: Marche quadrupède.Reacher-v4: Atteinte avec un bras en 2D.
Piège à éviter : Les environnements MuJoCo de Gymnasium utilisent le GPU par défaut. En cas d’erreurs CUDA, définissez :
env = gym.make("Humanoid-v4", render_mode=None, use_gpu=False)
6. Pièges du transfert sim-to-real et identification de système
Les physiques de MuJoCo ne sont pas parfaites. Comblez l’écart entre simulation et réalité avec :
- Identification de système : Ajustez les paramètres de MuJoCo pour correspondre au matériel réel.
- Randomisation de domaine : Entraînez-vous sur des paramètres variés de MuJoCo.
Exemple d’identification de système
Utilisez scipy.optimize pour ajuster la masse/inertie de MuJoCo aux données réelles :
import mujoco
import numpy as np
from scipy.optimize import minimize
# Charger le modèle et les données
model = mujoco.MjModel.from_xml_path("robot.xml")
data = mujoco.MjData(model)
# Définir la fonction de coût (ex. : erreur entre le couple simulé et réel)
def cost_function(params):
# Mettre à jour les paramètres du modèle (ex. : masse)
model.body_mass[0] = params[0]
# Simuler et calculer l'erreur
error = simulate_and_compare(data)
return error
# Optimiser
result = minimize(cost_function, x0=[1.0], method="L-BFGS-B")
print(f"Masse optimale : {result.x[0]} kg")
Randomisation de domaine
Randomisez les paramètres de MuJoCo pendant l’entraînement :
def randomize_model(model):
# Randomiser le frottement
model.contact.mu = np.random.uniform(0.3, 0.7)
model.contact.mu2 = np.random.uniform(0.0, 0.1)
# Randomiser la masse
model.body_mass = model.body_mass * np.random.uniform(0.9, 1.1)
return model
Piège à éviter : Le transfert sim-to-real échoue souvent à cause de dynamiques non modélisées (ex. : frottement des câbles). Commencez par une masse/inertie identique et randomisez progressivement.
7. Visualisation et journalisation
Le visualiseur intégré de MuJoCo est léger mais efficace.
Lancer le visualiseur
import mujoco
import mujoco.viewer
model = mujoco.MjModel.from_xml_path("bras7dof.xml")
data = mujoco.MjData(model)
# Créer le visualiseur
with mujoco.viewer.launch_passive(model, data) as viewer:
while viewer.is_running():
step = not viewer.cam_move
mujoco.mj_step(model, data)
Contrôles :
- Cliquer-glisser (gauche) : Faire pivoter la caméra.
- Cliquer-glisser (droit) : Déplacer.
- Molette : Zoomer.
Enregistrer les données pour analyse
Sauvegardez les données de simulation dans un fichier .mat :
import scipy.io
# Simuler et enregistrer
data = mujoco.MjData(model)
for _ in range(1000):
mujoco.mj_step(model, data)
# Sauvegarder les positions des articulations
joint_positions = data.qpos.copy()
# Sauvegarder dans un fichier MATLAB
scipy.io.savemat("données_simulation.mat", {"qpos": joint_positions})
Piège à éviter : Le visualiseur bloque l’exécution Python. Utilisez launch_passive pour un rendu en arrière-plan.
Que faire ensuite ?
- Concevoir un robot personnalisé : Commencez par un bras à 7 DoF (Section 2) et exportez son MJCF vers un outil CAD comme Blender.
- Former un agent RL : Utilisez Stable Baselines3 (Section 5) pour enseigner une compétence à votre robot (ex. : atteindre un objet).
- Déployer sur matériel réel : Utilisez l’identification de système (Section 6) pour ajuster MuJoCo à votre robot physique.
Pour une infrastructure Physical AI—de l’ajustement du simulateur au déploiement en bordure—les outils et l’expertise de Hyperion Consulting peuvent accélérer votre pipeline. Contactez-nous
