{"id":15903136,"url":"https://github.com/LeCAR-Lab/dial-mpc","last_synced_at":"2025-10-18T06:30:35.528Z","repository":{"id":257662473,"uuid":"857882804","full_name":"LeCAR-Lab/dial-mpc","owner":"LeCAR-Lab","description":"Official implementation for the paper \"Full-Order Sampling-Based MPC for Torque-Level Locomotion Control via Diffusion-Style Annealing\". DIAL-MPC is a novel sampling-based MPC framework for legged robot full-order torque-level control with both precision and agility in a training-free manner.","archived":false,"fork":false,"pushed_at":"2025-01-30T00:48:48.000Z","size":281286,"stargazers_count":482,"open_issues_count":3,"forks_count":51,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-01-30T01:27:55.405Z","etag":null,"topics":["diffusion","humanoid","legged-robots","mpc","online-control","optimal-control","quadruped","sampling-based-control"],"latest_commit_sha":null,"homepage":"https://lecar-lab.github.io/dial-mpc/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LeCAR-Lab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-15T21:07:20.000Z","updated_at":"2025-01-28T08:44:33.000Z","dependencies_parsed_at":"2024-09-18T01:32:47.432Z","dependency_job_id":"46d334ea-9a48-44de-b9d7-e78755c1ea57","html_url":"https://github.com/LeCAR-Lab/dial-mpc","commit_stats":null,"previous_names":["lecar-lab/dial-mpc"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeCAR-Lab%2Fdial-mpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeCAR-Lab%2Fdial-mpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeCAR-Lab%2Fdial-mpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeCAR-Lab%2Fdial-mpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeCAR-Lab","download_url":"https://codeload.github.com/LeCAR-Lab/dial-mpc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236907711,"owners_count":19223639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diffusion","humanoid","legged-robots","mpc","online-control","optimal-control","quadruped","sampling-based-control"],"created_at":"2024-10-06T12:01:06.078Z","updated_at":"2025-10-18T06:30:35.522Z","avatar_url":"https://github.com/LeCAR-Lab.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# DIAL-MPC: Diffusion-Inspired Annealing For Legged MPC\n\n\u003cdiv align=\"center\"\u003e\n\nICRA 2025, Best Paper Finalist\n\n[[Website]](https://lecar-lab.github.io/dial-mpc/)\n[[PDF]](https://drive.google.com/file/d/1Z39MCvnl-Tdraon4xAj37iQYLsUh5UOV/view?usp=sharing)\n[[Arxiv]](https://arxiv.org/abs/2409.15610)\n\n[\u003cimg src=\"https://img.shields.io/badge/Backend-Jax-red.svg\"/\u003e](https://github.com/google/jax)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n\u003cimg src=\"assets/joint.gif\" width=\"600px\"/\u003e\n\n\u003c/div\u003e\n\nThis repository contains the code (simulation and real-world experiments with minimum setup) for the paper \"Full-Order Sampling-Based MPC for Torque-Level Locomotion Control via Diffusion-Style Annealing\".\n\nDIAL-MPC is a sampling-based MPC framework for legged robot ***full-order torque-level*** control with both precision and agility in a ***training-free*** manner. \nDIAL-MPC is designed to be simple and flexible, with minimal requirements for specific reward design and dynamics model. It directly samples and rolls out in physics-based simulations (``Brax``) and does not require reduced-order modeling, linearization, convexification, or predefined contact sequences.\nThat means you can test out the controller in a plug-and-play manner with minimum setup.\n\n## News\n\n- 05/19/2025: 🫰 New demo for ball-spinning on finger can be run with `dial-mpc --example allegro_reorient`.\n- 04/24/2025: 🎉 DIAL-MPC made into the best paper final list of ICRA 2025.\n- 11/03/2024: 🎉 Sim2Real pipeline is ready! Check out the [Sim2Real](#deploy-in-real-unitree-go2) section for more details.\n- 09/25/2024: 🎉 DIAL-MPC is released with open-source codes! Sim2Real pipeline coming soon!\n\nhttps://github.com/user-attachments/assets/f2e5f26d-69ac-4478-872e-26943821a218\n\n\n## Table of Contents\n\n1. [Install](#install-dial-mpc)\n2. [Synchronous Simulation](#synchronous-simulation)\n3. [Asynchronous Simulation](#asynchronous-simulation)\n4. [Deploy in Real](#deploy-in-real-unitree-go2)\n5. [Writing Your Own Environment](#writing-custom-environment)\n6. [Rendering Rollouts](#rendering-rollouts-in-blender)\n7. [Citing this Work](#bibtex)\n\n## Simulation Setup\n\n### Install `dial-mpc`\n\n\u003e [!IMPORTANT]\n\u003e We recommend Ubuntu \u003e= 20.04 + Python \u003e= 3.10 + CUDA \u003e= 12.3.\n\u003e You can create a mamba (or conda) environment before proceeding.\n\nOur environment is Ubuntu 22.04 + Python 3.10 + CUDA 12.6.\n\n```bash\ngit clone https://github.com/LeCar-Lab/dial-mpc.git --depth 1\ncd dial-mpc\npip3 install -e .\n```\n\n## Synchronous Simulation\n\nIn this mode, the simulation will wait for DIAL-MPC to finish computing before stepping. It is ideal for debugging and doing tasks that are currently not real-time.\n\n#### Run Examples\n\nList available examples:\n\n```bash\ndial-mpc --list-examples\n```\n\nRun an example:\n\n```bash\ndial-mpc --example unitree_h1_jog\n```\n\nAfter rollout completes, go to `127.0.0.1:5000` to visualize the rollouts.\n\n## Asynchronous Simulation\n\nThe asynchronous simulation is meant to test the algorithm before Sim2Real. The simulation rolls out in real-time (or scaled by `real_time_factor`). DIAL-MPC will encounter delay in this case.\n\nWhen DIAL-MPC cannot finish the compute in the time defined by `dt`, it will spit out warning. Slight overtime is accepetable as DIAL-MPC maintains a buffer of the previous step's solution and will play out the planned action sequence until the buffer runs out.\n\nList available examples:\n\n```bash\ndial-mpc-sim --list-examples\n```\n\nRun an example:\n\nIn terminal 1, run\n\n```bash\ndial-mpc-sim --example unitree_go2_seq_jump_deploy\n```\nThis will open a mujoco visualization window.\n\nIn terminal 2, run\n\n```bash\ndial-mpc-plan --example unitree_go2_seq_jump_deploy\n```\n\n\n## Deploy in Real (Unitree Go2)\n\n### Overview\n\nThe real-world deployment procedure is very similar to asynchronous simulation.\n\nWe use `unitree_sdk2_python` to communicate with the robot directly via CycloneDDS.\n\n### Step 1: State Estimation\n\nFor state estimation, this proof-of-concept work requires external localization module to get base **position** and **velocity**.\n\nThe following plugins are built-in:\n\n- ROS2 odometry message\n- Vicon motion capture system\n\n#### Option 1: ROS2 odometry message\n\nConfigure `odom_topic` in the YAML file. You are responsible for publishing this message at at least 50 Hz and ideally over 100 Hz. We provide an odometry publisher for Vicon motion capture system in [`vicon_interface`](https://github.com/LeCAR-Lab/vicon_interface).\n\n\u003e [!CAUTION]\n\u003e All velocities in ROS2 odometry message **must** be in **body frame** of the base to conform to [ROS odometry message definition](https://docs.ros.org/en/noetic/api/nav_msgs/html/msg/Odometry.html), although in the end they are converted to world frame in DIAL-MPC.\n\n#### Option 2: Vicon (no ROS2 required)\n\n1. `pip install pyvicon-datastream`\n2. Change `localization_plugin` to `vicon_shm_plugin` in the YAML file.\n3. Configure `vicon_tracker_ip`, `vicon_object_name`, and `vicon_z_offset` in the YAML file.\n\n#### Option 3: Bring Your Own Plugin\n\nWe provide a simple ABI for custom localization modules, and you need to implement this in a python file in your workspace, should you consider not using the built-in plugins.\n\n```python\nimport numpy as np\nimport time\nfrom dial_mpc.deploy.localization import register_plugin\nfrom dial_mpc.deploy.localization.base_plugin import BaseLocalizationPlugin\n\nclass MyPlugin(BaseLocalizationPlugin):\n    def __init__(self, config):\n        pass\n\n    def get_state(self):\n        qpos = np.zeros(7)\n        qvel = np.zeros(6)\n        return np.concatenate([qpos, qvel])\n\n    def get_last_update_time(self):\n        return time.time()\n\nregister_plugin('custom_plugin', plugin_cls=MyPlugin)\n```\n\n\u003e [!CAUTION]\n\u003e When writing custom localization plugin, velocities should be reported in **world frame**.\n\n\u003e [!NOTE]\n\u003e Angular velocity source is onboard IMU. You could leave `qvel[3:6]` in the returned state as zero for now.\n\nLocalization plugin can be changed in the configuration file. A `--plugin` argument can be supplied to `dial-mpc-real` to import a custom localization plugin in the current workspace.\n\n### Step 2: Installing `unitree_sdk2_python`\n\n\u003e [!NOTE]\n\u003e If you are already using ROS2 with Cyclone DDS according to [ROS2 documentation on Cyclone DDS](https://docs.ros.org/en/humble/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.html), you don't have to install Cyclone DDS as suggested by `unitree_sdk2_python`. But do follow the rest of the instructions.\n\nFollow the instructions in [`unitree_sdk2_python`](https://github.com/unitreerobotics/unitree_sdk2_python).\n\n### Step 3: Configuring DIAL-MPC\n\nIn `dial_mpc/examples/unitree_go2_trot_deploy.yaml` or `dial_mpc/examples/unitree_go2_seq_jump.yaml`, modify `network_interface` to match the name of the network interface connected to Go2.\n\nAlternatively, you can also pass `--network_interface` to `dial-mpc-real` when launching the robot, which will override the config.\n\n### Step 4: Starting the Robot\n\nFollow the [official Unitree documentation](https://support.unitree.com/home/en/developer/Quick_start) to disable sports mode on Go2. Lay the robot flat on the ground like shown.\n\n\u003cdiv style=\"text-align: center;\"\u003e\n    \u003cimg src=\"images/go2.png\" alt=\"Unitree Go2 laying flat on the ground.\" style=\"width:50%;\"\u003e\n\u003c/div\u003e\n\n### Step 5: Running the Robot\n\nList available examples:\n\n```bash\ndial-mpc-real --list-examples\n```\n\nRun an example:\n\nIn terminal 1, run\n\n```bash\n# source /opt/ros/\u003cros-distro\u003e/setup.bash # if using ROS2\ndial-mpc-real --example unitree_go2_seq_jump_deploy\n```\n\nThis will open a mujoco visualization window. The robot will slowly stand up. If the robot is squatting, manually lift the robot into a standing position. Verify that the robot states match the real world and are updating.\n\nYou can supply additional arguments to `dial-mpc-real`:\n\n- `--custom-env`: custom environment definition.\n- `--network-interface`: override network interface configuration.\n- `--plugin`: custom localization plugin.\n\nNext, in terminal 2, run\n\n```bash\ndial-mpc-plan --example unitree_go2_seq_jump_deploy\n```\n\n## Writing Custom Environment\n\n1. If custom robot model is needed, Store it in `dial_mpc/models/my_model/my_model.xml`.\n2. Import the base environment and config.\n3. Implement required functions.\n4. Register environment.\n5. Configure config file.\n\nExample environment file (`my_env.py`):\n\n```python\nfrom dataclasses import dataclass\n\nfrom brax import envs as brax_envs\nfrom brax.envs.base import State\n\nfrom dial_mpc.envs.base_env import BaseEnv, BaseEnvConfig\nimport dial_mpc.envs as dial_envs\n\n@dataclass\nclass MyEnvConfig(BaseEnvConfig):\n    arg1: 1.0\n    arg2: \"test\"\n\nclass MyEnv(BaseEnv):\n    def __init__(self, config: MyEnvConfig):\n        super().__init__(config)\n        # custom initializations below...\n\n    def make_system(self, config: MyEnvConfig) -\u003e System:\n        model_path = (\"my_model/my_model.xml\")\n        sys = mjcf.load(model_path)\n        sys = sys.tree_replace({\"opt.timestep\": config.timestep})\n        return sys\n\n    def reset(self, rng: jax.Array) -\u003e State:\n        # TODO: implement reset\n\n    def step(self, state: State, action: jax.Array) -\u003e State:\n        # TODO: implement step\n\nbrax_envs.register_environment(\"my_env_name\", MyEnv)\ndial_envs.register_config(\"my_env_name\", MyEnvConfig)\n```\n\nExample configuration file (`my_env.yaml`):\n```yaml\n# DIAL-MPC\nseed: 0\noutput_dir: dial_mpc_ws/my_model\nn_steps: 400\n\nenv_name: my_env_name\nNsample: 2048\nHsample: 25\nHnode: 5\nNdiffuse: 4\nNdiffuse_init: 10\ntemp_sample: 0.05\nhorizon_diffuse_factor: 1.0\ntraj_diffuse_factor: 0.5\nupdate_method: mppi\n\n\n# Base environment\ndt: 0.02\ntimestep: 0.02\nleg_control: torque\naction_scale: 1.0\n\n# My Env\narg1: 2.0\narg2: \"test_2\"\n```\n\nRun the following command to use the custom environment in synchronous simulation. Make sure that `my_env.py` is in the same directory from which the command is run.\n\n```bash\ndial-mpc --config my_env.yaml --custom-env my_env\n```\n\nYou can also run asynchronous simulation with the custom environment:\n\n```bash\n# Terminal 1\ndial-mpc-sim --config my_env.yaml --custom-env my_env\n\n# Terminal 2\ndial-mpc-plan --config my_env.yaml --custom-env my_env\n```\n\n## Rendering Rollouts in Blender\n\nIf you want better visualization, you can check out the `render` branch for the Blender visualization examples. \n\n## Acknowledgements\n\n* This codebase's environment and RL implementation is built on top of [Brax](https://github.com/google/brax).\n* We use [Mujoco MJX](https://github.com/deepmind/mujoco) for the physics engine.\n* Controller design and implementation is inspired by [Model-based Diffusion](https://github.com/LeCAR-Lab/model-based-diffusion).\n\n\n## BibTeX\n\nIf you find this code useful for your research, please consider citing:\n\n```bibtex\n@misc{xue2024fullordersamplingbasedmpctorquelevel,\n      title={Full-Order Sampling-Based MPC for Torque-Level Locomotion Control via Diffusion-Style Annealing}, \n      author={Haoru Xue and Chaoyi Pan and Zeji Yi and Guannan Qu and Guanya Shi},\n      year={2024},\n      eprint={2409.15610},\n      archivePrefix={arXiv},\n      primaryClass={cs.RO},\n      url={https://arxiv.org/abs/2409.15610}, \n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeCAR-Lab%2Fdial-mpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLeCAR-Lab%2Fdial-mpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLeCAR-Lab%2Fdial-mpc/lists"}