Import upstream snapshot 57d13ead53206a6bf0db3d66f86506ae8c2ce01a

Upstream: https://github.com/pollen-robotics/bam Upstream-Commit: 57d13ead53206a6bf0db3d66f86506ae8c2ce01a Upstream-Branch: mjlab_frictionloss
2026-08-28 15:42:08 +08:00
commit 8be13016bc
131 changed files with 12114 additions and 0 deletions
@@ -0,0 +1,129 @@
+Better Actuator Models (BAM)
+============================
+
+.. grid:: 1 2 2 2
+    :gutter: 2
+
+    .. grid-item::
+
+        .. video:: https://github.com/Rhoban/bam_media/raw/refs/heads/main/videos/m1_vs_m6.mp4
+                :autoplay:
+                :muted:
+                :loop:
+
+    .. grid-item::
+
+        .. video:: https://github.com/Rhoban/bam_media/raw/refs/heads/main/videos/sin_sin.mp4
+                :autoplay:
+                :muted:
+                :loop:
+
+.. admonition:: What is it?
+
+
+    BAM (for Better Actuator Models) is a library to **identify** and **use** servo-actuator models in simulation
+    engines. In particular, it provides **extended friction models**, which are more accurate than the default friction
+    models used in most simulators (e.g., MuJoCo).
+
+    The animation above is a face-to-face comparison of the :doc:`default MuJoCo friction model (M1) <theory/models>` and an :doc:`extended friction model (M6) <theory/models>` identified for Dynamixel MX-64 and MX-106 servo-actuators lifting a load.
+
+Features
+--------
+
+- :doc:`Pre-identified friction models <usage/actuators>` for common servo-actuators (e.g., XL320, XL330, MX64, MX106...)
+- **API for direct integration of friction models** into :doc:`MuJoCo CPU <usage/mujoco_cpu>` and :doc:`mjlab (MuJoCo Warp) <usage/mjlab_gpu>`
+- :doc:`Extended friction models <theory/index>`, including Stribeck effect, load-dependance
+- :doc:`Identification process <identification/index>` for servo-actuator with friction models
+
+Getting started
+---------------
+
+Pick the path that matches where you are:
+
+.. grid:: 1 1 3 3
+    :gutter: 3
+    :class-container: bam-getting-started
+
+    .. grid-item-card:: 🔌 Use a bundled model
+        :link: usage/index
+        :link-type: doc
+        :class-card: bam-card
+
+        Your motor is already in the :doc:`library <usage/actuators>`
+        (``xl320``, ``xl330``, ``mx64``, ``mx106``, ...).
+
+        Load its parameters and plug them into your MuJoCo or mjlab simulation
+        right away.
+
+        +++
+        :doc:`Usage guide → <usage/index>`
+
+    .. grid-item-card:: 🔧 Identify a new motor
+        :link: identification/index
+        :link-type: doc
+        :class-card: bam-card
+
+        Your motor is not in the library yet.
+
+        Build a simple pendulum test bench, record trajectories under varying
+        load, and run the identification pipeline to fit a friction model.
+
+        +++
+        :doc:`Identification process → <identification/index>`
+
+    .. grid-item-card:: 📐 Understand the theory
+        :link: theory/index
+        :link-type: doc
+        :class-card: bam-card
+
+        You want to understand the modeling approach.
+
+        Dive into the pendulum dynamics, the friction-budget formulation, and
+        the six model variants M1–M6.
+
+        +++
+        :doc:`Theory → <theory/index>`
+
+Reference paper
+---------------
+
+This library implements the modeling and identification approach introduced
+in the paper `"Extended Friction Models for the Physics Simulation of Servo
+Actuators" <https://arxiv.org/pdf/2410.08650>`_ by Marc Duclusaud, Gregoire Passault, Vincent Padois, and Olivier
+Ly .
+
+If you use BAM or the friction models provided in this library for your
+scientific work, please cite the publication:
+
+.. code-block:: bibtex
+
+   @inproceedings{duclusaud2025extended,
+     title={Extended Friction Models for the Physics Simulation of Servo Actuators},
+     author={Duclusaud, Marc and Passault, Gr{\'e}goire and Padois, Vincent and Ly, Olivier},
+     booktitle={2025 IEEE International Conference on Robotics and Automation (ICRA)},
+     pages={12091--12097},
+     year={2025},
+     organization={IEEE}
+   }
+
+If you also wish to cite the software directly, you may use:
+
+.. code-block:: bibtex
+
+   @software{BAM,
+     title = {{BAM: Better Actuator Models}},
+     author = {Duclusaud, Marc and Passault, Grégoire},
+     license = {Apache-2.0},
+     url = {https://github.com/Rhoban/bam},
+     version = {0.0.1},
+     year = {2024}
+   }
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   usage/index
+   identification/index
+   theory/index
+   api/index