robot-models-lib 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_models/__init__.py +18 -0
  2. robot_models/actuators/__init__.py +1 -0
  3. robot_models/actuators/rungs/README.md +24 -0
  4. robot_models/actuators/rungs/coulomb_viscous/README.md +61 -0
  5. robot_models/actuators/rungs/coulomb_viscous/model.js +14 -0
  6. robot_models/actuators/rungs/coulomb_viscous/model.json +102 -0
  7. robot_models/actuators/rungs/coulomb_viscous/model.py +24 -0
  8. robot_models/actuators/rungs/datasheet/README.md +65 -0
  9. robot_models/actuators/rungs/datasheet/model.js +14 -0
  10. robot_models/actuators/rungs/datasheet/model.json +138 -0
  11. robot_models/actuators/rungs/datasheet/model.py +24 -0
  12. robot_models/actuators/rungs/dcmotor/README.md +63 -0
  13. robot_models/actuators/rungs/dcmotor/model.json +163 -0
  14. robot_models/actuators/rungs/ideal/README.md +60 -0
  15. robot_models/actuators/rungs/ideal/model.js +6 -0
  16. robot_models/actuators/rungs/ideal/model.json +90 -0
  17. robot_models/actuators/rungs/ideal/model.py +13 -0
  18. robot_models/actuators/rungs/load/README.md +65 -0
  19. robot_models/actuators/rungs/load/model.js +15 -0
  20. robot_models/actuators/rungs/load/model.json +117 -0
  21. robot_models/actuators/rungs/load/model.py +25 -0
  22. robot_models/actuators/rungs/lugre/README.md +72 -0
  23. robot_models/actuators/rungs/lugre/model.js +24 -0
  24. robot_models/actuators/rungs/lugre/model.json +164 -0
  25. robot_models/actuators/rungs/lugre/model.py +30 -0
  26. robot_models/actuators/rungs/ripple/README.md +64 -0
  27. robot_models/actuators/rungs/ripple/model.js +17 -0
  28. robot_models/actuators/rungs/ripple/model.json +119 -0
  29. robot_models/actuators/rungs/ripple/model.py +27 -0
  30. robot_models/actuators/rungs/stribeck/README.md +65 -0
  31. robot_models/actuators/rungs/stribeck/model.js +17 -0
  32. robot_models/actuators/rungs/stribeck/model.json +126 -0
  33. robot_models/actuators/rungs/stribeck/model.py +28 -0
  34. robot_models/actuators/servo/README.md +278 -0
  35. robot_models/actuators/servo/__init__.py +7 -0
  36. robot_models/actuators/servo/bldc/README.md +186 -0
  37. robot_models/actuators/servo/bldc/__init__.py +5 -0
  38. robot_models/actuators/servo/bldc/bldc_motor.py +93 -0
  39. robot_models/actuators/servo/bldc/ladder.py +268 -0
  40. robot_models/actuators/servo/foc_controller/README.md +127 -0
  41. robot_models/actuators/servo/foc_controller/__init__.py +3 -0
  42. robot_models/actuators/servo/foc_controller/ladder.py +207 -0
  43. robot_models/actuators/servo/gearbox/README.md +148 -0
  44. robot_models/actuators/servo/gearbox/__init__.py +5 -0
  45. robot_models/actuators/servo/gearbox/gearbox.py +36 -0
  46. robot_models/actuators/servo/gearbox/ladder.py +214 -0
  47. robot_models/actuators/servo/integrated_servo.py +33 -0
  48. robot_models/actuators/servo/ladder.py +593 -0
  49. robot_models/arms/__init__.py +1 -0
  50. robot_models/arms/rigid_body_chain/README.md +151 -0
  51. robot_models/arms/rigid_body_chain/__init__.py +3 -0
  52. robot_models/arms/rigid_body_chain/ladder.py +228 -0
  53. robot_models/conveyors/__init__.py +1 -0
  54. robot_models/conveyors/conveyor/README.md +140 -0
  55. robot_models/conveyors/conveyor/__init__.py +1 -0
  56. robot_models/conveyors/conveyor/ladder.py +203 -0
  57. robot_models/datasheet/__init__.py +56 -0
  58. robot_models/datasheet/datasheet.py +355 -0
  59. robot_models/datasheet/literal.py +144 -0
  60. robot_models/datasheet/source.py +328 -0
  61. robot_models/datasheet/stated.py +135 -0
  62. robot_models/datasheet/units.py +57 -0
  63. robot_models/end_effectors/__init__.py +1 -0
  64. robot_models/end_effectors/gripper/README.md +112 -0
  65. robot_models/end_effectors/gripper/__init__.py +3 -0
  66. robot_models/end_effectors/gripper/ladder.py +150 -0
  67. robot_models/homing/__init__.py +38 -0
  68. robot_models/homing/cad_bundle.py +206 -0
  69. robot_models/homing/contact.py +201 -0
  70. robot_models/homing/fit.py +126 -0
  71. robot_models/homing/metrics.py +237 -0
  72. robot_models/homing/protocols.py +72 -0
  73. robot_models/homing/types.py +256 -0
  74. robot_models/ladder.py +645 -0
  75. robot_models/markers/__init__.py +1 -0
  76. robot_models/markers/aruco_marker/README.md +92 -0
  77. robot_models/markers/aruco_marker/__init__.py +2 -0
  78. robot_models/markers/aruco_marker/ladder.py +142 -0
  79. robot_models/references.py +429 -0
  80. robot_models/sensors/__init__.py +1 -0
  81. robot_models/sensors/camera/README.md +118 -0
  82. robot_models/sensors/camera/__init__.py +3 -0
  83. robot_models/sensors/camera/ladder.py +108 -0
  84. robot_models/sensors/encoder/README.md +103 -0
  85. robot_models/sensors/encoder/__init__.py +5 -0
  86. robot_models/sensors/encoder/ladder.py +133 -0
  87. robot_models/sensors/hyperspectral_camera/README.md +107 -0
  88. robot_models/sensors/hyperspectral_camera/__init__.py +1 -0
  89. robot_models/sensors/hyperspectral_camera/ladder.py +151 -0
  90. robot_models/sensors/rgbd/README.md +113 -0
  91. robot_models/sensors/rgbd/__init__.py +5 -0
  92. robot_models/sensors/rgbd/ladder.py +113 -0
  93. robot_models_lib-0.2.0.dist-info/METADATA +143 -0
  94. robot_models_lib-0.2.0.dist-info/RECORD +96 -0
  95. robot_models_lib-0.2.0.dist-info/WHEEL +4 -0
  96. robot_models_lib-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,593 @@
1
+ """A joint in one housing, a motor, its drive, a reducer or none, and an encoder: its ladder of models (PEP 0004).
2
+
3
+ Spec: PEP 0004 §5.2 and §6.1 (docs/peps/0004-model-ladders-by-type.md).
4
+
5
+ The ladder climbs the way a joint's torque model grows:
6
+
7
+ - M0 and M1 state the part (its inertia and ratio, then every datasheet field) and fit nothing.
8
+ - M2 to M3 are friction, from Coulomb and viscous through Stribeck, load, LuGre, and weakening with a capture level.
9
+ - M4 adds the drivetrain, rotor ripple, backlash and compliance, and composes the drive's own delay loop.
10
+ - M5 is the electrics and heat (MuJoCo's DC motor, and the drive's ceiling) and the wear that grows with use.
11
+ - M6 is a learned residual on the wear rung and M7 a black-box network.
12
+
13
+ Torques, speeds and inertias are at the OUTPUT, after the reducer, as `IntegratedServo`'s datasheet states them; kt,
14
+ kv and rotor_inertia stay on the rotor. Every name below is a canonical one: sim2real's twin names, the registry's
15
+ keys and the exporter's fields are aliases (a unit never appears in a canonical name), and MuJoCo's arrays are packed
16
+ names. What a deployment sets (gains, current limit) is `deployment`, never a rung's parameter.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from robot_models import references
22
+ from robot_models.actuators.servo.integrated_servo import IntegratedServo
23
+ from robot_models.ladder import (
24
+ Alias,
25
+ DeploymentOnly,
26
+ Ladder,
27
+ Packed,
28
+ Parameter,
29
+ Rung,
30
+ Wear,
31
+ datasheet_vocabulary,
32
+ )
33
+
34
+ # WHY a folder constant: robotparts' eight actuator rungs live under one folder, each named by its word (PEP 0004 §8).
35
+ RUNG_CODE = "actuators/rungs"
36
+
37
+ # WHY these usages: the servo card counts a deployment's hours, and backlash opens with the torque it carried over the
38
+ # revolutions it turned (Archard), so its usage is their product (PEP 0004 §5.2, M5.wear).
39
+ DEPLOYMENT_HOURS = "deployment hours"
40
+ HOURS_UNIT = "h"
41
+ TORQUE_REVOLUTIONS = "torque-weighted output revolutions"
42
+ TORQUE_REVOLUTIONS_UNIT = "N·m·rev"
43
+
44
+ # --- the vocabulary: the datasheet's fields, then the names each rung first reads ---------------------------
45
+
46
+ # WHY from the class (PEP 0003 §6): M1.datasheet's names, units and definitions are the typed fields', never a second
47
+ # spelling of them.
48
+ DATASHEET_VOCABULARY = datasheet_vocabulary(IntegratedServo)
49
+
50
+ # M3: state-dependent friction.
51
+ FRICTION_VOCABULARY = (
52
+ Parameter(
53
+ name="breakaway_torque",
54
+ unit="N·m",
55
+ definition=("Static friction at the output: the torque that starts it moving from rest, the top of the "
56
+ "Stribeck curve."),
57
+ ),
58
+ Parameter(
59
+ name="stribeck_velocity",
60
+ unit="rad/s",
61
+ definition="Output speed over which friction falls from breakaway_torque to coulomb_friction.",
62
+ ),
63
+ Parameter(
64
+ name="stribeck_exponent",
65
+ unit="",
66
+ definition="Shape exponent of the Stribeck curve, how sharply friction falls with speed; 2 when absent.",
67
+ ),
68
+ Parameter(
69
+ name="friction_load_coefficient",
70
+ unit="",
71
+ definition="Extra output friction per N·m of load torque the part transmits: Fc + μ·abs(τ_load).",
72
+ ),
73
+ Parameter(
74
+ name="sigma0",
75
+ unit="N·m/rad",
76
+ definition="LuGre bristle stiffness: output torque per radian of bristle deflection.",
77
+ ),
78
+ Parameter(
79
+ name="sigma1",
80
+ unit="N·m·s/rad",
81
+ definition="LuGre bristle damping: output torque per rad/s of bristle deflection rate.",
82
+ ),
83
+ Parameter(
84
+ name="friction_weakening",
85
+ unit="N·m·s/rad",
86
+ definition=("How fast the static friction level falls with output speed, up to "
87
+ "friction_weakening_limit."),
88
+ ),
89
+ Parameter(
90
+ name="friction_weakening_limit",
91
+ unit="rad/s",
92
+ definition="The output speed up to which the friction level keeps weakening.",
93
+ ),
94
+ Parameter(
95
+ name="friction_capture",
96
+ unit="N·m",
97
+ definition=("The friction level that holds a slowed output until it has stayed slow for "
98
+ "friction_capture_dwell."),
99
+ ),
100
+ Parameter(
101
+ name="friction_capture_speed",
102
+ unit="rad/s",
103
+ definition="Below this output speed a joint counts as slow for capture.",
104
+ ),
105
+ Parameter(
106
+ name="friction_capture_dwell",
107
+ unit="s",
108
+ definition="How long a joint must stay slow before the static level returns.",
109
+ ),
110
+ )
111
+
112
+ # M4: the drivetrain.
113
+ DRIVETRAIN_VOCABULARY = (
114
+ Parameter(
115
+ name="harmonics",
116
+ unit="N·m",
117
+ definition=("Rotor-periodic torque harmonics at the output, a list of (rotor_harmonic, amplitude, phase): "
118
+ "cogging and commutation ripple."),
119
+ shape="list",
120
+ ),
121
+ Parameter(
122
+ name="torsional_stiffness",
123
+ unit="N·m/rad",
124
+ definition="Drivetrain stiffness at the output with the rotor held: output torque per radian of twist.",
125
+ ),
126
+ )
127
+
128
+ # M5: heat. kt and resistance_line_to_line are datasheet fields, so they sit in the datasheet vocabulary.
129
+ HEAT_VOCABULARY = (
130
+ Parameter(
131
+ name="thermal_resistance",
132
+ unit="K/W",
133
+ definition=("Winding-to-ambient thermal resistance: winding temperature rise per watt of copper loss."),
134
+ ),
135
+ Parameter(
136
+ name="thermal_time_constant",
137
+ unit="s",
138
+ definition="Time constant of the winding temperature's first-order rise.",
139
+ ),
140
+ )
141
+
142
+ # M5.wear: the rates a deployment's hours and turned load wear the joint at.
143
+ WEAR_VOCABULARY = (
144
+ Parameter(
145
+ name="friction_growth",
146
+ unit="N·m/h",
147
+ definition=("How fast the friction level grows per deployment hour (seals, grease, bearings); on a Stribeck "
148
+ "curve breakaway and Coulomb grow together."),
149
+ ),
150
+ Parameter(
151
+ name="backlash_wear",
152
+ unit="rad/(N·m·rev)",
153
+ definition="How fast backlash opens per torque-weighted output revolution (Archard).",
154
+ ),
155
+ )
156
+
157
+ VOCABULARY = (
158
+ *DATASHEET_VOCABULARY,
159
+ *FRICTION_VOCABULARY,
160
+ *DRIVETRAIN_VOCABULARY,
161
+ *HEAT_VOCABULARY,
162
+ *WEAR_VOCABULARY,
163
+ )
164
+
165
+ # --- the rungs, M0 upward -----------------------------------------------------------------------------------
166
+
167
+ M0_ADDS = ("output_inertia", "gear_ratio")
168
+
169
+ # WHY every typed field and none needed (PEP 0004 decision 3; robotparts' M1 marks all its terms required: false): the
170
+ # datasheet rung states what the source states, so a part with no friction figure still reaches M1.
171
+ DATASHEET_OPTIONAL = tuple(name for name in IntegratedServo.typed_fields() if name not in M0_ADDS)
172
+
173
+ RUNGS = (
174
+ Rung(
175
+ level=0,
176
+ name="ideal",
177
+ title="The ideal actuator: the stated inertia and ratio, no losses",
178
+ base=None,
179
+ adds=M0_ADDS,
180
+ code=f"{RUNG_CODE}/ideal",
181
+ equation="tau_r = 0; armature = output_inertia",
182
+ references=(references.SICILIANO_2009, references.MUJOCO_ARMATURE),
183
+ ),
184
+ Rung(
185
+ level=1,
186
+ name="datasheet",
187
+ title="The datasheet: the stated values, nothing fitted",
188
+ base="M0.ideal",
189
+ optional=DATASHEET_OPTIONAL,
190
+ code=f"{RUNG_CODE}/datasheet",
191
+ equation=("tau_r = coulomb_friction·sign(v) + viscous_friction·v when stated; armature = output_inertia, or "
192
+ "gear_ratio²·(rotor_inertia + gearbox_input_inertia)"),
193
+ references=(references.ARMSTRONG_1994, references.MUJOCO_ARMATURE),
194
+ note="States every IntegratedServo field and needs none beyond M0 (robotparts' M1: required false).",
195
+ ),
196
+ Rung(
197
+ level=2,
198
+ name="coulomb_viscous",
199
+ title="Coulomb and viscous friction, fitted",
200
+ base="M1.datasheet",
201
+ adds=("coulomb_friction", "viscous_friction"),
202
+ code=f"{RUNG_CODE}/coulomb_viscous",
203
+ equation="tau_r = coulomb_friction·sign(v) + viscous_friction·v",
204
+ references=(references.ARMSTRONG_1994, references.OLSSON_1998),
205
+ ),
206
+ Rung(
207
+ level=3,
208
+ name="stribeck",
209
+ title="Stribeck friction: breakaway falling to Coulomb with speed",
210
+ base="M2.coulomb_viscous",
211
+ adds=("breakaway_torque", "stribeck_velocity"),
212
+ optional=("stribeck_exponent",),
213
+ code=f"{RUNG_CODE}/stribeck",
214
+ equation=("tau_r = (coulomb_friction + (breakaway_torque − coulomb_friction)·exp(−(|v|/stribeck_velocity)"
215
+ "^stribeck_exponent))·sign(v) + viscous_friction·v"),
216
+ references=(references.ARMSTRONG_1994, references.OLSSON_1998),
217
+ ),
218
+ Rung(
219
+ level=3,
220
+ name="load",
221
+ title="Friction that grows with the transmitted load",
222
+ base="M2.coulomb_viscous",
223
+ adds=("friction_load_coefficient",),
224
+ code=f"{RUNG_CODE}/load",
225
+ equation=("tau_r = (coulomb_friction + friction_load_coefficient·|tau_load|)·sign(v) "
226
+ "+ viscous_friction·v"),
227
+ references=(references.KIRCANSKI_1997, references.OLSSON_1998),
228
+ ),
229
+ Rung(
230
+ level=3,
231
+ name="lugre",
232
+ title="LuGre dynamic friction",
233
+ base="M3.stribeck",
234
+ adds=("sigma0", "sigma1"),
235
+ code=f"{RUNG_CODE}/lugre",
236
+ # WHY viscous_friction stands for LuGre's sigma2: one quantity, one canonical name; "sigma2" is its alias.
237
+ equation=("dz/dt = v − sigma0·|v|·z/g(v), g(v) the Stribeck level of M3.stribeck; "
238
+ "tau_r = sigma0·z + sigma1·dz/dt + viscous_friction·v (LuGre's sigma2)"),
239
+ references=(references.CANUDAS_1995,),
240
+ ),
241
+ Rung(
242
+ level=3,
243
+ name="weakening_capture",
244
+ title="Stribeck with weakening and a capture level at rest",
245
+ base="M3.stribeck",
246
+ adds=(
247
+ "friction_weakening",
248
+ "friction_weakening_limit",
249
+ "friction_capture",
250
+ "friction_capture_speed",
251
+ "friction_capture_dwell",
252
+ ),
253
+ equation=(
254
+ "level(v) = breakaway_torque − friction_weakening·min(|v|, friction_weakening_limit) − "
255
+ "(breakaway_torque − coulomb_friction)·(1 − exp(−(|v|/stribeck_velocity)²)); "
256
+ "friction_capture holds below friction_capture_speed until friction_capture_dwell has passed"
257
+ ),
258
+ references=(references.ARMSTRONG_1994, references.CANUDAS_1995),
259
+ # WHY no code (PEP 0004 §11, call 7): the type holds the structure and its terms; the twin that fitted it
260
+ # is never published.
261
+ note="sim2real's servo M3, the rack twin's friction: its structure only, the twin is never published.",
262
+ ),
263
+ Rung(
264
+ level=4,
265
+ name="ripple",
266
+ title="Rotor ripple on Coulomb and viscous friction",
267
+ base="M2.coulomb_viscous",
268
+ adds=("harmonics",),
269
+ code=f"{RUNG_CODE}/ripple",
270
+ equation=("tau_r = Σ_k amplitude_k·sin(rotor_harmonic_k·gear_ratio·θ + phase_k) "
271
+ "+ coulomb_friction·sign(v) + viscous_friction·v"),
272
+ references=(references.JAHNS_1996,),
273
+ ),
274
+ Rung(
275
+ level=4,
276
+ name="drivetrain",
277
+ title="The drivetrain: ripple, backlash and compliance on the full friction model",
278
+ base="M3.weakening_capture",
279
+ adds=("harmonics", "backlash", "torsional_stiffness"),
280
+ composes=(("foc_controller", "M1.delay_loop"),),
281
+ equation=("output_inertia·q̈ = tau_drive − tau_r; tau_r = level(v)·sign(v) + viscous_friction·v + "
282
+ "the harmonics; the output across a backlash gap and torsional_stiffness; tau_drive from "
283
+ "foc_controller M1.delay_loop"),
284
+ references=(references.JAHNS_1996, references.NORDIN_2002, references.TUTTLE_1996, references.KRISHNAN_2010),
285
+ note="sim2real's servo M4, the rack twin (today's model), less its heat: that is M5.envelope's.",
286
+ ),
287
+ Rung(
288
+ level=5,
289
+ name="dcmotor",
290
+ title="MuJoCo's DC motor: electrics, heat, cogging and LuGre friction",
291
+ base="M3.lugre",
292
+ adds=("kt", "resistance_line_to_line"),
293
+ optional=("harmonics", "thermal_resistance", "thermal_time_constant"),
294
+ code=f"{RUNG_CODE}/dcmotor",
295
+ equation=("MuJoCo's own: mjDYN_DCMOTOR (electrical dynamics), mjGAIN_DCMOTOR (K or K/R), mjBIAS_DCMOTOR "
296
+ "(back-EMF, cogging, LuGre friction)"),
297
+ references=(references.KRAUSE_2013, references.MUJOCO_DCMOTOR),
298
+ note=("robotparts' rung: its terms are MuJoCo's arrays (the packed names); motorconst and resistance "
299
+ "required, the rest optional, as its model.json marks them."),
300
+ ),
301
+ Rung(
302
+ level=5,
303
+ name="envelope",
304
+ title="The drive's ceiling, the motor's electrics and heat on the drivetrain",
305
+ base="M4.drivetrain",
306
+ adds=("kt", "resistance_line_to_line", "thermal_resistance", "thermal_time_constant"),
307
+ composes=(("foc_controller", "M2.ceiling_heat"),),
308
+ # WHY 1.5·i²R: R is one phase's resistance and i the phase-current amplitude, so the three phases' copper loss
309
+ # is (3/2)·i²·R; the heat is the winding's rise ΔT over ambient, as the motor's M5.dcmotor has it.
310
+ equation=("kt_out = kt·gear_ratio, R = resistance_line_to_line/2 per phase: motoring torque ≤ "
311
+ "kt_out·(voltage_available − |v|·kt_out/1.5)/R; any torque ≤ kt_out·I_max (the deployment's "
312
+ "current cap); winding rise ΔT over ambient: "
313
+ "thermal_time_constant·dΔT/dt = thermal_resistance·1.5·i²R − ΔT "
314
+ "(the three phases' copper loss, i the phase-current amplitude)"),
315
+ references=(references.KRAUSE_2013, references.KRISHNAN_2010, references.MUJOCO_DCMOTOR),
316
+ note=("sim2real's servo M5 (the envelope ladder): the rack twin plus the drive's ceiling and the motor's "
317
+ "electrics; the heat the twin carries at its M4 sits here, robotparts' layer 5."),
318
+ ),
319
+ Rung(
320
+ level=5,
321
+ name="wear",
322
+ title="Wear: friction grows with hours, backlash opens with load",
323
+ base="M5.envelope",
324
+ adds=("friction_growth", "backlash_wear"),
325
+ wears=(
326
+ Wear(parameter="breakaway_torque", usage=DEPLOYMENT_HOURS, usage_unit=HOURS_UNIT, law="linear",
327
+ rate="friction_growth"),
328
+ Wear(parameter="coulomb_friction", usage=DEPLOYMENT_HOURS, usage_unit=HOURS_UNIT, law="linear",
329
+ rate="friction_growth"),
330
+ Wear(parameter="backlash", usage=TORQUE_REVOLUTIONS, usage_unit=TORQUE_REVOLUTIONS_UNIT, law="archard",
331
+ rate="backlash_wear"),
332
+ ),
333
+ equation=("backlash(u) = backlash + backlash_wear·Σ|τ|·Δrev; breakaway_torque and coulomb_friction both "
334
+ "grow by friction_growth·h (the Stribeck drop stays)"),
335
+ references=(references.ARCHARD_1953, references.FLODIN_1997, references.LU_MEEKER_1993),
336
+ ),
337
+ Rung(
338
+ level=6,
339
+ name="residual",
340
+ title="Grey-box residual on M5.wear",
341
+ base="M5.wear",
342
+ kind="residual",
343
+ equation=("M5.wear + an MLP residual torque from 3 samples of position error, velocity and torque "
344
+ "command"),
345
+ references=(references.NGUYEN_TUONG_2010, references.ZENG_2020, references.KOVALEV_2026),
346
+ ),
347
+ Rung(
348
+ level=7,
349
+ name="learned",
350
+ title="Black-box network",
351
+ base=None,
352
+ kind="learned",
353
+ equation="an MLP over 3 samples of position error and velocity → output torque",
354
+ references=(references.HWANGBO_2019, references.HWANGBO_2019_ARXIV, references.ZHU_2025),
355
+ ),
356
+ )
357
+
358
+ # --- other names for the same quantities --------------------------------------------------------------------
359
+
360
+ # WHY a note whenever an alias is not its canonical one for one (PEP 0004 §6): a side, a phase, a level against a
361
+ # difference, a part against a mount. Where `unit` is set the source writes that unit; "" is the canonical SI unit.
362
+ ALIASES = (
363
+ # The registry's old user-part keys and its catalogue columns.
364
+ Alias(
365
+ name="torque_constant",
366
+ canonical="kt",
367
+ note="Old user-part key: a geared part's source may state it at the output (kt × gear_ratio).",
368
+ ),
369
+ Alias(
370
+ name="torque_coefficient",
371
+ canonical="kt",
372
+ note="Catalogue part key: check RMS against peak amperes (kt is per peak ampere).",
373
+ ),
374
+ Alias(
375
+ name="phase_resistance",
376
+ canonical="resistance_line_to_line",
377
+ note=("Old user-part key: a 'phase to phase' value is line to line; a per-phase value is half of it on a "
378
+ "wye winding."),
379
+ ),
380
+ Alias(
381
+ name="phase_inductance",
382
+ canonical="inductance_line_to_line",
383
+ note="Old user-part key: per phase is half of line to line on a wye winding.",
384
+ ),
385
+ Alias(
386
+ name="noload_speed",
387
+ canonical="max_output_speed",
388
+ note="Old user-part key: its unit is the part file's; check it before converting.",
389
+ ),
390
+ Alias(
391
+ name="max_speed",
392
+ canonical="max_output_speed",
393
+ note="Old user-part key: may be a mechanical limit rather than the no-load speed.",
394
+ ),
395
+ Alias(
396
+ name="peak_phase_current",
397
+ canonical="max_phase_current",
398
+ note="The registry's driver key: what the integrated drive can deliver; the motor alone may take more.",
399
+ ),
400
+ Alias(
401
+ name="encoder_counts",
402
+ canonical="encoder_lines",
403
+ note="Counts per turn: 4 × lines on a quadrature encoder.",
404
+ ),
405
+ # Catalogue atlas columns, which carry their unit in the name.
406
+ Alias(name="rated_torque_nm", canonical="rated_torque"),
407
+ Alias(name="peak_torque_nm", canonical="peak_torque"),
408
+ Alias(name="noload_speed_rpm", canonical="max_output_speed", unit="rpm"),
409
+ Alias(name="rated_speed_rpm", canonical="rated_speed", unit="rpm"),
410
+ Alias(name="rated_power_w", canonical="rated_power"),
411
+ Alias(name="voltage_v", canonical="nominal_voltage"),
412
+ Alias(name="mass_kg", canonical="mass"),
413
+ Alias(name="od_mm", canonical="outer_diameter", unit="mm"),
414
+ Alias(name="length_mm", canonical="axial_length", unit="mm"),
415
+ Alias(name="rotor_inertia_kg_m2", canonical="rotor_inertia"),
416
+ Alias(name="peak_current_a", canonical="max_phase_current"),
417
+ Alias(name="rated_current_a", canonical="rated_phase_current"),
418
+ Alias(name="backlash_arcmin", canonical="backlash", unit="arcmin"),
419
+ # Cad2Robot's exporter fields.
420
+ Alias(
421
+ name="phase_resistance_ohm",
422
+ canonical="resistance_line_to_line",
423
+ unit="Ω",
424
+ note="Per phase (sim2real's servo, Cad2Robot's motor): line to line is twice it on a wye winding.",
425
+ ),
426
+ Alias(
427
+ name="phase_inductance_h",
428
+ canonical="inductance_line_to_line",
429
+ unit="H",
430
+ note="Per phase (Cad2Robot's motor): half of line to line on a wye winding.",
431
+ ),
432
+ Alias(
433
+ name="max_effort_nm",
434
+ canonical="peak_torque",
435
+ note="Cad2Robot's servo field: the effort limit it exports.",
436
+ ),
437
+ Alias(
438
+ name="max_velocity_rad_s",
439
+ canonical="max_output_speed",
440
+ note="Cad2Robot's servo field: the velocity limit it exports.",
441
+ ),
442
+ # sim2real's servo card and the rack twin's names.
443
+ Alias(
444
+ name="armature_kg_m2",
445
+ canonical="output_inertia",
446
+ note=("As mounted: the whole axis' inertia at the output, the part's own plus what it drives; "
447
+ "output_inertia is the part alone."),
448
+ ),
449
+ Alias(
450
+ name="frictionloss_nm",
451
+ canonical="coulomb_friction",
452
+ note=("The rack twin's frictionloss is the static level: with no Stribeck term it is coulomb_friction; with "
453
+ "one it is breakaway_torque, and coulomb_friction = frictionloss − friction_stribeck_drop."),
454
+ ),
455
+ Alias(name="damping_nm_s_rad", canonical="viscous_friction"),
456
+ Alias(name="friction_weakening_nm_s_rad", canonical="friction_weakening"),
457
+ Alias(name="friction_weakening_limit_rad_s", canonical="friction_weakening_limit"),
458
+ Alias(
459
+ name="friction_stribeck_drop_nm",
460
+ canonical="breakaway_torque",
461
+ note="A difference, not a level: breakaway_torque − coulomb_friction.",
462
+ ),
463
+ Alias(
464
+ name="friction_stribeck_speed_rad_s",
465
+ canonical="stribeck_velocity",
466
+ note="The twin's Stribeck exponent is fixed at 2.",
467
+ ),
468
+ Alias(name="friction_capture_nm", canonical="friction_capture"),
469
+ Alias(name="friction_capture_speed_rad_s", canonical="friction_capture_speed"),
470
+ Alias(name="friction_capture_dwell_s", canonical="friction_capture_dwell"),
471
+ Alias(name="ripple_harmonics", canonical="harmonics"),
472
+ Alias(
473
+ name="ripple_rotor_per_output",
474
+ canonical="gear_ratio",
475
+ note="The ripple's rotor turns per output turn: the gear ratio as the twin's ripple reads it.",
476
+ ),
477
+ Alias(name="backlash_rad", canonical="backlash"),
478
+ Alias(
479
+ name="gear_stiffness_nm_rad",
480
+ canonical="torsional_stiffness",
481
+ note="Fitted on a mounted unit: it includes the mount's compliance.",
482
+ ),
483
+ Alias(
484
+ name="kt_out_nm_a",
485
+ canonical="kt",
486
+ note="Output side: kt_out = kt × gear_ratio.",
487
+ ),
488
+ Alias(name="backlash_wear_rad_per_nm_rev", canonical="backlash_wear"),
489
+ Alias(
490
+ name="friction_growth_nm_per_h",
491
+ canonical="friction_growth",
492
+ note="It grows the rack twin's frictionloss, the static level: breakaway_torque and coulomb_friction together.",
493
+ ),
494
+ # robotparts' rung terms that name one quantity the vocabulary already has.
495
+ Alias(
496
+ name="sigma2",
497
+ canonical="viscous_friction",
498
+ note="LuGre's own symbol (M3.lugre) for the same viscous coefficient.",
499
+ ),
500
+ Alias(
501
+ name="resistance",
502
+ canonical="resistance_line_to_line",
503
+ unit="Ω",
504
+ note=("M5.dcmotor's winding resistance as MuJoCo takes it, per phase as sim2real reads it "
505
+ "(phase_resistance_ohm): line to line is twice it on a wye winding."),
506
+ ),
507
+ )
508
+
509
+ # --- names that pack several quantities into one array ------------------------------------------------------
510
+
511
+ # WHY packed and not an alias of the first entry (PEP 0004 §4, the fidelity review): an array is never one parameter.
512
+ # MuJoCo's own layouts are not verified here, so each says what it carries and what is MuJoCo's.
513
+ MUJOCO_ARRAY = "M5.dcmotor's MuJoCo array (unit mujoco)"
514
+
515
+ PACKED = (
516
+ Packed(
517
+ name="thermal_r_c",
518
+ holds=("thermal_resistance", "thermal_time_constant"),
519
+ ordered=True,
520
+ note=("The rack twin's (K/W, s) pair. Its thermal model fits a Foster network of one or two poles; with "
521
+ "two, thermal_resistance = ΣR_k and no single time constant holds."),
522
+ ),
523
+ Packed(
524
+ name="motorconst",
525
+ holds=("kt",),
526
+ note=(f"{MUJOCO_ARRAY}, 2 numbers: sim2real reads the torque constant from it at the OUTPUT "
527
+ "(kt × gear_ratio, unless the actuator's gear carries the ratio); the other entry is MuJoCo's, "
528
+ "unverified here."),
529
+ ),
530
+ Packed(
531
+ name="nominal",
532
+ holds=("nominal_voltage",),
533
+ note=f"{MUJOCO_ARRAY}, 3 numbers of nominal ratings; the other entries are MuJoCo's, unverified here.",
534
+ ),
535
+ Packed(
536
+ name="inductance",
537
+ holds=("inductance_line_to_line",),
538
+ note=(f"{MUJOCO_ARRAY}, 2 numbers; per phase or line to line is MuJoCo's convention, unverified here."),
539
+ ),
540
+ Packed(
541
+ name="cogging",
542
+ holds=("harmonics",),
543
+ note=(f"{MUJOCO_ARRAY}, 3 numbers: one cogging harmonic (harmonic, amplitude, phase) in MuJoCo's order, "
544
+ "unverified here."),
545
+ ),
546
+ Packed(
547
+ name="thermal",
548
+ holds=("thermal_resistance", "thermal_time_constant"),
549
+ note=f"{MUJOCO_ARRAY}, 6 numbers; the rest and the order are MuJoCo's, unverified here.",
550
+ ),
551
+ Packed(
552
+ name="lugre",
553
+ holds=("sigma0", "sigma1"),
554
+ note=f"{MUJOCO_ARRAY}, 5 numbers: the M3.lugre terms in MuJoCo's order, unverified here.",
555
+ ),
556
+ )
557
+
558
+ # --- names a deployment sets, which no rung reads as a parameter of the type --------------------------------
559
+
560
+ # WHY not on a rung (PEP 0004 §7): these come from the station or the drive's config. The card's driver-role names
561
+ # (torque_scale, current_loop_hz, command_delay_s, voltage_available_v) are no entry here: they resolve through
562
+ # foc_controller, which M4.drivetrain and M5.envelope compose.
563
+ DEPLOYMENT = (
564
+ DeploymentOnly(
565
+ name="gravity_nm",
566
+ role="assembly",
567
+ why="The station's gravity torque on the joint: the description's.",
568
+ ),
569
+ DeploymentOnly(name="kp_nm_rad", role="config", why="The drive's position gain: the deployment's config."),
570
+ DeploymentOnly(name="kd_nm_s_rad", role="config", why="The drive's velocity gain: the deployment's config."),
571
+ DeploymentOnly(name="max_current_a", role="config", why="The drive's current limit: the deployment's config."),
572
+ DeploymentOnly(
573
+ name="controller",
574
+ role="config",
575
+ why="M5.dcmotor's MuJoCo controller array: the drive's control settings.",
576
+ ),
577
+ DeploymentOnly(
578
+ name="saturation",
579
+ role="config",
580
+ why="M5.dcmotor's MuJoCo saturation array: the drive's ceilings.",
581
+ ),
582
+ )
583
+
584
+ LADDER = Ladder(
585
+ type="integrated_servo",
586
+ title="A joint in one housing: a motor, its drive, a reducer or none, and an encoder.",
587
+ vocabulary=VOCABULARY,
588
+ rungs=RUNGS,
589
+ aliases=ALIASES,
590
+ packed=PACKED,
591
+ deployment=DEPLOYMENT,
592
+ datasheet=IntegratedServo,
593
+ )
@@ -0,0 +1 @@
1
+ """Chain types by type folder (PEP 0004): rigid_body_chain/, a whole arm or any open or closed chain of links."""