Import upstream snapshot 57d13ead53206a6bf0db3d66f86506ae8c2ce01a

Upstream: https://github.com/pollen-robotics/bam
Upstream-Commit: 57d13ead53206a6bf0db3d66f86506ae8c2ce01a
Upstream-Branch: mjlab_frictionloss

docs/theory/models.rst

@@ -0,0 +1,183 @@
+Friction Models (M1-M6)
+=======================
+
+BAM supports six friction models of increasing expressiveness, denoted
+:math:`\mathcal{M}_1` to :math:`\mathcal{M}_6`.
+
+They are ordered from the simplest Coulomb-Viscous approximation to a richer
+directional and quadratic formulation that better captures gearbox behavior.
+
+- :math:`\mathcal{M}_1`: Coulomb-Viscous
+- :math:`\mathcal{M}_2`: Stribeck
+- :math:`\mathcal{M}_3`: Load-dependent
+- :math:`\mathcal{M}_4`: Stribeck + load-dependent
+- :math:`\mathcal{M}_5`: Directional load-dependent
+- :math:`\mathcal{M}_6`: Quadratic directional variant
+
+Notation
+--------
+
+In the equations below:
+
+- :math:`\dot{\theta}` is joint velocity
+- :math:`\tau_m` is motor torque
+- :math:`\tau_e` is external/load torque
+- :math:`\tau_{fm}` is the maximum resistive friction torque (friction budget)
+
+The simulation then applies friction by clipping the stopping torque in
+:math:`[-\tau_{fm},\tau_{fm}]`.
+
+Drive/backdrive diagrams
+------------------------
+
+The drive/backdrive diagrams help to visualize the effect of friction. Let's for example consider the :math:`\mathcal{M}_6` model:
+
+.. image:: ../_static/drive_backdrive_m6.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+Here:
+
+- Below the blue line, the motor is driving the system
+- Above the red line, the system is backdriving the motor
+- On the black dashed line, motor torque and external torque exacttly cancel out
+- In the middle, the friction budget is preventing motion in the system
+- The lines with less opacity depicts what happens when the system is moving (1 rad/s per step). As you can notice, the faster the system is moving, the less friction appears here.
+
+They can be obtained using ``bam.drive_backdrive`` command from the repository:
+
+.. code-block:: bash
+
+    uv run -m bam.drive_backdrive --params bam/params/erob80_100/m1.json  --max_torque 100
+
+Model :math:`\mathcal{M}_1`: Coulomb-Viscous
+--------------------------------------------
+
+.. image:: ../_static/drive_backdrive_m1.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_1:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c
+
+This is the baseline model used in most physics simulators.
+It keeps only viscous damping and a constant Coulomb term.
+
+Model :math:`\mathcal{M}_2`: Stribeck
+-------------------------------------
+
+.. image:: ../_static/drive_backdrive_m2.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_2:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c +
+   \exp\left(-\left|\frac{\dot{\theta}}{\dot{\theta}_s}\right|^{\alpha}\right)K_{cs}
+
+This adds higher friction near zero speed and smooth transition to sliding.
+It models the fact that static friction is usually stronger than sliding friction.
+
+Model :math:`\mathcal{M}_3`: Load-dependent
+-------------------------------------------
+
+.. image:: ../_static/drive_backdrive_m3.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_3:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c + K_l|\tau_m - \tau_e|
+
+This captures the increase of friction with transmitted gearbox load.
+It is useful when the apparent resistance depends on how hard the transmission is loaded.
+
+Model :math:`\mathcal{M}_4`: Stribeck + load-dependent
+------------------------------------------------------
+
+.. image:: ../_static/drive_backdrive_m4.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_4:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c + K_l|\tau_m-\tau_e|
+   + \exp\left(-\left|\frac{\dot{\theta}}{\dot{\theta}_s}\right|^{\alpha}\right)
+   \left(K_{cs} + K_{ls}|\tau_m-\tau_e|\right)
+
+This combines presliding dynamics with load dependence.
+It adds Stribeck smoothing on top of a load-sensitive friction budget.
+
+Model :math:`\mathcal{M}_5`: Directional load-dependent
+-------------------------------------------------------
+
+.. image:: ../_static/drive_backdrive_m5.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_5:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c + |K_m\tau_m - K_e\tau_e|
+   + \exp\left(-\left|\frac{\dot{\theta}}{\dot{\theta}_s}\right|^{\alpha}\right)
+   \left(K_{cs} + |K_{ms}\tau_m - K_{es}\tau_e|\right)
+
+This separates motor-side and external-side contributions, which helps model
+directional efficiency/backdrivability asymmetry.
+It is appropriate when the gearbox behaves differently depending on the torque direction.
+
+Model :math:`\mathcal{M}_6`: Quadratic directional
+--------------------------------------------------
+
+.. image:: ../_static/drive_backdrive_m6.png
+    :alt: Drive/backdrive diagram
+    :width: 500
+    :align: center
+
+.. math::
+
+   \mathcal{M}_6:\quad
+   \tau_{fm} = K_v|\dot{\theta}| + K_c + |K_m\tau_m - K_e\tau_e|
+   + \exp\left(-\left|\frac{\dot{\theta}}{\dot{\theta}_s}\right|^{\alpha}\right)
+   \left(K_{cs} + |K_{ms}\tau_m - K_{es}\tau_e| + Q\right)
+
+with piecewise quadratic contribution:
+
+.. math::
+
+   Q =
+   \begin{cases}
+   K_{eq}\tau_e^2 & \text{if } |\tau_m| > |\tau_e| \\
+   K_{mq}\tau_m^2 & \text{otherwise}
+   \end{cases}
+
+This is useful for actuators where harmonic-drive-like effects create nonlinear
+load-friction coupling.
+It extends the directional model with a quadratic load term.
+
+Modeling hierarchy
+------------------
+
+The sequence :math:`\mathcal{M}_1 \rightarrow \mathcal{M}_6` reflects increasing
+expressiveness and parameter count. In practice, BAM fits all candidates and
+selects the best trade-off from validation error.
+
+Implementation in BAM
+---------------------
+
+Model behaviors are implemented in :mod:`bam.model`, notably:
+
+- :class:`bam.model.Model`
+- :func:`bam.model.load_model`
+- :func:`bam.model.load_model_from_dict`