8be13016bc
Upstream: https://github.com/pollen-robotics/bam Upstream-Commit: 57d13ead53206a6bf0db3d66f86506ae8c2ce01a Upstream-Branch: mjlab_frictionloss
74 lines
2.1 KiB
ReStructuredText
74 lines
2.1 KiB
ReStructuredText
Contributing a Model
|
||
====================
|
||
|
||
If you have identified parameters for a motor that is not yet in the BAM
|
||
library, sharing them benefits the whole community. This page explains how
|
||
to format and submit your contribution.
|
||
|
||
What to include
|
||
---------------
|
||
|
||
A contribution consists of:
|
||
|
||
- One JSON parameter file per model variant (at minimum M6; ideally M1–M6).
|
||
- Update in this documentation, adding your actuator to the :doc:`usage/actuators` page.
|
||
- Ideally, provide raw data so that the fitting is reproducible
|
||
|
||
Parameter file format
|
||
---------------------
|
||
|
||
The JSON file produced by ``uv run python -m bam.fit`` is the expected format:
|
||
|
||
.. code-block:: json
|
||
|
||
{
|
||
"model": "m6",
|
||
"actuator": "my_motor",
|
||
"kt": 1.23,
|
||
"R": 4.56,
|
||
"armature": 0.01,
|
||
"friction_base": 0.05,
|
||
"friction_viscous": 0.02,
|
||
"friction_stribeck": 0.08,
|
||
"dtheta_stribeck": 1.5,
|
||
"alpha": 1.2,
|
||
"load_friction_motor": 0.15,
|
||
"load_friction_external": 0.03,
|
||
"load_friction_motor_stribeck": 0.10,
|
||
"load_friction_external_stribeck": 0.04,
|
||
"load_friction_motor_quad": 0.005,
|
||
"load_friction_external_quad": 0.001,
|
||
"q_offset": 0.0
|
||
}
|
||
|
||
The file is generated automatically at the end of a fitting run. No manual
|
||
editing is required.
|
||
|
||
Quality checklist
|
||
-----------------
|
||
|
||
Before submitting, verify:
|
||
|
||
- The identified parameters reproduce recorded trajectories with a reasonable
|
||
MAE (use ``uv run python -m bam.plot --sim`` to inspect the fit visually).
|
||
- The fit was validated on a hold-out set (``--validation_kp``) to check for
|
||
overfitting.
|
||
- All six models (M1–M6) have been fitted so users can choose the complexity
|
||
level appropriate for their use case.
|
||
|
||
Submitting
|
||
----------
|
||
|
||
Open a pull request on the `BAM GitHub repository <https://github.com/Rhoban/bam>`_
|
||
and place your parameter files under:
|
||
|
||
.. code-block:: text
|
||
|
||
bam/params/<motor_name>/m1.json
|
||
bam/params/<motor_name>/m2.json
|
||
...
|
||
bam/params/<motor_name>/m6.json
|
||
|
||
Include a short description of the motor and the identification conditions in
|
||
the pull request body.
|