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,151 @@
1
+ > **Generated file.** Written by [`tools/make_type_docs.py`](../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
2
+
3
+ # rigid_body_chain
4
+
5
+ A chain of rigid links and joints, open or closed: a whole arm, a sub-assembly, a wrist, a five-bar.
6
+
7
+ **10 rungs** · 8 parameters · 5 aliases · 0 packed names · 2 deployment-only names · folder `arms/rigid_body_chain/`.
8
+
9
+ In code: `ladders()["rigid_body_chain"]` from [`robot_models.ladder`](../../ladder.py). Every type: [docs/TYPES.md](../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../docs/peps/0004-model-ladders-by-type.md).
10
+ Projects the notes below name, and what they are: [sim2real](../../../../docs/TYPES.md#name-sim2real).
11
+
12
+ ## About
13
+
14
+ From the docstring of [`ladder.py`](ladder.py), less a paragraph on the order that file reads in (this page shows the ladder, then the rungs, then the names):
15
+
16
+ Spec: PEP 0004 §5.10 and §6.9.
17
+
18
+ An arm is not a type of its own: a whole arm is a rigid_body_chain whose joints are their own types (an integrated
19
+ servo, a gearbox, an encoder), so one ladder serves an arm, a sub-assembly, a wrist and a closed five-bar (PEP 0004 §0).
20
+
21
+ The ladder forks after M1.zero_offsets into two branches that both fall back on it:
22
+
23
+ - the kinematic branch (a whole arm): M2.geometric (DH errors), M3.compliance, M3.wear, then the residual M6.residual;
24
+ - the dynamic branch (a sub-assembly, a closed chain): M2.inertial, M2.wear, then the residual M6.inertial_residual.
25
+
26
+ ## The ladder
27
+
28
+ ```mermaid
29
+ flowchart BT
30
+ M0_nominal["M0.nominal<br/>Nominal kinematics"]
31
+ M1_zero_offsets["M1.zero_offsets<br/>Joint zero offsets"]
32
+ M2_geometric["M2.geometric<br/>Geometric (DH) errors"]
33
+ M2_inertial["M2.inertial<br/>Link inertials and loop<br/>closure"]
34
+ M2_wear["M2.wear<br/>Joint zeros that drift<br/>over vibration hours"]
35
+ M3_compliance["M3.compliance<br/>Joint compliance and<br/>link inertials"]
36
+ M3_wear["M3.wear<br/>Joint compliance that<br/>grows with use (Archard)"]
37
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M3.wear"}}
38
+ M6_inertial_residual{{"M6.inertial_residual<br/>Grey-box residual on<br/>M2.wear"}}
39
+ M7_learned(["M7.learned<br/>Black-box network"])
40
+ M0_nominal --> M1_zero_offsets
41
+ M1_zero_offsets --> M2_geometric
42
+ M1_zero_offsets --> M2_inertial
43
+ M2_inertial --> M2_wear
44
+ M2_geometric --> M3_compliance
45
+ M3_compliance --> M3_wear
46
+ M3_wear --> M6_residual
47
+ M2_wear --> M6_inertial_residual
48
+ M6_inertial_residual ~~~ M7_learned
49
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
50
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
51
+ classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
52
+ classDef learned fill:#f1e6fb,stroke:#7a3db3,color:#2a1040
53
+ class M0_nominal,M1_zero_offsets,M2_geometric,M2_inertial,M3_compliance physics
54
+ class M2_wear,M3_wear wear
55
+ class M6_residual,M6_inertial_residual residual
56
+ class M7_learned learned
57
+ ```
58
+
59
+ Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use); amber hexagon: the grey-box residual (M6) on a physics rung; purple rounded box: the learned net (M7), which extends no model.
60
+
61
+ ## Rungs
62
+
63
+ Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
64
+
65
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
66
+ | --- | --- | --- | --- | --- | --- | --- | --- |
67
+ | <a id="rung-m0-nominal"></a>`M0.nominal` | Nominal kinematics | — | `link_geometry` | — | — | `tool = FK(q; link_geometry)` | [SICILIANO_2009](#ref-siciliano_2009), [DH_1955](#ref-dh_1955) |
68
+ | <a id="rung-m1-zero_offsets"></a>`M1.zero_offsets` | Joint zero offsets | [`M0.nominal`](#rung-m0-nominal) | `joint_zero_offsets` | — | — | `tool = FK(q + joint_zero_offsets; link_geometry)` | [HOLLERBACH_WAMPLER_1996](#ref-hollerbach_wampler_1996) |
69
+ | <a id="rung-m2-geometric"></a>`M2.geometric` | Geometric (DH) errors<br>*sim2real's arm M2: the kinematic branch of an open chain.* | [`M1.zero_offsets`](#rung-m1-zero_offsets) | `dh_errors` | — | — | `tool = FK(q + joint_zero_offsets; link_geometry + dh_errors)` | [HAYATI_1983](#ref-hayati_1983), [OKAMURA_1996](#ref-okamura_1996), [HOLLERBACH_2016](#ref-hollerbach_2016) |
70
+ | <a id="rung-m2-inertial"></a>`M2.inertial` | Link inertials and loop closure<br>*sim2real's arm sub-assembly M2: the dynamic branch, which needs no DH errors.* | [`M1.zero_offsets`](#rung-m1-zero_offsets) | `link_inertials`, `closure_tolerance` | — | — | `tool = FK(q + joint_zero_offsets; link_geometry); dynamics from link_inertials with each joint's own type; a closed loop may stay open by closure_tolerance` | [ATKESON_1986](#ref-atkeson_1986), [GAUTIER_1990](#ref-gautier_1990), [SWEVERS_1997](#ref-swevers_1997) |
71
+ | <a id="rung-m2-wear"></a>`M2.wear` | Joint zeros that drift over vibration hours<br>wears `joint_zero_offsets`: see [Wear](#wear) | [`M2.inertial`](#rung-m2-inertial) | `joint_zero_drift` | — | — | `joint_zero_offsets(h) = joint_zero_offsets + joint_zero_drift·√h` | [JUNKER_1969](#ref-junker_1969), [WHITMORE_1995](#ref-whitmore_1995) |
72
+ | <a id="rung-m3-compliance"></a>`M3.compliance` | Joint compliance and link inertials | [`M2.geometric`](#rung-m2-geometric) | `joint_compliance`, `link_inertials` | — | — | `tool = FK(q + joint_zero_offsets + joint_compliance·τ; link_geometry + dh_errors); τ from link_inertials, each joint its own type` | [SPONG_1987](#ref-spong_1987), [ATKESON_1986](#ref-atkeson_1986), [GAUTIER_1990](#ref-gautier_1990), [SWEVERS_1997](#ref-swevers_1997) |
73
+ | <a id="rung-m3-wear"></a>`M3.wear` | Joint compliance that grows with use (Archard)<br>wears `joint_compliance`: see [Wear](#wear) | [`M3.compliance`](#rung-m3-compliance) | `compliance_wear` | — | — | `joint_compliance(u) = joint_compliance + compliance_wear·Σ\|τ\|·Δrev` | [ARCHARD_1953](#ref-archard_1953), [FLODIN_1997](#ref-flodin_1997) |
74
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M3.wear | [`M3.wear`](#rung-m3-wear) | — | — | — | `M3.wear + an MLP residual of joint torques from 3 samples of each joint's error, speed and torque, added to M3.compliance's τ, so it moves the tool through the compliance` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020) |
75
+ | <a id="rung-m6-inertial_residual"></a>`M6.inertial_residual` | Grey-box residual on M2.wear<br>*the residual of the dynamic branch (sim2real's arm sub-assembly M6).* | [`M2.wear`](#rung-m2-wear) | — | — | — | `M2.wear + an MLP residual of joint torques from 3 samples of each joint's error, speed and torque` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020) |
76
+ | <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 3 samples of each joint's error and speed → joint torques` | [HWANGBO_2019](#ref-hwangbo_2019) |
77
+
78
+ ## Wear
79
+
80
+ Which parameter grows with use, with what, by which law, at which rate.
81
+
82
+ | rung | parameter that wears | grows with | law | rate |
83
+ | --- | --- | --- | --- | --- |
84
+ | [`M2.wear`](#rung-m2-wear) | [`joint_zero_offsets`](#param-joint_zero_offsets) | vibration hours (h) | sqrt: `p(u) = p0 + k·√u` | [`joint_zero_drift`](#param-joint_zero_drift) |
85
+ | [`M3.wear`](#rung-m3-wear) | [`joint_compliance`](#param-joint_compliance) | torque-weighted joint revolutions (N·m·rev) | archard: `p(u) = p0 + k·Σ(load·distance): wear grows with the load carried times the distance slid` | [`compliance_wear`](#param-compliance_wear) |
86
+
87
+ ## Vocabulary
88
+
89
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
90
+
91
+ | parameter | SI unit | shape | definition | first read on |
92
+ | --- | --- | --- | --- | --- |
93
+ | <a id="param-link_geometry"></a>`link_geometry` | m, rad | per joint | The chain's nominal joint axes and link frames, as a URDF, a DH table or a CAD export states them. | [`M0.nominal`](#rung-m0-nominal) |
94
+ | <a id="param-joint_zero_offsets"></a>`joint_zero_offsets` | rad | per joint | Each joint's offset between its encoder zero and its kinematic zero. | [`M1.zero_offsets`](#rung-m1-zero_offsets) |
95
+ | <a id="param-dh_errors"></a>`dh_errors` | m, rad | per joint | Errors of the chain's DH parameters from their nominal values. | [`M2.geometric`](#rung-m2-geometric) |
96
+ | <a id="param-link_inertials"></a>`link_inertials` | kg, m, kg·m² | per link | Each link's mass, centre of mass and inertia tensor. | [`M2.inertial`](#rung-m2-inertial) |
97
+ | <a id="param-closure_tolerance"></a>`closure_tolerance` | m | scalar | How far a closed chain's loop may stay open at its closure joint. | [`M2.inertial`](#rung-m2-inertial) |
98
+ | <a id="param-joint_zero_drift"></a>`joint_zero_drift` | rad/√h | scalar | How fast the joint zero offsets drift with the square root of vibration hours. | [`M2.wear`](#rung-m2-wear) |
99
+ | <a id="param-joint_compliance"></a>`joint_compliance` | rad/(N·m) | per joint | Each joint's deflection per N·m it carries. | [`M3.compliance`](#rung-m3-compliance) |
100
+ | <a id="param-compliance_wear"></a>`compliance_wear` | rad/(N·m)/(N·m·rev) | scalar | How fast joint_compliance grows per torque-weighted joint revolution (Archard). | [`M3.wear`](#rung-m3-wear) |
101
+
102
+ ## Aliases
103
+
104
+ Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
105
+
106
+ | alias | canonical | unit | note |
107
+ | --- | --- | --- | --- |
108
+ | `compliance_wear_per_nm_rev` | [`compliance_wear`](#param-compliance_wear) | rad/(N·m)/(N·m·rev) *(canonical)* | |
109
+ | `joint_offset_drift_rad_per_sqrt_h` | [`joint_zero_drift`](#param-joint_zero_drift) | rad/√h *(canonical)* | |
110
+ | `joint_offsets` | [`joint_zero_offsets`](#param-joint_zero_offsets) | rad *(canonical)* | |
111
+ | `joint_zero_drift_rad_per_sqrt_h` | [`joint_zero_drift`](#param-joint_zero_drift) | rad/√h *(canonical)* | |
112
+ | `link_lengths` | [`link_geometry`](#param-link_geometry) | m, rad *(canonical)* | Lengths only: the geometry also carries the joint axes. |
113
+
114
+ ## Packed names
115
+
116
+ Names for one array that carries several of these parameters; never read as one parameter.
117
+
118
+ None.
119
+
120
+ ## Deployment-only names
121
+
122
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
123
+
124
+ - *assembly*: a property of where the part is mounted (the station's gravity, a base frame): the description's.
125
+
126
+ | name | role | where it belongs |
127
+ | --- | --- | --- |
128
+ | `base_frame` | assembly | Where the chain stands in its cell: the description's. |
129
+ | `tool_frame` | assembly | The tool mounted on its flange: the description's. |
130
+
131
+ ## References
132
+
133
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
134
+
135
+ - <a id="ref-archard_1953"></a>**ARCHARD_1953**: Archard (1953). Contact and rubbing of flat surfaces. Journal of Applied Physics. [doi:10.1063/1.1721448](https://doi.org/10.1063/1.1721448). What the rung uses: wear volume grows with the load carried times the distance slid. Cited by [`M3.wear`](#rung-m3-wear).
136
+ - <a id="ref-atkeson_1986"></a>**ATKESON_1986**: Atkeson, An, Hollerbach (1986). Estimation of inertial parameters of manipulator loads and links. The International Journal of Robotics Research. [doi:10.1177/027836498600500306](https://doi.org/10.1177/027836498600500306). What the rung uses: link and load inertials by least squares. Cited by [`M2.inertial`](#rung-m2-inertial), [`M3.compliance`](#rung-m3-compliance).
137
+ - <a id="ref-dh_1955"></a>**DH_1955**: Denavit, Hartenberg (1955). A kinematic notation for lower-pair mechanisms based on matrices. Journal of Applied Mechanics. [doi:10.1115/1.4011045](https://doi.org/10.1115/1.4011045). What the rung uses: the DH parameters of a serial chain. Cited by [`M0.nominal`](#rung-m0-nominal).
138
+ - <a id="ref-flodin_1997"></a>**FLODIN_1997**: Flodin, Andersson (1997). Simulation of mild wear in spur gears. Wear. [doi:10.1016/S0043-1648(96)07467-4](https://doi.org/10.1016/S0043-1648%2896%2907467-4). What the rung uses: Archard's law on gear teeth: the flank wear that opens backlash. Cited by [`M3.wear`](#rung-m3-wear).
139
+ - <a id="ref-gautier_1990"></a>**GAUTIER_1990**: Gautier, Khalil (1990). Direct calculation of minimum set of inertial parameters of serial robots. IEEE Transactions on Robotics and Automation. [doi:10.1109/70.56655](https://doi.org/10.1109/70.56655). What the rung uses: the base inertial parameters an arm can identify. Cited by [`M2.inertial`](#rung-m2-inertial), [`M3.compliance`](#rung-m3-compliance).
140
+ - <a id="ref-hayati_1983"></a>**HAYATI_1983**: Hayati (1983). Robot arm geometric link parameter estimation. The 22nd IEEE Conference on Decision and Control. [doi:10.1109/CDC.1983.269783](https://doi.org/10.1109/CDC.1983.269783). What the rung uses: modified DH for parallel axes, the form kinematic calibration fits. Cited by [`M2.geometric`](#rung-m2-geometric).
141
+ - <a id="ref-hollerbach_2016"></a>**HOLLERBACH_2016**: Hollerbach, Khalil, Gautier (2016). Model identification. In Springer Handbook of Robotics, 2nd ed. Springer. [doi:10.1007/978-3-319-32552-1_6](https://doi.org/10.1007/978-3-319-32552-1_6) (chapter). What the rung uses: kinematic calibration and inertial identification, one chapter. Cited by [`M2.geometric`](#rung-m2-geometric).
142
+ - <a id="ref-hollerbach_wampler_1996"></a>**HOLLERBACH_WAMPLER_1996**: Hollerbach, Wampler (1996). The calibration index and taxonomy for robot kinematic calibration methods. The International Journal of Robotics Research. [doi:10.1177/027836499601500604](https://doi.org/10.1177/027836499601500604). What the rung uses: open- and closed-loop kinematic calibration. Cited by [`M1.zero_offsets`](#rung-m1-zero_offsets).
143
+ - <a id="ref-hwangbo_2019"></a>**HWANGBO_2019**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. Science Robotics. [doi:10.1126/scirobotics.aau5872](https://doi.org/10.1126/scirobotics.aau5872). What the rung uses: ANYmal's actuator net: an MLP over position error and velocity at t, t − 10 ms, t − 20 ms, 3 × 32 softsign (arXiv:1901.08652). Cited by [`M7.learned`](#rung-m7-learned).
144
+ - <a id="ref-junker_1969"></a>**JUNKER_1969**: Junker (1969). New criteria for self-loosening of fasteners under vibration. SAE Technical Paper. [doi:10.4271/690055](https://doi.org/10.4271/690055). What the rung uses: a mount loosening under transverse vibration. Cited by [`M2.wear`](#rung-m2-wear).
145
+ - <a id="ref-nguyen_tuong_2010"></a>**NGUYEN_TUONG_2010**: Nguyen-Tuong, Peters (2010). Using model knowledge for learning inverse dynamics. IEEE International Conference on Robotics and Automation. [doi:10.1109/ROBOT.2010.5509858](https://doi.org/10.1109/ROBOT.2010.5509858). What the rung uses: a physics model plus a learned residual. Cited by [`M6.residual`](#rung-m6-residual), [`M6.inertial_residual`](#rung-m6-inertial_residual).
146
+ - <a id="ref-okamura_1996"></a>**OKAMURA_1996**: Okamura, Park (1996). Kinematic calibration using the product of exponentials formula. Robotica. [doi:10.1017/S0263574700019810](https://doi.org/10.1017/S0263574700019810). What the rung uses: a singularity-free calibration parameterisation. Cited by [`M2.geometric`](#rung-m2-geometric).
147
+ - <a id="ref-siciliano_2009"></a>**SICILIANO_2009**: Siciliano, Sciavicco, Villani, Oriolo (2009). Robotics: Modelling, Planning and Control. Springer. [doi:10.1007/978-1-84628-642-1](https://doi.org/10.1007/978-1-84628-642-1) (book). What the rung uses: rigid-body joint dynamics and reflected inertia. Cited by [`M0.nominal`](#rung-m0-nominal).
148
+ - <a id="ref-spong_1987"></a>**SPONG_1987**: Spong (1987). Modeling and control of elastic joint robots. Journal of Dynamic Systems, Measurement, and Control. [doi:10.1115/1.3143860](https://doi.org/10.1115/1.3143860). What the rung uses: joint compliance as a spring between motor and link. Cited by [`M3.compliance`](#rung-m3-compliance).
149
+ - <a id="ref-swevers_1997"></a>**SWEVERS_1997**: Swevers, Ganseman, Tükel, De Schutter, Van Brussel (1997). Optimal robot excitation and identification. IEEE Transactions on Robotics and Automation. [doi:10.1109/70.631234](https://doi.org/10.1109/70.631234). What the rung uses: periodic excitation trajectories for dynamic identification. Cited by [`M2.inertial`](#rung-m2-inertial), [`M3.compliance`](#rung-m3-compliance).
150
+ - <a id="ref-whitmore_1995"></a>**WHITMORE_1995**: Whitmore (1995). Estimating degradation by a Wiener diffusion process subject to measurement error. Lifetime Data Analysis. [doi:10.1007/BF00985762](https://doi.org/10.1007/BF00985762). What the rung uses: diffusive drift: its expected size grows as the square root of time. Cited by [`M2.wear`](#rung-m2-wear).
151
+ - <a id="ref-zeng_2020"></a>**ZENG_2020**: Zeng, Song, Lee, Rodriguez, Funkhouser (2020). TossingBot: learning to throw arbitrary objects with residual physics. IEEE Transactions on Robotics. [doi:10.1109/TRO.2020.2988642](https://doi.org/10.1109/TRO.2020.2988642). What the rung uses: residual physics: learn what the physics estimate misses. Cited by [`M6.residual`](#rung-m6-residual), [`M6.inertial_residual`](#rung-m6-inertial_residual).
@@ -0,0 +1,3 @@
1
+ """A chain of rigid links and joints, open or closed: a whole arm, a sub-assembly, a wrist, a five-bar. Its ladder of
2
+ models (PEP 0004) runs from the nominal forward kinematics up through zero offsets, DH errors or link inertials and loop
3
+ closure, joint compliance and the wear of both, to a learned residual and a learned net."""
@@ -0,0 +1,228 @@
1
+ """A chain of rigid links and joints, open or closed: a whole arm, a sub-assembly, a wrist, a five-bar. Its ladder of
2
+ models (PEP 0004).
3
+
4
+ Spec: PEP 0004 §5.10 and §6.9.
5
+
6
+ An arm is not a type of its own: a whole arm is a rigid_body_chain whose joints are their own types (an integrated
7
+ servo, a gearbox, an encoder), so one ladder serves an arm, a sub-assembly, a wrist and a closed five-bar (PEP 0004 §0).
8
+
9
+ The ladder forks after M1.zero_offsets into two branches that both fall back on it:
10
+
11
+ - the kinematic branch (a whole arm): M2.geometric (DH errors), M3.compliance, M3.wear, then the residual M6.residual;
12
+ - the dynamic branch (a sub-assembly, a closed chain): M2.inertial, M2.wear, then the residual M6.inertial_residual.
13
+
14
+ Read top to bottom: the vocabulary, grouped by the rung that first reads it, then the rungs from M0 up, then the other
15
+ names a source may use for them.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from robot_models import references as refs
21
+ from robot_models.ladder import Alias, DeploymentOnly, Ladder, Parameter, Rung, Wear
22
+
23
+ # --- the vocabulary, by the rung that first reads each name ----------------------------------------------------------
24
+
25
+ VOCABULARY = (
26
+ # M0.nominal
27
+ Parameter(
28
+ name="link_geometry",
29
+ unit="m, rad",
30
+ definition=("The chain's nominal joint axes and link frames, as a URDF, a DH table or a CAD export states "
31
+ "them."),
32
+ shape="per joint",
33
+ ),
34
+ # M1.zero_offsets
35
+ Parameter(
36
+ name="joint_zero_offsets",
37
+ unit="rad",
38
+ definition="Each joint's offset between its encoder zero and its kinematic zero.",
39
+ shape="per joint",
40
+ ),
41
+ # M2.geometric
42
+ Parameter(
43
+ name="dh_errors",
44
+ unit="m, rad",
45
+ definition="Errors of the chain's DH parameters from their nominal values.",
46
+ shape="per joint",
47
+ ),
48
+ # M2.inertial
49
+ Parameter(
50
+ name="link_inertials",
51
+ unit="kg, m, kg·m²",
52
+ definition="Each link's mass, centre of mass and inertia tensor.",
53
+ shape="per link",
54
+ ),
55
+ Parameter(
56
+ name="closure_tolerance",
57
+ unit="m",
58
+ definition="How far a closed chain's loop may stay open at its closure joint.",
59
+ ),
60
+ # M2.wear
61
+ Parameter(
62
+ name="joint_zero_drift",
63
+ unit="rad/√h",
64
+ definition="How fast the joint zero offsets drift with the square root of vibration hours.",
65
+ ),
66
+ # M3.compliance
67
+ Parameter(
68
+ name="joint_compliance",
69
+ unit="rad/(N·m)",
70
+ definition="Each joint's deflection per N·m it carries.",
71
+ shape="per joint",
72
+ ),
73
+ # M3.wear
74
+ Parameter(
75
+ name="compliance_wear",
76
+ unit="rad/(N·m)/(N·m·rev)",
77
+ definition="How fast joint_compliance grows per torque-weighted joint revolution (Archard).",
78
+ ),
79
+ )
80
+
81
+ # --- the rungs, M0 upward --------------------------------------------------------------------------------------------
82
+
83
+ # WHY the residual reads the same inputs on both branches (sim2real's arm and arm sub-assembly cards): three samples
84
+ # of each joint's error, speed and torque are what both cards feed their residual MLPs.
85
+ RESIDUAL_INPUTS = "3 samples of each joint's error, speed and torque"
86
+
87
+ RUNGS = (
88
+ Rung(
89
+ level=0,
90
+ name="nominal",
91
+ title="Nominal kinematics",
92
+ base=None,
93
+ adds=("link_geometry",),
94
+ equation="tool = FK(q; link_geometry)",
95
+ references=(refs.SICILIANO_2009, refs.DH_1955),
96
+ ),
97
+ Rung(
98
+ level=1,
99
+ name="zero_offsets",
100
+ title="Joint zero offsets",
101
+ base="M0.nominal",
102
+ adds=("joint_zero_offsets",),
103
+ equation="tool = FK(q + joint_zero_offsets; link_geometry)",
104
+ references=(refs.HOLLERBACH_WAMPLER_1996,),
105
+ ),
106
+ # --- the kinematic branch: a whole arm
107
+ Rung(
108
+ level=2,
109
+ name="geometric",
110
+ title="Geometric (DH) errors",
111
+ base="M1.zero_offsets",
112
+ adds=("dh_errors",),
113
+ equation="tool = FK(q + joint_zero_offsets; link_geometry + dh_errors)",
114
+ references=(refs.HAYATI_1983, refs.OKAMURA_1996, refs.HOLLERBACH_2016),
115
+ note="sim2real's arm M2: the kinematic branch of an open chain.",
116
+ ),
117
+ # --- the dynamic branch: a sub-assembly, open or closed
118
+ # WHY its base is M1.zero_offsets and not M2.geometric: a sub-assembly's dynamics need no DH errors (sim2real's arm
119
+ # sub-assembly card goes from M1 straight to its link inertials), so it never falls back on them.
120
+ Rung(
121
+ level=2,
122
+ name="inertial",
123
+ title="Link inertials and loop closure",
124
+ base="M1.zero_offsets",
125
+ adds=("link_inertials", "closure_tolerance"),
126
+ equation=("tool = FK(q + joint_zero_offsets; link_geometry); "
127
+ "dynamics from link_inertials with each joint's own type; "
128
+ "a closed loop may stay open by closure_tolerance"),
129
+ references=(refs.ATKESON_1986, refs.GAUTIER_1990, refs.SWEVERS_1997),
130
+ note="sim2real's arm sub-assembly M2: the dynamic branch, which needs no DH errors.",
131
+ ),
132
+ Rung(
133
+ level=2,
134
+ name="wear",
135
+ title="Joint zeros that drift over vibration hours",
136
+ base="M2.inertial",
137
+ adds=("joint_zero_drift",),
138
+ wears=(
139
+ Wear(parameter="joint_zero_offsets", usage="vibration hours", usage_unit="h", law="sqrt",
140
+ rate="joint_zero_drift"),
141
+ ),
142
+ equation="joint_zero_offsets(h) = joint_zero_offsets + joint_zero_drift·√h",
143
+ references=(refs.JUNKER_1969, refs.WHITMORE_1995),
144
+ ),
145
+ # --- back on the kinematic branch
146
+ Rung(
147
+ level=3,
148
+ name="compliance",
149
+ title="Joint compliance and link inertials",
150
+ base="M2.geometric",
151
+ adds=("joint_compliance", "link_inertials"),
152
+ equation=("tool = FK(q + joint_zero_offsets + joint_compliance·τ; link_geometry + dh_errors); "
153
+ "τ from link_inertials, each joint its own type"),
154
+ references=(refs.SPONG_1987, refs.ATKESON_1986, refs.GAUTIER_1990, refs.SWEVERS_1997),
155
+ ),
156
+ Rung(
157
+ level=3,
158
+ name="wear",
159
+ title="Joint compliance that grows with use (Archard)",
160
+ base="M3.compliance",
161
+ adds=("compliance_wear",),
162
+ wears=(
163
+ Wear(parameter="joint_compliance", usage="torque-weighted joint revolutions", usage_unit="N·m·rev",
164
+ law="archard", rate="compliance_wear"),
165
+ ),
166
+ equation="joint_compliance(u) = joint_compliance + compliance_wear·Σ|τ|·Δrev",
167
+ references=(refs.ARCHARD_1953, refs.FLODIN_1997),
168
+ ),
169
+ # --- the learned rungs: one residual per branch, one net for the type
170
+ Rung(
171
+ level=6,
172
+ name="residual",
173
+ title="Grey-box residual on M3.wear",
174
+ base="M3.wear",
175
+ kind="residual",
176
+ # WHY through the compliance: the kinematic branch's tool pose depends on τ only through M3.compliance, so a
177
+ # torque residual moves the tool only once it is added to that τ.
178
+ equation=(f"M3.wear + an MLP residual of joint torques from {RESIDUAL_INPUTS}, added to M3.compliance's τ, "
179
+ "so it moves the tool through the compliance"),
180
+ references=(refs.NGUYEN_TUONG_2010, refs.ZENG_2020),
181
+ ),
182
+ Rung(
183
+ level=6,
184
+ name="inertial_residual",
185
+ title="Grey-box residual on M2.wear",
186
+ base="M2.wear",
187
+ kind="residual",
188
+ equation=f"M2.wear + an MLP residual of joint torques from {RESIDUAL_INPUTS}",
189
+ references=(refs.NGUYEN_TUONG_2010, refs.ZENG_2020),
190
+ note="the residual of the dynamic branch (sim2real's arm sub-assembly M6).",
191
+ ),
192
+ Rung(
193
+ level=7,
194
+ name="learned",
195
+ title="Black-box network",
196
+ base=None,
197
+ kind="learned",
198
+ equation="an MLP over 3 samples of each joint's error and speed → joint torques",
199
+ references=(refs.HWANGBO_2019,),
200
+ ),
201
+ )
202
+
203
+ # --- the other names a source uses ------------------------------------------------------------------------------------
204
+
205
+ ALIASES = (
206
+ Alias(name="link_lengths", canonical="link_geometry",
207
+ note="Lengths only: the geometry also carries the joint axes."),
208
+ Alias(name="joint_offsets", canonical="joint_zero_offsets"),
209
+ Alias(name="joint_offset_drift_rad_per_sqrt_h", canonical="joint_zero_drift"),
210
+ Alias(name="joint_zero_drift_rad_per_sqrt_h", canonical="joint_zero_drift"),
211
+ Alias(name="compliance_wear_per_nm_rev", canonical="compliance_wear"),
212
+ )
213
+
214
+ # WHY not on a rung (PEP 0004 §7): where the chain stands and what it carries on its flange belong to the cell it is
215
+ # mounted in, so the description gives them; they are no property of the type.
216
+ DEPLOYMENT = (
217
+ DeploymentOnly(name="base_frame", role="assembly", why="Where the chain stands in its cell: the description's."),
218
+ DeploymentOnly(name="tool_frame", role="assembly", why="The tool mounted on its flange: the description's."),
219
+ )
220
+
221
+ LADDER = Ladder(
222
+ type="rigid_body_chain",
223
+ title="A chain of rigid links and joints, open or closed: a whole arm, a sub-assembly, a wrist, a five-bar.",
224
+ vocabulary=VOCABULARY,
225
+ rungs=RUNGS,
226
+ aliases=ALIASES,
227
+ deployment=DEPLOYMENT,
228
+ )
@@ -0,0 +1 @@
1
+ """Conveyor types by type folder (PEP 0004): conveyor/."""
@@ -0,0 +1,140 @@
1
+ > **Generated file.** Written by [`tools/make_type_docs.py`](../../../../tools/make_type_docs.py) from this folder's [`ladder.py`](ladder.py): edit the ladder, not this file, then run `python tools/make_type_docs.py` from the repository root.
2
+
3
+ # conveyor
4
+
5
+ A belt driven through a drum.
6
+
7
+ **7 rungs** · 11 parameters · 9 aliases · 0 packed names · 2 deployment-only names · folder `conveyors/conveyor/`.
8
+
9
+ In code: `ladders()["conveyor"]` from [`robot_models.ladder`](../../ladder.py). Every type: [docs/TYPES.md](../../../../docs/TYPES.md). Spec: [PEP 0004](../../../../docs/peps/0004-model-ladders-by-type.md).
10
+ Projects the notes below name, and what they are: [sim2real](../../../../docs/TYPES.md#name-sim2real).
11
+
12
+ ## About
13
+
14
+ From the docstring of [`ladder.py`](ladder.py):
15
+
16
+ The ladder climbs from an ideal belt (the drum's turns become belt travel, a rigid mass moves under a force) through
17
+ friction on the belt, the belt's stretch between drum and load (where the moving mass splits into the drive side's and
18
+ the load side's), and friction that grows with the belt's distance, to a grey-box residual and a black-box network. Its
19
+ rungs are numbered by the actuator's layers (sim2real's decision, the same M2 and M3 friction rungs, here as forces on
20
+ the belt); there is no M1 because the type has no Datasheet class yet.
21
+
22
+ Spec: PEP 0004 §5.12 and §6.11.
23
+
24
+ ## The ladder
25
+
26
+ ```mermaid
27
+ flowchart BT
28
+ M0_ideal["M0.ideal<br/>An ideal belt:<br/>kinematics and a rigid<br/>mass"]
29
+ M2_coulomb_viscous["M2.coulomb_viscous<br/>Coulomb and viscous<br/>friction on the belt"]
30
+ M3_stribeck["M3.stribeck<br/>Static friction<br/>(Stribeck)"]
31
+ M4_stretch["M4.stretch<br/>Belt stretch: drum and<br/>load as two masses"]
32
+ M4_wear["M4.wear<br/>Friction that grows with<br/>belt distance"]
33
+ M6_residual{{"M6.residual<br/>Grey-box residual on<br/>M4.wear"}}
34
+ M7_learned(["M7.learned<br/>Black-box network"])
35
+ M0_ideal --> M2_coulomb_viscous
36
+ M2_coulomb_viscous --> M3_stribeck
37
+ M3_stribeck --> M4_stretch
38
+ M4_stretch --> M4_wear
39
+ M4_wear --> M6_residual
40
+ M6_residual ~~~ M7_learned
41
+ classDef physics fill:#e8f1fb,stroke:#2f6aa3,color:#10243a
42
+ classDef wear fill:#e8f1fb,stroke:#2f6aa3,color:#10243a,stroke-dasharray:6 3
43
+ classDef residual fill:#fdf0dc,stroke:#b06a00,color:#3a2400
44
+ classDef learned fill:#f1e6fb,stroke:#7a3db3,color:#2a1040
45
+ class M0_ideal,M2_coulomb_viscous,M3_stribeck,M4_stretch physics
46
+ class M4_wear wear
47
+ class M6_residual residual
48
+ class M7_learned learned
49
+ ```
50
+
51
+ Read it bottom up: each solid arrow runs from a rung's base to the rung that extends it, and a rung needs everything below it on its own chain (its fallback). Blue box: a physics rung; dashed blue box: a wear rung (a parameter that grows with use); amber hexagon: the grey-box residual (M6) on a physics rung; purple rounded box: the learned net (M7), which extends no model.
52
+
53
+ ## Rungs
54
+
55
+ Bottom up. *Needs* is what the rung's model cannot run without, new over its base; *reads when stated* is what it uses when a source states it. A rung needs everything its base needs.
56
+
57
+ | rung | title | base | needs (adds) | reads when stated (optional) | code | equation | references |
58
+ | --- | --- | --- | --- | --- | --- | --- | --- |
59
+ | <a id="rung-m0-ideal"></a>`M0.ideal` | An ideal belt: kinematics and a rigid mass<br>*numbered by the actuator's layers (sim2real's decision); no M1: no Datasheet class yet.* | — | `drum_radius`, `gear_ratio`, `moving_mass` | — | — | `x = θ_motor·drum_radius/gear_ratio; (moving_mass + load)·ẍ = F` | [ZHANG_XIA_2011](#ref-zhang_xia_2011) |
60
+ | <a id="rung-m2-coulomb_viscous"></a>`M2.coulomb_viscous` | Coulomb and viscous friction on the belt | [`M0.ideal`](#rung-m0-ideal) | `coulomb_friction`, `viscous_friction` | — | — | `F_f = coulomb_friction·sign(ẋ) + viscous_friction·ẋ` | [ARMSTRONG_1994](#ref-armstrong_1994), [ZHANG_XIA_2011](#ref-zhang_xia_2011) |
61
+ | <a id="rung-m3-stribeck"></a>`M3.stribeck` | Static friction (Stribeck)<br>*the actuator's M3.stribeck as forces on the belt.* | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) | `breakaway_force`, `stribeck_velocity` | — | — | `F_f = (coulomb_friction + (breakaway_force − coulomb_friction)·exp(−(\|ẋ\|/stribeck_velocity)²))·sign(ẋ) + viscous_friction·ẋ` | [ARMSTRONG_1994](#ref-armstrong_1994) |
62
+ | <a id="rung-m4-stretch"></a>`M4.stretch` | Belt stretch: drum and load as two masses<br>*M4 splits moving_mass: drum_mass on the drive side of the stretch, the rest moves with the load.* | [`M3.stribeck`](#rung-m3-stribeck) | `stretch_stiffness`, `stretch_damping`, `drum_mass` | — | — | `drum: drum_mass·ẍ_d = gear_ratio·τ/drum_radius − stretch_stiffness·(x_d − x_l) − stretch_damping·(ẋ_d − ẋ_l); load: (moving_mass − drum_mass + load)·ẍ_l = the same stretch force − F_f` | [SPONG_1987](#ref-spong_1987), [HE_2017](#ref-he_2017) |
63
+ | <a id="rung-m4-wear"></a>`M4.wear` | Friction that grows with belt distance<br>wears `breakaway_force`, `coulomb_friction`: see [Wear](#wear) | [`M4.stretch`](#rung-m4-stretch) | `friction_growth` | — | — | `breakaway_force and coulomb_friction both grow by friction_growth·s (the Stribeck drop stays)` | [LU_MEEKER_1993](#ref-lu_meeker_1993), [ZHANG_XIA_2011](#ref-zhang_xia_2011) |
64
+ | <a id="rung-m6-residual"></a>`M6.residual` | Grey-box residual on M4.wear | [`M4.wear`](#rung-m4-wear) | — | — | — | `M4.wear + an MLP residual drive force from 3 samples of belt speed error, belt speed and motor current` | [NGUYEN_TUONG_2010](#ref-nguyen_tuong_2010), [ZENG_2020](#ref-zeng_2020) |
65
+ | <a id="rung-m7-learned"></a>`M7.learned` | Black-box network | — | — | — | — | `an MLP over 3 samples of position error and belt speed → drive force` | [HWANGBO_2019](#ref-hwangbo_2019), [HWANGBO_2019_ARXIV](#ref-hwangbo_2019_arxiv) |
66
+
67
+ ## Wear
68
+
69
+ Which parameter grows with use, with what, by which law, at which rate.
70
+
71
+ | rung | parameter that wears | grows with | law | rate |
72
+ | --- | --- | --- | --- | --- |
73
+ | [`M4.wear`](#rung-m4-wear) | [`breakaway_force`](#param-breakaway_force) | belt distance (km) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
74
+ | [`M4.wear`](#rung-m4-wear) | [`coulomb_friction`](#param-coulomb_friction) | belt distance (km) | linear: `p(u) = p0 + k·u` | [`friction_growth`](#param-friction_growth) |
75
+
76
+ ## Vocabulary
77
+
78
+ Every parameter the ladder holds, by the rung that first reads it. — as a unit: dimensionless (a ratio or a count).
79
+
80
+ | parameter | SI unit | shape | definition | first read on |
81
+ | --- | --- | --- | --- | --- |
82
+ | <a id="param-drum_radius"></a>`drum_radius` | m | scalar | Radius of the drive drum the belt wraps. | [`M0.ideal`](#rung-m0-ideal) |
83
+ | <a id="param-gear_ratio"></a>`gear_ratio` | — | scalar | Motor turns per drum turn. | [`M0.ideal`](#rung-m0-ideal) |
84
+ | <a id="param-moving_mass"></a>`moving_mass` | kg | scalar | The moving mass referred to the belt: belt, drum and reflected rotor. | [`M0.ideal`](#rung-m0-ideal) |
85
+ | <a id="param-coulomb_friction"></a>`coulomb_friction` | N | scalar | Coulomb friction force on the belt: the constant force that opposes its motion. | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
86
+ | <a id="param-viscous_friction"></a>`viscous_friction` | N·s/m | scalar | Viscous friction coefficient on the belt. | [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous) |
87
+ | <a id="param-breakaway_force"></a>`breakaway_force` | N | scalar | Static friction on the belt: the force that starts it moving from rest. | [`M3.stribeck`](#rung-m3-stribeck) |
88
+ | <a id="param-stribeck_velocity"></a>`stribeck_velocity` | m/s | scalar | Belt speed over which friction falls from breakaway_force to coulomb_friction. | [`M3.stribeck`](#rung-m3-stribeck) |
89
+ | <a id="param-stretch_stiffness"></a>`stretch_stiffness` | N/m | scalar | The belt's stiffness along its length, between drum and load. | [`M4.stretch`](#rung-m4-stretch) |
90
+ | <a id="param-stretch_damping"></a>`stretch_damping` | N·s/m | scalar | Damping of the belt's stretch between drum and load. | [`M4.stretch`](#rung-m4-stretch) |
91
+ | <a id="param-drum_mass"></a>`drum_mass` | kg | scalar | The drive side's mass referred to the belt, read from M4: the drum and the reflected rotor; moving_mass less drum_mass moves with the load. | [`M4.stretch`](#rung-m4-stretch) |
92
+ | <a id="param-friction_growth"></a>`friction_growth` | N/km | scalar | How fast the friction level grows per kilometre of belt travel (idlers and slider bed wearing); breakaway_force and coulomb_friction grow together. | [`M4.wear`](#rung-m4-wear) |
93
+
94
+ ## Aliases
95
+
96
+ Other names a source uses for one of these parameters. A note says how it differs when it is not the same quantity one for one. The unit is the one the source writes its values in; *(canonical)* after it marks an alias stored with no unit of its own, which robot_models reads as the canonical parameter's SI unit, shown here spelled out. A note can still qualify that unit.
97
+
98
+ | alias | canonical | unit | note |
99
+ | --- | --- | --- | --- |
100
+ | `coulomb_growth_n_per_km` | [`friction_growth`](#param-friction_growth) | N/km *(canonical)* | |
101
+ | `coulomb_n` | [`coulomb_friction`](#param-coulomb_friction) | N *(canonical)* | |
102
+ | `drum_radius_m` | [`drum_radius`](#param-drum_radius) | m *(canonical)* | |
103
+ | `drum_radius_mm` | [`drum_radius`](#param-drum_radius) | mm | |
104
+ | `moving_mass_kg` | [`moving_mass`](#param-moving_mass) | kg *(canonical)* | |
105
+ | `static_n` | [`breakaway_force`](#param-breakaway_force) | N *(canonical)* | |
106
+ | `stretch_damping_n_s_m` | [`stretch_damping`](#param-stretch_damping) | N·s/m *(canonical)* | |
107
+ | `stretch_stiffness_n_m` | [`stretch_stiffness`](#param-stretch_stiffness) | N/m *(canonical)* | |
108
+ | `viscous_n_s_m` | [`viscous_friction`](#param-viscous_friction) | N·s/m *(canonical)* | |
109
+
110
+ ## Packed names
111
+
112
+ Names for one array that carries several of these parameters; never read as one parameter.
113
+
114
+ None.
115
+
116
+ ## Deployment-only names
117
+
118
+ Names some model reads that are not the type's own: a deployment sets them, or the mount gives them.
119
+
120
+ - *assembly*: a property of where the part is mounted (the station's gravity, a base frame): the description's.
121
+ - *config*: a setting a deployment writes (a gain, a cap, a rate): read from its config, never fitted to the type.
122
+
123
+ | name | role | where it belongs |
124
+ | --- | --- | --- |
125
+ | `encoder_counts_per_m` | config | Derived from the encoder, the ratio and the drum radius. |
126
+ | `load_mass_kg` | assembly | The parcels on the belt: the deployment's. |
127
+
128
+ ## References
129
+
130
+ The works the rungs cite, by their names in [`robot_models.references`](../../references.py).
131
+
132
+ - <a id="ref-armstrong_1994"></a>**ARMSTRONG_1994**: Armstrong-Hélouvry, Dupont, Canudas de Wit (1994). A survey of models, analysis tools and compensation methods for the control of machines with friction. Automatica. [doi:10.1016/0005-1098(94)90209-7](https://doi.org/10.1016/0005-1098%2894%2990209-7). What the rung uses: Coulomb, viscous and Stribeck friction. Cited by [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous), [`M3.stribeck`](#rung-m3-stribeck).
133
+ - <a id="ref-he_2017"></a>**HE_2017**: He, Pang, Lodewijks (2017). Green operations of belt conveyors by means of speed control. Applied Energy. [doi:10.1016/j.apenergy.2016.12.017](https://doi.org/10.1016/j.apenergy.2016.12.017). What the rung uses: a belt conveyor's dynamics under speed changes. Cited by [`M4.stretch`](#rung-m4-stretch).
134
+ - <a id="ref-hwangbo_2019"></a>**HWANGBO_2019**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. Science Robotics. [doi:10.1126/scirobotics.aau5872](https://doi.org/10.1126/scirobotics.aau5872). What the rung uses: ANYmal's actuator net: an MLP over position error and velocity at t, t − 10 ms, t − 20 ms, 3 × 32 softsign (arXiv:1901.08652). Cited by [`M7.learned`](#rung-m7-learned).
135
+ - <a id="ref-hwangbo_2019_arxiv"></a>**HWANGBO_2019_ARXIV**: Hwangbo, Lee, Dosovitskiy, Bellicoso, Tsounis, Koltun, Hutter (2019). Learning agile and dynamic motor skills for legged robots. arXiv:1901.08652. [https://arxiv.org/abs/1901.08652](https://arxiv.org/abs/1901.08652) (preprint). What the rung uses: the open version. Cited by [`M7.learned`](#rung-m7-learned).
136
+ - <a id="ref-lu_meeker_1993"></a>**LU_MEEKER_1993**: Lu, Meeker (1993). Using degradation measures to estimate a time-to-failure distribution. Technometrics. [doi:10.1080/00401706.1993.10485038](https://doi.org/10.1080/00401706.1993.10485038). What the rung uses: a degradation path in usage, linear the simplest, crossing a failure threshold. Cited by [`M4.wear`](#rung-m4-wear).
137
+ - <a id="ref-nguyen_tuong_2010"></a>**NGUYEN_TUONG_2010**: Nguyen-Tuong, Peters (2010). Using model knowledge for learning inverse dynamics. IEEE International Conference on Robotics and Automation. [doi:10.1109/ROBOT.2010.5509858](https://doi.org/10.1109/ROBOT.2010.5509858). What the rung uses: a physics model plus a learned residual. Cited by [`M6.residual`](#rung-m6-residual).
138
+ - <a id="ref-spong_1987"></a>**SPONG_1987**: Spong (1987). Modeling and control of elastic joint robots. Journal of Dynamic Systems, Measurement, and Control. [doi:10.1115/1.3143860](https://doi.org/10.1115/1.3143860). What the rung uses: joint compliance as a spring between motor and link. Cited by [`M4.stretch`](#rung-m4-stretch).
139
+ - <a id="ref-zeng_2020"></a>**ZENG_2020**: Zeng, Song, Lee, Rodriguez, Funkhouser (2020). TossingBot: learning to throw arbitrary objects with residual physics. IEEE Transactions on Robotics. [doi:10.1109/TRO.2020.2988642](https://doi.org/10.1109/TRO.2020.2988642). What the rung uses: residual physics: learn what the physics estimate misses. Cited by [`M6.residual`](#rung-m6-residual).
140
+ - <a id="ref-zhang_xia_2011"></a>**ZHANG_XIA_2011**: Zhang, Xia (2011). Modeling and energy efficiency optimization of belt conveyors. Applied Energy. [doi:10.1016/j.apenergy.2011.03.015](https://doi.org/10.1016/j.apenergy.2011.03.015). What the rung uses: a belt conveyor's resistances and drive power. Cited by [`M0.ideal`](#rung-m0-ideal), [`M2.coulomb_viscous`](#rung-m2-coulomb_viscous), [`M4.wear`](#rung-m4-wear).
@@ -0,0 +1 @@
1
+ """A belt driven through a drum: the conveyor that carries parcels past an arm, modelled as a ladder (PEP 0004)."""