robot-model-ladders 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. robot_model_ladders-0.2.0.dist-info/METADATA +143 -0
  2. robot_model_ladders-0.2.0.dist-info/RECORD +96 -0
  3. robot_model_ladders-0.2.0.dist-info/WHEEL +4 -0
  4. robot_model_ladders-0.2.0.dist-info/licenses/LICENSE +21 -0
  5. robot_models/__init__.py +18 -0
  6. robot_models/actuators/__init__.py +1 -0
  7. robot_models/actuators/rungs/README.md +24 -0
  8. robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
  9. robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
  10. robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
  11. robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
  12. robot_models/actuators/rungs/datasheet/README.md +65 -0
  13. robot_models/actuators/rungs/datasheet/model.js +14 -0
  14. robot_models/actuators/rungs/datasheet/model.json +138 -0
  15. robot_models/actuators/rungs/datasheet/model.py +24 -0
  16. robot_models/actuators/rungs/dcmotor/README.md +63 -0
  17. robot_models/actuators/rungs/dcmotor/model.json +163 -0
  18. robot_models/actuators/rungs/ideal/README.md +60 -0
  19. robot_models/actuators/rungs/ideal/model.js +6 -0
  20. robot_models/actuators/rungs/ideal/model.json +90 -0
  21. robot_models/actuators/rungs/ideal/model.py +13 -0
  22. robot_models/actuators/rungs/load/README.md +65 -0
  23. robot_models/actuators/rungs/load/model.js +15 -0
  24. robot_models/actuators/rungs/load/model.json +117 -0
  25. robot_models/actuators/rungs/load/model.py +25 -0
  26. robot_models/actuators/rungs/lugre/README.md +72 -0
  27. robot_models/actuators/rungs/lugre/model.js +24 -0
  28. robot_models/actuators/rungs/lugre/model.json +164 -0
  29. robot_models/actuators/rungs/lugre/model.py +30 -0
  30. robot_models/actuators/rungs/ripple/README.md +64 -0
  31. robot_models/actuators/rungs/ripple/model.js +17 -0
  32. robot_models/actuators/rungs/ripple/model.json +119 -0
  33. robot_models/actuators/rungs/ripple/model.py +27 -0
  34. robot_models/actuators/rungs/stribeck/README.md +65 -0
  35. robot_models/actuators/rungs/stribeck/model.js +17 -0
  36. robot_models/actuators/rungs/stribeck/model.json +126 -0
  37. robot_models/actuators/rungs/stribeck/model.py +28 -0
  38. robot_models/actuators/servo/README.md +278 -0
  39. robot_models/actuators/servo/__init__.py +7 -0
  40. robot_models/actuators/servo/bldc/README.md +186 -0
  41. robot_models/actuators/servo/bldc/__init__.py +5 -0
  42. robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
  43. robot_models/actuators/servo/bldc/ladder.py +268 -0
  44. robot_models/actuators/servo/foc_controller/README.md +127 -0
  45. robot_models/actuators/servo/foc_controller/__init__.py +3 -0
  46. robot_models/actuators/servo/foc_controller/ladder.py +207 -0
  47. robot_models/actuators/servo/gearbox/README.md +148 -0
  48. robot_models/actuators/servo/gearbox/__init__.py +5 -0
  49. robot_models/actuators/servo/gearbox/gearbox.py +36 -0
  50. robot_models/actuators/servo/gearbox/ladder.py +214 -0
  51. robot_models/actuators/servo/integrated_servo.py +33 -0
  52. robot_models/actuators/servo/ladder.py +593 -0
  53. robot_models/arms/__init__.py +1 -0
  54. robot_models/arms/rigid_body_chain/README.md +151 -0
  55. robot_models/arms/rigid_body_chain/__init__.py +3 -0
  56. robot_models/arms/rigid_body_chain/ladder.py +228 -0
  57. robot_models/conveyors/__init__.py +1 -0
  58. robot_models/conveyors/conveyor/README.md +140 -0
  59. robot_models/conveyors/conveyor/__init__.py +1 -0
  60. robot_models/conveyors/conveyor/ladder.py +203 -0
  61. robot_models/datasheet/__init__.py +56 -0
  62. robot_models/datasheet/datasheet.py +355 -0
  63. robot_models/datasheet/literal.py +144 -0
  64. robot_models/datasheet/source.py +328 -0
  65. robot_models/datasheet/stated.py +135 -0
  66. robot_models/datasheet/units.py +57 -0
  67. robot_models/end_effectors/__init__.py +1 -0
  68. robot_models/end_effectors/gripper/README.md +112 -0
  69. robot_models/end_effectors/gripper/__init__.py +3 -0
  70. robot_models/end_effectors/gripper/ladder.py +150 -0
  71. robot_models/homing/__init__.py +38 -0
  72. robot_models/homing/cad_bundle.py +206 -0
  73. robot_models/homing/contact.py +201 -0
  74. robot_models/homing/fit.py +126 -0
  75. robot_models/homing/metrics.py +237 -0
  76. robot_models/homing/protocols.py +72 -0
  77. robot_models/homing/types.py +256 -0
  78. robot_models/ladder.py +645 -0
  79. robot_models/markers/__init__.py +1 -0
  80. robot_models/markers/aruco_marker/README.md +92 -0
  81. robot_models/markers/aruco_marker/__init__.py +2 -0
  82. robot_models/markers/aruco_marker/ladder.py +142 -0
  83. robot_models/references.py +429 -0
  84. robot_models/sensors/__init__.py +1 -0
  85. robot_models/sensors/camera/README.md +118 -0
  86. robot_models/sensors/camera/__init__.py +3 -0
  87. robot_models/sensors/camera/ladder.py +108 -0
  88. robot_models/sensors/encoder/README.md +103 -0
  89. robot_models/sensors/encoder/__init__.py +5 -0
  90. robot_models/sensors/encoder/ladder.py +133 -0
  91. robot_models/sensors/hyperspectral_camera/README.md +107 -0
  92. robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
  93. robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
  94. robot_models/sensors/rgbd/README.md +113 -0
  95. robot_models/sensors/rgbd/__init__.py +5 -0
  96. robot_models/sensors/rgbd/ladder.py +113 -0
@@ -0,0 +1,143 @@
1
+ Metadata-Version: 2.5
2
+ Name: robot-model-ladders
3
+ Version: 0.2.0
4
+ Summary: Generic physical models of robot part types (no maker, no SKU): each type a ladder of models from ideal to learned, every rung with its parameters, equation and references.
5
+ Project-URL: Homepage, https://github.com/zacharyyamaoka/robot_models
6
+ Project-URL: Repository, https://github.com/zacharyyamaoka/robot_models
7
+ Project-URL: Issues, https://github.com/zacharyyamaoka/robot_models/issues
8
+ Author: Zach Yamaoka
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: actuators,digital-twin,friction,physical-models,robotics,sensors,sim2real,system-identification
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Scientific/Engineering
23
+ Classifier: Topic :: Scientific/Engineering :: Physics
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: numpy>=1.26
26
+ Requires-Dist: robot-msgs>=0.3.0
27
+ Provides-Extra: contact
28
+ Requires-Dist: coal<3.1,>=3.0.2; extra == 'contact'
29
+ Requires-Dist: trimesh>=4.0; extra == 'contact'
30
+ Provides-Extra: test
31
+ Requires-Dist: coal==3.0.2; extra == 'test'
32
+ Requires-Dist: pytest>=8; extra == 'test'
33
+ Requires-Dist: trimesh>=4.0; extra == 'test'
34
+ Description-Content-Type: text/markdown
35
+
36
+ # robot_models
37
+
38
+ Generic physical models of robot part **types** (no maker, no SKU): each type is a ladder of models from ideal to
39
+ learned, and every rung states its parameters, its equation and its references.
40
+
41
+ ```
42
+ robot_msgs ← robot_models ← robot_parts ← robot_descriptions, with sim2real on top
43
+ ```
44
+
45
+ - [robot_msgs](https://github.com/zacharyyamaoka/robot_msgs): the message types this package builds on.
46
+ - [sim2real](https://github.com/zacharyyamaoka/sim2real): the outer API (twins, calibration) over the stack.
47
+ - robot_parts (robotparts, private): the part catalogue, whose parts point at these types and rungs.
48
+ - Type data only: parameter names, SI units, definitions, equations. Never a value measured on one unit.
49
+
50
+ ## Usage
51
+
52
+ ```python
53
+ from robot_models.ladder import ladders, needs
54
+
55
+ servo = ladders()["integrated_servo"]
56
+ servo.parameters("M3.stribeck") # what the rung needs, inherited names included:
57
+ # ('output_inertia', 'gear_ratio', 'coulomb_friction', 'viscous_friction', 'breakaway_torque', 'stribeck_velocity')
58
+ servo.holds("M3.stribeck") # ... plus what it reads when a source states it
59
+ servo.fallback("M3.lugre") # the chain it falls back down:
60
+ # ('M3.lugre', 'M3.stribeck', 'M2.coulomb_viscous', 'M1.datasheet', 'M0.ideal')
61
+ servo.canonical("frictionloss_nm") # 'coulomb_friction': any other name resolves to the type's own
62
+ servo.unpack("thermal_r_c") # ('thermal_resistance', 'thermal_time_constant'): a packed array
63
+ servo.rung("M3.stribeck").equation # 'tau_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(...)'
64
+ needs(ladders(), "integrated_servo", "M4.drivetrain") # {type: names}, the composed driver's included
65
+ ```
66
+
67
+ - A rung key is `M{level}.{name}`: M0 ideal, M1 datasheet, M2 Coulomb + viscous, M3 state-dependent friction,
68
+ M4 drivetrain, M5 electrics and heat, M6 grey-box residual, M7 learned net; `.wear` variants grow a parameter with use.
69
+ - Each ladder is a tree of explicit bases; a rung needs everything its base needs.
70
+ - Every other name for a quantity is an `Alias` (with a note when it is not the same quantity one for one) or a
71
+ `Packed` array; what a deployment sets (gains, caps) is `DeploymentOnly`, never on a rung.
72
+ - Spec: [PEP 0004](docs/peps/0004-model-ladders-by-type.md).
73
+
74
+ ## The 12 types (84 rungs)
75
+
76
+ | type | folder (`src/robot_models/…`) | rungs | what it is |
77
+ |---|---|---:|---|
78
+ | `integrated_servo` | `actuators/servo/` | 14 | A joint in one housing: motor, drive, reducer or none, encoder |
79
+ | `bldc_motor` | `actuators/servo/bldc/` | 9 | A brushless motor alone, at its shaft |
80
+ | `gearbox` | `actuators/servo/gearbox/` | 8 | A gear stage between a motor and its load |
81
+ | `foc_controller` | `actuators/servo/foc_controller/` | 6 | A field-oriented-control motor drive board |
82
+ | `encoder` | `sensors/encoder/` | 4 | An angle sensor on a shaft |
83
+ | `camera` | `sensors/camera/` | 6 | A frame camera's colour image: projection, distortion, exposure |
84
+ | `depth_camera` | `sensors/rgbd/` | 5 | A stereo depth camera: depth on top of a colour stream |
85
+ | `hyperspectral_camera` | `sensors/hyperspectral_camera/` | 5 | A line-scan spectral camera over a belt |
86
+ | `rigid_body_chain` | `arms/rigid_body_chain/` | 10 | A chain of rigid links and joints, open or closed: an arm, a wrist, a five-bar |
87
+ | `gripper` | `end_effectors/gripper/` | 6 | An end effector that grasps, on a chain's flange |
88
+ | `conveyor` | `conveyors/conveyor/` | 7 | A belt driven through a drum |
89
+ | `aruco_marker` | `markers/aruco_marker/` | 4 | A printed sheet carrying ArUco markers rigidly |
90
+
91
+ Each folder holds one `ladder.py`; `ladders()` finds them by walking the package (no registry). The integrated servo's
92
+ eight rung folders (`actuators/rungs/<rung>/`: `model.json`, a README, and Python + JavaScript code where the rung has
93
+ its own) are byte-pinned, so a downstream copy can be checked against them.
94
+
95
+ ## Other modules
96
+
97
+ - `robot_models.datasheet`: typed part fields, and a part's values resolved from one Python file per raw source
98
+ ([PEP 0003](docs/peps/0003-typed-datasheets-from-sources.md)). Stdlib only.
99
+ - `robot_models.actuators.servo`: the servo type tree (`IntegratedServo`, `BldcMotor`, `Gearbox`), the typed fields
100
+ each ladder's M1 states.
101
+ - `robot_models.homing`: the homing stop core: stops, the backlash ladder, stall evidence, the pure fit, the bench's
102
+ five metrics ([PEP 0001](docs/peps/0001-homing-stop-core.md), [PEP 0002](docs/peps/0002-homing-bench.md)).
103
+ numpy + robot_msgs only; exact mesh contact (`homing.contact`, `homing.cad_bundle`) is the `contact` extra.
104
+ - The ladder core (`robot_models.ladder`) and the citable works (`robot_models.references`) are stdlib only.
105
+
106
+ ## Install
107
+
108
+ ```bash
109
+ pip install robot-model-ladders
110
+ uv add robot-model-ladders
111
+ ```
112
+
113
+ - The PyPI name is robot-model-ladders (robot-models is taken by a near-identical name); you still `import robot_models`.
114
+ - robot-msgs 0.3.0 or later comes with it. The ladders and the datasheets import neither robot_msgs nor numpy.
115
+ - Mesh contact for homing: add the extra, `robot-model-ladders[contact]`.
116
+ - Python 3.11 to 3.14.
117
+
118
+ ## Tests
119
+
120
+ From a clone (`--no-sources` because `[tool.uv.sources]` names the author's local robot_msgs checkout):
121
+
122
+ ```bash
123
+ uv run --isolated --no-sources --extra test python -m pytest -q --ignore=tests/test_fit_ruler.py --ignore=tests/test_stop_ruler.py
124
+ ```
125
+
126
+ - That is what CI runs (`.github/workflows/test.yml`, Python 3.11–3.14).
127
+ - `tests/test_fit_ruler.py` and `tests/test_stop_ruler.py` read CAD bundles from a local, unpublished cache
128
+ (`ROBOT_MODELS_CAD_BUNDLES`, default `~/.cache/cad2robot-build/bundles`); with that cache, drop the two `--ignore`s.
129
+ - `PYTHONDONTWRITEBYTECODE=1` keeps `__pycache__/` out of the rung folders, which robotparts vendors byte for byte.
130
+
131
+ ## Design records
132
+
133
+ [docs/peps/](docs/peps/), each a decision with its undo:
134
+
135
+ - [0001](docs/peps/0001-homing-stop-core.md): the homing stop core lives in robot_models
136
+ - [0002](docs/peps/0002-homing-bench.md): the homing bench's pure parts: five metrics, two seams
137
+ - [0003](docs/peps/0003-typed-datasheets-from-sources.md): typed datasheets, resolved from one Python file per source
138
+ - [0004](docs/peps/0004-model-ladders-by-type.md): model ladders by type: one vocabulary per type, rungs as a tree of
139
+ bases
140
+
141
+ ## License
142
+
143
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,96 @@
1
+ robot_models/__init__.py,sha256=K3P58GtlV8_LluLtoqcA4Jj1B8yCVIIV1YxelLhktWQ,1161
2
+ robot_models/ladder.py,sha256=rVxvwfKRNkGLYpjMgejk7wWmKUKQsbz1D701PObRwgs,34830
3
+ robot_models/references.py,sha256=BYq3Ly6622lysCE61J-OYgnfXp8vCXlJbmk54_svqnI,17393
4
+ robot_models/actuators/__init__.py,sha256=hh8k4CZ1lmByjLT4zQJrPkxpuIqau-4ZDO5w5m4D9F8,116
5
+ robot_models/actuators/rungs/README.md,sha256=DcPWfS5GeBJWFYg2-MMLWbTfJDt9pEjnGphAXuoxrCg,1722
6
+ robot_models/actuators/rungs/coulomb_viscous/README.md,sha256=Upwr8flotnrfWAampJ2aGS396zax2AX5mgTgLRivZTA,3497
7
+ robot_models/actuators/rungs/coulomb_viscous/model.js,sha256=W4ExzgrNPw2ESYX7iI0O-R1VM0LqKYCJaQGwENsMHgA,651
8
+ robot_models/actuators/rungs/coulomb_viscous/model.json,sha256=FjimFAX35Ug12AljOomcZSdJ_ddzeAMB5a4av_Y04Kg,3585
9
+ robot_models/actuators/rungs/coulomb_viscous/model.py,sha256=4g1vQVgiVyu4nzBTRNzj78ZZqdsoIqNDABQa-lZlsJU,1124
10
+ robot_models/actuators/rungs/datasheet/README.md,sha256=QRGZAaYvPTW9Gv-mBSUFFBvLTTdBiJbKfzJJoWKXwrM,3835
11
+ robot_models/actuators/rungs/datasheet/model.js,sha256=uwVIlOkBodZGRUXvu-DoGXXFvkzYRj6sEFwBmF5kxB4,655
12
+ robot_models/actuators/rungs/datasheet/model.json,sha256=A7I0p_IiIM0erkJe3KOvbZ6hmrQaivgS_JGp_a63Tmw,4506
13
+ robot_models/actuators/rungs/datasheet/model.py,sha256=PtXn2NkNmO_sCvhJV_JxyiDzZcYvZgc5viW4zK0ewtw,1130
14
+ robot_models/actuators/rungs/dcmotor/README.md,sha256=qryevOcl3PsrPuQcFuAeMuhdQ-p8QcCcshLtcpSXCfc,4891
15
+ robot_models/actuators/rungs/dcmotor/model.json,sha256=z65Q-FbbZRhRnswYgXtXRTYaOwNouFhmQQlvRmhAWTE,5797
16
+ robot_models/actuators/rungs/ideal/README.md,sha256=I-RT1Jid-fAdeIcUAmZVB57UKEwCpGg-IEWBgV7LcQM,2836
17
+ robot_models/actuators/rungs/ideal/model.js,sha256=UzZo0z405n1ebR3MBP3z8_nRtdfUCff2fCZNgIoo6AU,313
18
+ robot_models/actuators/rungs/ideal/model.json,sha256=S87o3n1vE5DZSSEV4FAm2KXWfzc0EgzMPeC5XSX8guI,2907
19
+ robot_models/actuators/rungs/ideal/model.py,sha256=umszpMvSiup8sYdObmRun13TTGejMpDLSJKWrtoNS3Y,701
20
+ robot_models/actuators/rungs/load/README.md,sha256=Jhvz5ZdRF7ubDb_3lRgwkoSBSWl_Y7nlgPTS3y332wo,3762
21
+ robot_models/actuators/rungs/load/model.js,sha256=1Q6yIiA5AZSXqhGXKspUeadRekKe8rmcKM2GVcmzoNA,789
22
+ robot_models/actuators/rungs/load/model.json,sha256=_JFd2PAUdoOOuwgd51s3sSs-0uACq7wHVHiag5b20Vc,4133
23
+ robot_models/actuators/rungs/load/model.py,sha256=A7XLEkrUpmv_oymLT8z4MfF8M8FH0VxD2Z70SSBYcDM,1266
24
+ robot_models/actuators/rungs/lugre/README.md,sha256=ZX6XflM1j7tTJN6vBZKEuFaTuuocA1WQTmlarbd85VI,4484
25
+ robot_models/actuators/rungs/lugre/model.js,sha256=6OQu4z2Kz-8_p75lQsaO4GwWX_HcLz3Wd4dCSgAJywo,910
26
+ robot_models/actuators/rungs/lugre/model.json,sha256=VgogKeiEZHSjV0ZvvLWERRqBw_md1VBwFemgaRT9iKo,5637
27
+ robot_models/actuators/rungs/lugre/model.py,sha256=Y8uT0gMl64v-duf6KJmSjHJetd41S0VhmDDH701ZzeA,1398
28
+ robot_models/actuators/rungs/ripple/README.md,sha256=3lWcA-bH2-LKPusuwH5e0M4baLW9JGytwu5G_zdLs68,4089
29
+ robot_models/actuators/rungs/ripple/model.js,sha256=MfCFd7qMzfPBLdi75nKmeshw6Uscy2_DSPxkywZA3bo,811
30
+ robot_models/actuators/rungs/ripple/model.json,sha256=Qmt_8bZMbJw_Icj6_UuiCeGyPIQj9tNXguIBidMeG24,4541
31
+ robot_models/actuators/rungs/ripple/model.py,sha256=4w614-18SuCbBvxEjjHlLIHlpMrZvT6dDmG1BMbQOVw,1372
32
+ robot_models/actuators/rungs/stribeck/README.md,sha256=WhwmShBfFCW5GHEObkeLyZgL_-sueMiTJzsdcgF7lsw,3968
33
+ robot_models/actuators/rungs/stribeck/model.js,sha256=Fb21qxZtqBjeIyAeWPUk0c-14GBKpk7K2fLOUdaPHDQ,827
34
+ robot_models/actuators/rungs/stribeck/model.json,sha256=M2si6LYUKLXMWKJFBNcRd4pZtFXCmHUVLg2n_vt3uNg,4476
35
+ robot_models/actuators/rungs/stribeck/model.py,sha256=h_m8i-zZ3V234YEbNJ-5brMeQiQ1q0wY7UPberOVKls,1400
36
+ robot_models/actuators/servo/README.md,sha256=K2Lu_0mVlgy24VUjZpdeU8JY6ObzHWvOcoi-hwzWje8,42436
37
+ robot_models/actuators/servo/__init__.py,sha256=jmZ96RD8o0cScmhWdULBtRtoIhq8ZfDegIliKlN9Ufg,278
38
+ robot_models/actuators/servo/integrated_servo.py,sha256=V0BhvOMKd6yeEjN-6KbUulHoZs2uNG-9KtwDko0_AGE,2039
39
+ robot_models/actuators/servo/ladder.py,sha256=p_4bUrGfh_AOoROMWbUkoPV9c0l4OjzLvI0Gz2bCBJ0,25610
40
+ robot_models/actuators/servo/bldc/README.md,sha256=fHaNSk4h6wWrUAWz3NWQ84_YcdDvO-EjKGalBENaELM,24404
41
+ robot_models/actuators/servo/bldc/__init__.py,sha256=6tQFAdUCsCN4mOfkj7T3IgTolOQhKTNt4vO06VSeFMk,124
42
+ robot_models/actuators/servo/bldc/bldc_motor.py,sha256=6nd-p5EuGbd9AgRWgWLORfzAiyz0XvEd2fiK5XZT0fs,6384
43
+ robot_models/actuators/servo/bldc/ladder.py,sha256=bVhLMu7Ik-oAN944XxjK9Rx1z5vsB8_VpItasYsj26A,14046
44
+ robot_models/actuators/servo/foc_controller/README.md,sha256=j4g6czt_PGaN7TXlnQzyxBboX4TtGXUJximylrCJxNc,11753
45
+ robot_models/actuators/servo/foc_controller/__init__.py,sha256=jPKc90ltNKp-VXqVyvFIt5Kmuq_wMBc9_PBJOZ_jPyY,235
46
+ robot_models/actuators/servo/foc_controller/ladder.py,sha256=HJRtItKfLyeYuCcr7xhBGQWu2rJowjvuu9q_HjFsLhM,7704
47
+ robot_models/actuators/servo/gearbox/README.md,sha256=PRjPdMm9C0NwY2--16QDEIKp97JDW2svsjSnOwKmDDE,17247
48
+ robot_models/actuators/servo/gearbox/__init__.py,sha256=j5HIV5Fn3teH3pBrZorVRFYJ5UjM0v8Lag8ZsXzUsMk,125
49
+ robot_models/actuators/servo/gearbox/gearbox.py,sha256=QlizakS0lows7wIGcFhdFmUtd7JDr0aBSQOVdbsdV3U,2257
50
+ robot_models/actuators/servo/gearbox/ladder.py,sha256=r6VWN6DIe_PIBAyLIzQdXiIe_jdzmpruCcbcBpRMrAc,8711
51
+ robot_models/arms/__init__.py,sha256=xah43O27JPZ-oDq3PpXnyvNo6_XsKaDQawQHj7MEwIk,114
52
+ robot_models/arms/rigid_body_chain/README.md,sha256=7t0UVCzzIvxznAs4-W-ss8UflmE_tui0eUlR3EOJX70,17747
53
+ robot_models/arms/rigid_body_chain/__init__.py,sha256=WGzpEaNfB95PfxSUAi2ZR8--AAT3z2ONUDC70NlyHAI,331
54
+ robot_models/arms/rigid_body_chain/ladder.py,sha256=sH1URvZ5CzX4X86P3wGJNkp1C0a_kQP63xrORvcBxMU,9240
55
+ robot_models/conveyors/__init__.py,sha256=Nhh5skc9PWjiXPzpGGxgA7iwYRrBAmJJ4MRhHrneObE,59
56
+ robot_models/conveyors/conveyor/README.md,sha256=ygHNcq0PMJw-3YFeRFV2Av80lJFDFSrd1cnoqA6qNTM,14176
57
+ robot_models/conveyors/conveyor/__init__.py,sha256=EhKN-YdAru4xYkDt0SZrLNf4dPFkmfV5c5wcPzUbwxU,116
58
+ robot_models/conveyors/conveyor/ladder.py,sha256=F2Cd-phh139sDKelMHpeYJPtdFAakn4fwH_bN_iHSDo,8879
59
+ robot_models/datasheet/__init__.py,sha256=Q4IKQJ6nHUVnI9Rq2A6JqLTZRSNuqSZHh3lJ2ba-mi8,1333
60
+ robot_models/datasheet/datasheet.py,sha256=IGyyoipIKkd-BZTP9Na9KndWZhu-_1j2HyaukaLHA6A,17595
61
+ robot_models/datasheet/literal.py,sha256=2WImkzzH5sVQr8xkD7DU1mcwUn6eK4T4cfBOII_D1so,7883
62
+ robot_models/datasheet/source.py,sha256=MTqiZ-kCW-DtPZvFXqICsoTrZ2zSLPXeiYkWttb43Qk,16549
63
+ robot_models/datasheet/stated.py,sha256=fn6SXK0sp3CqgnV6e2VKbGv86iAf-5ouY9r5_x3tML4,5905
64
+ robot_models/datasheet/units.py,sha256=FW4YDuu0X0FPEAcwKDpFLqqQ5npPcTttHgOVR0CUrnQ,2605
65
+ robot_models/end_effectors/__init__.py,sha256=LPnEbwkZ0IDJ9NYSIruaMRuKDU_Oew5NdWfKIOXOoik,62
66
+ robot_models/end_effectors/gripper/README.md,sha256=ijCIItVsPrtfTkMb3Sdi3z3J_u74XMCL8kRt-Jqa3s4,9660
67
+ robot_models/end_effectors/gripper/__init__.py,sha256=7szrDIIIAJpUA4BG-dmHMI_pCw4kM1I0C0-kikpk_W4,275
68
+ robot_models/end_effectors/gripper/ladder.py,sha256=gYrqaprt-KgWVcJXvqFkU3NZ11Qd3ncYpZSeUiZzYaM,5280
69
+ robot_models/homing/__init__.py,sha256=ResL6niHxAU0pVpdhxsV4y7hEjex3y1ZEkywKH-tZtQ,812
70
+ robot_models/homing/cad_bundle.py,sha256=IPs6ge6i3Bjn0S9pxSBQhdPSlul5RKGIDRd52lXTccc,8709
71
+ robot_models/homing/contact.py,sha256=dB4TczOXG6qQe6dIn43Pfjz0kmPE1qfwGjZeu6p6S7U,7759
72
+ robot_models/homing/fit.py,sha256=zbPslWSAp-PjzRkNUSEvpqtOFrQstNbOD8d556pULQk,5035
73
+ robot_models/homing/metrics.py,sha256=CNk0cIBHadYzPBaUTOvB6L38x1f1Nsom2oSjSchyQdI,8715
74
+ robot_models/homing/protocols.py,sha256=BZdM336HzqsUuwEsmpAiyRcwb_bl7XI0wGeeWrw0WuY,2670
75
+ robot_models/homing/types.py,sha256=9G-eTT18oKFK3jYyVVMe6kAQmPTmi6NTxy8hwRBddXg,9303
76
+ robot_models/markers/__init__.py,sha256=hf3E4izuNuPkwyV-co2kEBJUsgMmo_AA9O6fSwQFAzU,61
77
+ robot_models/markers/aruco_marker/README.md,sha256=RyY7vPMURjpehCjFY_gQxDVCGW-eo9OzTnNcARvMkhY,6983
78
+ robot_models/markers/aruco_marker/__init__.py,sha256=dCbaF-rTVU1BR4xXpZr25LESZy5ONmQvkWuTgBP6zHc,239
79
+ robot_models/markers/aruco_marker/ladder.py,sha256=ne2tYt-cZ92W4g63nZBrW3L2zOeb0Hx5CvMKVtScqdw,4474
80
+ robot_models/sensors/__init__.py,sha256=TxGpYeGHVYHYT5kBxuDYII0Fz-iyzWuULkza_G0-C-Y,114
81
+ robot_models/sensors/camera/README.md,sha256=eQV44GjWjct1LmI1kKdgHIzr0RRY64FfGE4Vf1dvAIQ,10648
82
+ robot_models/sensors/camera/__init__.py,sha256=MDOUWriDoSCdOGxFjQpegcCuLj_K9k_4IkFz0O-pqV0,304
83
+ robot_models/sensors/camera/ladder.py,sha256=K0rSOPKPivak_YTrluvf-P4sz8IF2XyTgho54doeS1U,5442
84
+ robot_models/sensors/encoder/README.md,sha256=L-7XFkUlyyhuUbsqhv43YPVsW6XIeFDfsYPYnFsZtP0,8088
85
+ robot_models/sensors/encoder/__init__.py,sha256=XoUjnGCBoR8FoPvnPawNMaQ-C5tnSXNY4K4MNIZKTgk,353
86
+ robot_models/sensors/encoder/ladder.py,sha256=JtplACJhFUdseOBR9t1Hh_yyyVFHqOzqfl_XnPV8-94,4868
87
+ robot_models/sensors/hyperspectral_camera/README.md,sha256=WkINlzQvIOUWEs9PBXSVByI5J92WHHlmhYLZLt4_l88,8853
88
+ robot_models/sensors/hyperspectral_camera/__init__.py,sha256=OtEZKx8TqeErSq9I7_b6vrvYtNX4fsfXELgqKMfRPLM,113
89
+ robot_models/sensors/hyperspectral_camera/ladder.py,sha256=xjOvnZFeSCJtzq5YmQIliwft_2eyOr6HWIk9UzUVLDY,5581
90
+ robot_models/sensors/rgbd/README.md,sha256=yRmI146RjHZG21ICCEDuGeK-mrxdtn5dvrl9mCJP0LM,9325
91
+ robot_models/sensors/rgbd/__init__.py,sha256=tnapkxEnwr5AiJGwpqTNfEnIf4SlD7scxWCVaCrtfXw,302
92
+ robot_models/sensors/rgbd/ladder.py,sha256=IuJiUMQkH4gC0yEzS-G0EC9Avc5ln7Ox3kjkox9eMAw,5395
93
+ robot_model_ladders-0.2.0.dist-info/METADATA,sha256=Pa1rbomFlZqHFSh8aCYaeLjVQptMBEyo7eUIObDHFdI,7953
94
+ robot_model_ladders-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
95
+ robot_model_ladders-0.2.0.dist-info/licenses/LICENSE,sha256=h8fsof9VA84kQmejTwDwFeJXJLVah9Y_rs_WJWgxp1g,1069
96
+ robot_model_ladders-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zach Yamaoka
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,18 @@
1
+ """robot_models -- generic physical models of robot part types (no maker, no SKU): each type a ladder of
2
+ models from ideal to learned, every rung with its parameters, equation and references.
3
+
4
+ Layering (Robot Models Layering decision, 2026-11-12, in the order PEP 0004 corrected it to)::
5
+
6
+ robot_msgs <- robot_models <- robot_parts <- robot_descriptions; sim2real on top
7
+
8
+ ``robot_models.ladder`` (the type ladders; ``ladders()`` finds each type's ``ladder.py``) and
9
+ ``robot_models.references`` (the works the rungs cite), docs/peps/0004-model-ladders-by-type.md.
10
+ ``robot_models.homing`` (docs/peps/0001-homing-stop-core.md), ``robot_models.datasheet`` and the type tree
11
+ ``robot_models.actuators.servo`` (docs/peps/0003-typed-datasheets-from-sources.md). The package imports numpy
12
+ and robot_msgs only (the ladder core, the references, the datasheet and the types: the stdlib only); mesh
13
+ contact is the ``contact`` extra.
14
+ """
15
+
16
+ # WHY a literal, kept equal to pyproject.toml's version (CI asserts it against the built metadata): reading
17
+ # importlib.metadata here costs ~11 ms on every import and returns a stale editable install's number.
18
+ __version__ = "0.2.0"
@@ -0,0 +1 @@
1
+ """Part types by type folder, mirroring robotparts' user/parts tree (PEP 0003): actuators/servo/{bldc,gearbox}/."""
@@ -0,0 +1,24 @@
1
+ # Actuator rung definitions
2
+
3
+ These eight folders (`ideal`, `datasheet`, `coulomb_viscous`, `stribeck`, `load`, `lugre`, `ripple`, `dcmotor`) are the
4
+ canonical rung definitions of the `integrated_servo` ladder (PEP 0004 section 8.1). robotparts vendors them
5
+ byte-identical under `models/actuator/<word>/` because its published rung bytes are pinned by sha256.
6
+
7
+ ## Paths inside the copied files
8
+
9
+ The files were written in [robotparts](https://github.com/zacharyyamaoka/robotparts) and are kept exactly as it wrote
10
+ them, so some paths inside them point at robotparts, not at this repo. These live in robotparts and do not exist here:
11
+ `SCHEMA2.md` (section 4.3.2), `schemas/model.schema.json`, `robotparts.models.si_terms`, the `robotparts.mujoco` plugin,
12
+ and `tests/acceptance_v2/test_amendment_2_5.py` (the Python/JS parity test that holds `model.py` and `model.js` to 1e-12).
13
+ robot_models does not check that parity; robotparts does.
14
+
15
+ ## Changing a rung
16
+
17
+ Edit it here, then run robotparts' `tools/sync_actuator_rungs.py` (it copies the files over; `--check` lists every
18
+ difference without writing). Keep each folder to its regular files: no `__init__.py`, no `__pycache__`, no dot-files.
19
+ `.gitattributes` marks this tree `-text` so no checkout rewrites a line ending.
20
+
21
+ WHY every byte is pinned in three places, so a change moves all three together: the `RUNG_FILES` sha256 table in
22
+ `tests/test_ladders_acceptance.py`; each `model.json`'s `implementation_sha256` for `model.py` and `model.js`; and
23
+ robotparts' published fits' `definition_sha256`. PEP 0004 section 8.1 also says a definition a fit binds is never
24
+ edited away, so a change to a published rung is a new definition (a new rung or version), not an in-place edit.
@@ -0,0 +1,61 @@
1
+ # M2.coulomb_viscous — Coulomb and viscous friction
2
+
3
+ **Coulomb + viscous.** Family: fitted constant friction. Rung: 2, fitted constant friction. Category: actuator.
4
+
5
+ Constant (Coulomb) friction that flips with direction, plus a viscous drag that grows with speed. MuJoCo expresses both natively (frictionloss and damping), so it runs anywhere with no plugin. On the rack it is the first fitted rung, and the backend matters more than the terms: MuJoCo's default friction constraint creeps below about 0.4 rad/s on a light hinge, and a hard solreffriction fixes it.
6
+
7
+ **When to use it.** Use it as the first fitted model; measure it with velocity plateaus in both directions.
8
+
9
+ ## Equation
10
+
11
+ ```
12
+ tau_r = coulomb_friction*sign(v) + viscous_friction*v
13
+ ```
14
+
15
+ Output `tau_r` (N·m): The resisting torque at the output: what the motor must add to move the output as the inputs say. The joint feels -tau_r (a resisting torque opposes motion; ripple pushes and pulls with angle).
16
+
17
+ ## Terms
18
+
19
+ | term | required | unit (SI) | units a fit may use | measured by |
20
+ |---|---|---|---|---|
21
+ | `coulomb_friction` | yes | N·m | N·m, mN·m | velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn |
22
+ | `viscous_friction` | yes | N·m·s/rad | N·m·s/rad, mN·m·s/rad | velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn |
23
+ | `output_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | chirps (or the datasheet) |
24
+
25
+ Declared terms (the rest are registry keys, defined in SCHEMA2.md §7.3):
26
+
27
+ - none
28
+
29
+ ## Inputs and state
30
+
31
+ - input `v` (rad/s): The output's angular speed.
32
+
33
+ ## Backends
34
+
35
+ | backend | how | engine | what runs |
36
+ |---|---|---|---|
37
+ | python | reference | — | `model.py` (sha256 `e20d6f415822…`). The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI. |
38
+ | js | reference | — | `model.js` (sha256 `5b8131ce0acd…`). The same equation as model.py as an ES module (torque(terms, inputs, state, dt) -> {tau, state}); tests/acceptance_v2/test_amendment_2_5.py holds the two to 1e-12. |
39
+ | mujoco | native | mujoco, release named by the fit | frictionloss sticks at rest as a constraint (set friction_solref hard, or it creeps); damping is the viscous term. Maps: armature = `output_inertia`, frictionloss = `coulomb_friction`, damping = `viscous_friction`. |
40
+
41
+ **mujoco settings** a fit may state:
42
+
43
+ - `friction_solref`: 2 numbers. The joint's solreffriction (timeconst, dampratio): how hard frictionloss sticks; MuJoCo's soft default creeps below about 0.4 rad/s on a light hinge.
44
+ - `friction_solimp`: 5 numbers, in (0, inf). The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.
45
+
46
+ ## Validity
47
+
48
+ - A fit states the range of `output_speed` (rad/s) it holds across: |v|, the output speed the terms were fitted or checked across.
49
+ - Friction does not depend on speed beyond the viscous slope, on load, on temperature or on how long the part rested.
50
+
51
+ ## Use it
52
+
53
+ ```python
54
+ import importlib.util
55
+ spec = importlib.util.spec_from_file_location("coulomb_viscous", "model.py")
56
+ model = importlib.util.module_from_spec(spec); spec.loader.exec_module(model)
57
+ terms = {...} # a fit's terms in SI (robotparts.models.si_terms(fit, definition) converts them)
58
+ tau_r, state = model.torque(terms, {"v": 0.0}, None, 0.001)
59
+ ```
60
+
61
+ Defined since robotparts/2.3. It is robotparts/2.3's `coulomb_viscous` kind. The contract is SCHEMA2.md §4.3.2; the fit format is `schemas/model.schema.json`.
@@ -0,0 +1,14 @@
1
+ // Coulomb and viscous friction (M2.coulomb_viscous): the reference backend as an ES module, the same equation as model.py.
2
+ // torque(terms, inputs, state, dt) -> {tau, state}; terms and inputs in SI; the joint feels -tau.
3
+
4
+ const sign = (x) => (x > 0) - (x < 0);
5
+
6
+ export function torque(terms, inputs, state = {}, dt = null) {
7
+ const v = inputs.v;
8
+ return { tau: terms.coulomb_friction * sign(v) + terms.viscous_friction * v, state: { ...state } };
9
+ }
10
+
11
+ // The level the friction holds at rest: the exact limit at v -> 0+ (see model.py's static_level).
12
+ export function static_level(terms, inputs = {}, state = {}) {
13
+ return terms.coulomb_friction;
14
+ }
@@ -0,0 +1,102 @@
1
+ {
2
+ "format": "robotparts-model-definition/1",
3
+ "category": "actuator",
4
+ "word": "coulomb_viscous",
5
+ "rung": 2,
6
+ "name": "M2.coulomb_viscous",
7
+ "family": "fitted constant friction",
8
+ "title": "Coulomb and viscous friction",
9
+ "description": "Coulomb + viscous",
10
+ "summary": "Constant (Coulomb) plus viscous friction at the output, fitted from measurements: MuJoCo's frictionloss and damping, so its simulator is optional.",
11
+ "equation": "tau_r = coulomb_friction*sign(v) + viscous_friction*v",
12
+ "since": "robotparts/2.3",
13
+ "v2_3_kind": "coulomb_viscous",
14
+ "inputs": {
15
+ "v": {
16
+ "definition": "The output's angular speed.",
17
+ "unit": "rad/s"
18
+ }
19
+ },
20
+ "state": {},
21
+ "output": {
22
+ "name": "tau_r",
23
+ "definition": "The resisting torque at the output: what the motor must add to move the output as the inputs say.",
24
+ "unit": "N·m",
25
+ "sign": "The joint feels -tau_r (a resisting torque opposes motion; ripple pushes and pulls with angle)."
26
+ },
27
+ "terms": {
28
+ "coulomb_friction": {
29
+ "required": true,
30
+ "key": true,
31
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
32
+ },
33
+ "viscous_friction": {
34
+ "required": true,
35
+ "key": true,
36
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
37
+ },
38
+ "output_inertia": {
39
+ "required": false,
40
+ "key": true,
41
+ "measured_by": "chirps (or the datasheet)"
42
+ }
43
+ },
44
+ "together": [],
45
+ "exclusive": [],
46
+ "constraints": [],
47
+ "variants": {},
48
+ "backends": {
49
+ "python": {
50
+ "how": "reference",
51
+ "implementation": "model.py",
52
+ "implementation_sha256": "e20d6f415822572bb89f305344dce3efc659a9db2822a34300141afa5665b095",
53
+ "engine": null,
54
+ "note": "The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI."
55
+ },
56
+ "js": {
57
+ "how": "reference",
58
+ "implementation": "model.js",
59
+ "implementation_sha256": "5b8131ce0acd3f0d844985fb888d0ef91d553342ea2980896901b010db0c1e00",
60
+ "engine": null,
61
+ "note": "The same equation as model.py as an ES module (torque(terms, inputs, state, dt) -> {tau, state}); tests/acceptance_v2/test_amendment_2_5.py holds the two to 1e-12."
62
+ },
63
+ "mujoco": {
64
+ "how": "native",
65
+ "engine": "mujoco",
66
+ "maps": {
67
+ "armature": "output_inertia",
68
+ "frictionloss": "coulomb_friction",
69
+ "damping": "viscous_friction"
70
+ },
71
+ "settings": {
72
+ "friction_solref": {
73
+ "definition": "The joint's solreffriction (timeconst, dampratio): how hard frictionloss sticks; MuJoCo's soft default creeps below about 0.4 rad/s on a light hinge.",
74
+ "value": "number-list",
75
+ "length": 2
76
+ },
77
+ "friction_solimp": {
78
+ "definition": "The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.",
79
+ "value": "number-list",
80
+ "length": 5,
81
+ "bounds": {
82
+ "min": 0,
83
+ "min_exclusive": true
84
+ }
85
+ }
86
+ },
87
+ "note": "frictionloss sticks at rest as a constraint (set friction_solref hard, or it creeps); damping is the viscous term."
88
+ }
89
+ },
90
+ "validity": {
91
+ "dims": {
92
+ "output_speed": {
93
+ "definition": "|v|, the output speed the terms were fitted or checked across.",
94
+ "unit": "rad/s"
95
+ }
96
+ },
97
+ "assumptions": [
98
+ "Friction does not depend on speed beyond the viscous slope, on load, on temperature or on how long the part rested."
99
+ ]
100
+ },
101
+ "readme": "README.md"
102
+ }
@@ -0,0 +1,24 @@
1
+ """Coulomb and viscous friction (M2.coulomb_viscous): the reference backend, stdlib only. robotparts/2.5, SCHEMA2.md §4.3.2.
2
+
3
+ torque(terms, inputs, state=None, dt=None) -> (tau_r, state). terms are SI values by name (a fit's terms converted
4
+ with the units its definition declares), inputs the model.json inputs in SI. tau_r is the resisting torque at the
5
+ output: the joint feels -tau_r. sign(0) is 0, so a model at rest resists nothing here; a backend that sticks at rest
6
+ (MuJoCo's frictionloss) does that part natively.
7
+ """
8
+
9
+ import math
10
+
11
+ def _sign(x):
12
+ return (x > 0) - (x < 0)
13
+
14
+
15
+ def torque(terms, inputs, state=None, dt=None):
16
+ v = inputs["v"]
17
+ return terms["coulomb_friction"] * _sign(v) + terms["viscous_friction"] * v, dict(state or {})
18
+
19
+
20
+ def static_level(terms, inputs, state=None):
21
+ """The level the friction holds at rest: the exact limit of the resisting torque's friction part as v -> 0+
22
+ (judge r3 #2: a backend that sticks natively, MuJoCo's frictionloss, holds this, never a torque sampled at a small
23
+ speed). The state is read, never advanced."""
24
+ return float(terms["coulomb_friction"])
@@ -0,0 +1,65 @@
1
+ # M1.datasheet — The datasheet
2
+
3
+ **the stated values.** Family: datasheet. Rung: 1, the datasheet. Category: actuator.
4
+
5
+ The datasheet model holds what the maker states and nothing fitted: inertia, ratio, torque constant, and friction only if the datasheet gives it. The build checks every term against the part's own specs, so a model called datasheet can never carry a fitted number.
6
+
7
+ **When to use it.** Use it before anything is measured, and as the honest answer to "what does the maker claim?".
8
+
9
+ ## Equation
10
+
11
+ ```
12
+ tau_r = coulomb_friction*sign(v) + viscous_friction*v; armature = output_inertia, or gear_ratio^2*(rotor_inertia + gearbox_input_inertia)
13
+ ```
14
+
15
+ Output `tau_r` (N·m): The resisting torque at the output: what the motor must add to move the output as the inputs say. The joint feels -tau_r (a resisting torque opposes motion; ripple pushes and pulls with angle).
16
+
17
+ ## Terms
18
+
19
+ | term | required | unit (SI) | units a fit may use | measured by |
20
+ |---|---|---|---|---|
21
+ | `output_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | reading the datasheet |
22
+ | `rotor_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | reading the datasheet |
23
+ | `gearbox_input_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | reading the datasheet |
24
+ | `gear_ratio` | no | 1 | :1, 1 | reading the datasheet |
25
+ | `kt` | no | N·m/A | N·m/A, mN·m/A | reading the datasheet |
26
+ | `coulomb_friction` | no | N·m | N·m, mN·m | reading the datasheet |
27
+ | `viscous_friction` | no | N·m·s/rad | N·m·s/rad, mN·m·s/rad | reading the datasheet |
28
+
29
+ Declared terms (the rest are registry keys, defined in SCHEMA2.md §7.3):
30
+
31
+ - none
32
+
33
+ ## Inputs and state
34
+
35
+ - input `v` (rad/s): The output's angular speed.
36
+
37
+ ## Backends
38
+
39
+ | backend | how | engine | what runs |
40
+ |---|---|---|---|
41
+ | python | reference | — | `model.py` (sha256 `3ed5e7d8d90d…`). The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI. |
42
+ | js | reference | — | `model.js` (sha256 `bb054894e901…`). The same equation as model.py as an ES module (torque(terms, inputs, state, dt) -> {tau, state}); tests/acceptance_v2/test_amendment_2_5.py holds the two to 1e-12. |
43
+ | mujoco | native | mujoco, release named by the fit | The joint's armature, frictionloss and damping; a model stating rotor and gearbox inertia instead gives armature = gear_ratio^2 (rotor_inertia + gearbox_input_inertia). Maps: armature = `output_inertia`, frictionloss = `coulomb_friction`, damping = `viscous_friction`. Without `output_inertia`, armature = `gear_ratio`² × (`rotor_inertia` + `gearbox_input_inertia`), every one of `gear_ratio`, `rotor_inertia`, `gearbox_input_inertia` stated; `gearbox_input_inertia` counts as 0 only on drivetrain direct_drive or motor. |
44
+
45
+ **mujoco settings** a fit may state:
46
+
47
+ - `friction_solref`: 2 numbers. The joint's solreffriction (timeconst, dampratio): how hard frictionloss sticks; MuJoCo's soft default creeps below about 0.4 rad/s on a light hinge.
48
+ - `friction_solimp`: 5 numbers, in (0, inf). The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.
49
+
50
+ ## Validity
51
+
52
+ - A stated model is fitted from nothing, so it has no fitted range.
53
+ - Every value is the maker's, as stated: the model is only as good as the datasheet.
54
+
55
+ ## Use it
56
+
57
+ ```python
58
+ import importlib.util
59
+ spec = importlib.util.spec_from_file_location("datasheet", "model.py")
60
+ model = importlib.util.module_from_spec(spec); spec.loader.exec_module(model)
61
+ terms = {...} # a fit's terms in SI (robotparts.models.si_terms(fit, definition) converts them)
62
+ tau_r, state = model.torque(terms, {"v": 0.0}, None, 0.001)
63
+ ```
64
+
65
+ Defined since robotparts/2.3. It is robotparts/2.3's `datasheet` kind. The contract is SCHEMA2.md §4.3.2; the fit format is `schemas/model.schema.json`.
@@ -0,0 +1,14 @@
1
+ // The datasheet (M1.datasheet): the reference backend as an ES module, the same equation as model.py.
2
+ // torque(terms, inputs, state, dt) -> {tau, state}; terms and inputs in SI; the joint feels -tau.
3
+
4
+ const sign = (x) => (x > 0) - (x < 0);
5
+
6
+ export function torque(terms, inputs, state = {}, dt = null) {
7
+ const v = inputs.v;
8
+ return { tau: (terms.coulomb_friction ?? 0.0) * sign(v) + (terms.viscous_friction ?? 0.0) * v, state: { ...state } };
9
+ }
10
+
11
+ // The level the friction holds at rest: the exact limit at v -> 0+ (see model.py's static_level).
12
+ export function static_level(terms, inputs = {}, state = {}) {
13
+ return terms.coulomb_friction ?? 0.0;
14
+ }