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,164 @@
1
+ {
2
+ "format": "robotparts-model-definition/1",
3
+ "category": "actuator",
4
+ "word": "lugre",
5
+ "rung": 3,
6
+ "name": "M3.lugre",
7
+ "family": "dynamic friction",
8
+ "title": "LuGre friction",
9
+ "description": "Coulomb + viscous + Stribeck + bristle state",
10
+ "summary": "The LuGre dynamic friction model (Canudas de Wit, Olsson, Astrom and Lischinsky, IEEE TAC 1995): bristles of deflection z give pre-sliding displacement, the Stribeck curve and frictional lag.",
11
+ "equation": "dz/dt = v - sigma0*|v|*z/g(v), g(v) = coulomb_friction + (breakaway_torque - coulomb_friction)*exp(-(|v|/stribeck_velocity)^stribeck_exponent); tau_r = sigma0*z + sigma1*dz/dt + sigma2*v; stribeck_exponent is 2 when absent",
12
+ "since": "robotparts/2.3",
13
+ "v2_3_kind": "lugre",
14
+ "inputs": {
15
+ "v": {
16
+ "definition": "The output's angular speed.",
17
+ "unit": "rad/s"
18
+ },
19
+ "dt": {
20
+ "definition": "The step the simulator advances by (a stateful model integrates its state over it).",
21
+ "unit": "s"
22
+ }
23
+ },
24
+ "state": {
25
+ "z": {
26
+ "definition": "The bristles' mean deflection.",
27
+ "unit": "rad",
28
+ "initial": 0.0
29
+ }
30
+ },
31
+ "output": {
32
+ "name": "tau_r",
33
+ "definition": "The resisting torque at the output: what the motor must add to move the output as the inputs say.",
34
+ "unit": "N·m",
35
+ "sign": "The joint feels -tau_r (a resisting torque opposes motion; ripple pushes and pulls with angle)."
36
+ },
37
+ "terms": {
38
+ "coulomb_friction": {
39
+ "required": true,
40
+ "key": true,
41
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
42
+ },
43
+ "breakaway_torque": {
44
+ "required": true,
45
+ "key": true,
46
+ "measured_by": "slow plateaus below 0.5 rad/s"
47
+ },
48
+ "stribeck_velocity": {
49
+ "required": true,
50
+ "key": true,
51
+ "measured_by": "slow plateaus below 0.5 rad/s"
52
+ },
53
+ "sigma0": {
54
+ "required": true,
55
+ "definition": "LuGre bristle stiffness sigma0: output torque per radian of bristle deflection z.",
56
+ "value": "number",
57
+ "si_unit": "N·m/rad",
58
+ "units": {
59
+ "N·m/rad": 1
60
+ },
61
+ "positive": true,
62
+ "measured_by": "small reversals, recorded fast"
63
+ },
64
+ "sigma1": {
65
+ "required": true,
66
+ "definition": "LuGre bristle (micro-)damping sigma1: output torque per rad/s of bristle deflection rate.",
67
+ "value": "number",
68
+ "si_unit": "N·m·s/rad",
69
+ "units": {
70
+ "N·m·s/rad": 1,
71
+ "mN·m·s/rad": 0.001
72
+ },
73
+ "nonnegative": true,
74
+ "measured_by": "small reversals, recorded fast"
75
+ },
76
+ "sigma2": {
77
+ "required": true,
78
+ "definition": "LuGre viscous coefficient sigma2: output torque per rad/s of output speed (the other kinds' viscous_friction).",
79
+ "value": "number",
80
+ "si_unit": "N·m·s/rad",
81
+ "units": {
82
+ "N·m·s/rad": 1,
83
+ "mN·m·s/rad": 0.001
84
+ },
85
+ "nonnegative": true,
86
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
87
+ },
88
+ "stribeck_exponent": {
89
+ "required": false,
90
+ "definition": "Shape exponent d of the Stribeck curve in g(v); 2 when absent.",
91
+ "value": "number",
92
+ "si_unit": "",
93
+ "units": {
94
+ "": 1
95
+ },
96
+ "positive": true,
97
+ "measured_by": "slow plateaus below 0.5 rad/s",
98
+ "default": 2
99
+ },
100
+ "output_inertia": {
101
+ "required": false,
102
+ "key": true,
103
+ "measured_by": "chirps (or the datasheet)"
104
+ }
105
+ },
106
+ "together": [],
107
+ "exclusive": [],
108
+ "constraints": [],
109
+ "variants": {},
110
+ "backends": {
111
+ "python": {
112
+ "how": "reference",
113
+ "implementation": "model.py",
114
+ "implementation_sha256": "63cb93d20325eb8bfe76e7fa2899928c725eb5de354b45619830c7ef4d59cde0",
115
+ "engine": null,
116
+ "note": "The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI."
117
+ },
118
+ "js": {
119
+ "how": "reference",
120
+ "implementation": "model.js",
121
+ "implementation_sha256": "e8e42ee33d8acfef3fa7be6542c68ee06c165ff1dc2f3dd67787424a0009cb0a",
122
+ "engine": null,
123
+ "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."
124
+ },
125
+ "mujoco": {
126
+ "how": "plugin",
127
+ "implementation": "robotparts.mujoco",
128
+ "engine": "mujoco",
129
+ "maps": {
130
+ "armature": "output_inertia"
131
+ },
132
+ "settings": {
133
+ "friction_solref": {
134
+ "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.",
135
+ "value": "number-list",
136
+ "length": 2
137
+ },
138
+ "friction_solimp": {
139
+ "definition": "The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.",
140
+ "value": "number-list",
141
+ "length": 5,
142
+ "bounds": {
143
+ "min": 0,
144
+ "min_exclusive": true
145
+ }
146
+ }
147
+ },
148
+ "note": "No native part: the plugin integrates z each step with the simulator's dt (semi-implicit, stable for any dt) and applies the whole torque."
149
+ }
150
+ },
151
+ "validity": {
152
+ "dims": {
153
+ "output_speed": {
154
+ "definition": "|v|, the output speed the terms were fitted or checked across.",
155
+ "unit": "rad/s"
156
+ }
157
+ },
158
+ "assumptions": [
159
+ "One bristle state for the whole drivetrain.",
160
+ "Pre-sliding is fitted from small reversals; larger stiction effects outside their amplitude are extrapolated."
161
+ ]
162
+ },
163
+ "readme": "README.md"
164
+ }
@@ -0,0 +1,30 @@
1
+ """LuGre friction (M3.lugre): 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 _g(terms, v):
12
+ fc, fs, vs = terms["coulomb_friction"], terms["breakaway_torque"], terms["stribeck_velocity"]
13
+ d = terms.get("stribeck_exponent", 2.0)
14
+ return fc + (fs - fc) * math.exp(-((abs(v) / vs) ** d))
15
+
16
+
17
+ def torque(terms, inputs, state=None, dt=None):
18
+ v = inputs["v"]
19
+ s0, s1, s2 = terms["sigma0"], terms["sigma1"], terms["sigma2"]
20
+ z = (state or {}).get("z", 0.0)
21
+ g = _g(terms, v)
22
+ if not dt:
23
+ # WHY steady state without a step: dz/dt = 0 gives z = g(v) sign(v) / sigma0, the sliding curve.
24
+ z_next = g * ((v > 0) - (v < 0)) / s0
25
+ zdot = 0.0
26
+ else:
27
+ # WHY semi-implicit: the bristles are stiff (sigma0 ~ 1e2..1e5); an explicit step diverges at a simulator's dt.
28
+ z_next = (z + v * dt) / (1.0 + s0 * abs(v) * dt / g)
29
+ zdot = (z_next - z) / dt
30
+ return s0 * z_next + s1 * zdot + s2 * v, {"z": z_next}
@@ -0,0 +1,64 @@
1
+ # M4.ripple — Rotor ripple map
2
+
3
+ **Coulomb + viscous + rotor-keyed ripple.** Family: grey box. Rung: 4, the drivetrain (ripple, backlash, compliance). Category: actuator.
4
+
5
+ Cogging and commutation ripple: a torque that repeats with the rotor's angle, written as harmonics, plus optional Coulomb and viscous friction. Because the magnets and windings turn with the rotor, a map in rotor angle holds wherever the joint goes.
6
+
7
+ **When to use it.** Use it when position holds and slow moves show a periodic error; one rotor-angle sweep fits it.
8
+
9
+ ## Equation
10
+
11
+ ```
12
+ tau_r = sum_k amplitude_k*sin(rotor_harmonic_k*theta_rotor + phase_k), theta_rotor = gear_ratio*theta_output in rad from the rotor zero the simulator uses (tau_r adds coulomb_friction*sign(v) + viscous_friction*v when stated)
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
+ | `harmonics` | yes | N·m | N·m, mN·m | a rotor-angle sweep (the plateaus, if they cover more than one rotor turn) |
22
+ | `coulomb_friction` | no | N·m | N·m, mN·m | velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn |
23
+ | `viscous_friction` | no | 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 |
24
+ | `output_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | chirps (or the datasheet) |
25
+
26
+ Declared terms (the rest are registry keys, defined in SCHEMA2.md §7.3):
27
+
28
+ - `harmonics`: The ripple harmonics: a list of {rotor_harmonic, amplitude, phase}, rotor_harmonic in cycles per rotor turn (an integer >= 1, each once), amplitude in the term's unit (>= 0, the torque at the output), phase in rad.
29
+
30
+ ## Inputs and state
31
+
32
+ - input `v` (rad/s): The output's angular speed.
33
+ - input `theta_rotor` (rad): The rotor's angle, gear_ratio times the output angle from the rotor zero the simulator uses.
34
+
35
+ ## Backends
36
+
37
+ | backend | how | engine | what runs |
38
+ |---|---|---|---|
39
+ | python | reference | — | `model.py` (sha256 `e30eb5e3ed7c…`). The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI. |
40
+ | js | reference | — | `model.js` (sha256 `31f08577ba8c…`). 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. |
41
+ | mujoco | plugin | mujoco, release named by the fit | `robotparts.mujoco`. Friction natively; the plugin applies the ripple from the rotor angle each step. Maps: armature = `output_inertia`, frictionloss = `coulomb_friction`, damping = `viscous_friction`. |
42
+
43
+ **mujoco settings** a fit may state:
44
+
45
+ - `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.
46
+ - `friction_solimp`: 5 numbers, in (0, inf). The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.
47
+
48
+ ## Validity
49
+
50
+ - A fit states the range of `output_speed` (rad/s) it holds across: |v|, the output speed the terms were fitted or checked across.
51
+ - The ripple is periodic in the rotor angle and the same in both directions (cogging); direction-dependent ripple is not modelled.
52
+ - The harmonics hold wherever the joint goes, because the magnets turn with the rotor.
53
+
54
+ ## Use it
55
+
56
+ ```python
57
+ import importlib.util
58
+ spec = importlib.util.spec_from_file_location("ripple", "model.py")
59
+ model = importlib.util.module_from_spec(spec); spec.loader.exec_module(model)
60
+ terms = {...} # a fit's terms in SI (robotparts.models.si_terms(fit, definition) converts them)
61
+ tau_r, state = model.torque(terms, {"v": 0.0, "theta_rotor": 0.0}, None, 0.001)
62
+ ```
63
+
64
+ Defined since robotparts/2.3. It is robotparts/2.3's `ripple_map` kind. The contract is SCHEMA2.md §4.3.2; the fit format is `schemas/model.schema.json`.
@@ -0,0 +1,17 @@
1
+ // Rotor ripple map (M4.ripple): 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, theta = inputs.theta_rotor;
8
+ let tau = 0.0;
9
+ for (const h of terms.harmonics) tau += h.amplitude * Math.sin(h.rotor_harmonic * theta + h.phase);
10
+ tau += (terms.coulomb_friction ?? 0.0) * sign(v) + (terms.viscous_friction ?? 0.0) * v;
11
+ return { tau, state: { ...state } };
12
+ }
13
+
14
+ // The level the friction holds at rest: the exact limit at v -> 0+ (see model.py's static_level).
15
+ export function static_level(terms, inputs = {}, state = {}) {
16
+ return terms.coulomb_friction ?? 0.0;
17
+ }
@@ -0,0 +1,119 @@
1
+ {
2
+ "format": "robotparts-model-definition/1",
3
+ "category": "actuator",
4
+ "word": "ripple",
5
+ "rung": 4,
6
+ "name": "M4.ripple",
7
+ "family": "grey box",
8
+ "title": "Rotor ripple map",
9
+ "description": "Coulomb + viscous + rotor-keyed ripple",
10
+ "summary": "Cogging and commutation ripple as rotor-periodic torque harmonics at the output (the torque_ripple records in one map), optionally with Coulomb and viscous friction.",
11
+ "equation": "tau_r = sum_k amplitude_k*sin(rotor_harmonic_k*theta_rotor + phase_k), theta_rotor = gear_ratio*theta_output in rad from the rotor zero the simulator uses (tau_r adds coulomb_friction*sign(v) + viscous_friction*v when stated)",
12
+ "since": "robotparts/2.3",
13
+ "v2_3_kind": "ripple_map",
14
+ "inputs": {
15
+ "v": {
16
+ "definition": "The output's angular speed.",
17
+ "unit": "rad/s"
18
+ },
19
+ "theta_rotor": {
20
+ "definition": "The rotor's angle, gear_ratio times the output angle from the rotor zero the simulator uses.",
21
+ "unit": "rad"
22
+ }
23
+ },
24
+ "state": {},
25
+ "output": {
26
+ "name": "tau_r",
27
+ "definition": "The resisting torque at the output: what the motor must add to move the output as the inputs say.",
28
+ "unit": "N·m",
29
+ "sign": "The joint feels -tau_r (a resisting torque opposes motion; ripple pushes and pulls with angle)."
30
+ },
31
+ "terms": {
32
+ "harmonics": {
33
+ "required": true,
34
+ "definition": "The ripple harmonics: a list of {rotor_harmonic, amplitude, phase}, rotor_harmonic in cycles per rotor turn (an integer >= 1, each once), amplitude in the term's unit (>= 0, the torque at the output), phase in rad.",
35
+ "value": "harmonic-list",
36
+ "si_unit": "N·m",
37
+ "units": {
38
+ "N·m": 1,
39
+ "mN·m": 0.001
40
+ },
41
+ "measured_by": "a rotor-angle sweep (the plateaus, if they cover more than one rotor turn)"
42
+ },
43
+ "coulomb_friction": {
44
+ "required": false,
45
+ "key": true,
46
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
47
+ },
48
+ "viscous_friction": {
49
+ "required": false,
50
+ "key": true,
51
+ "measured_by": "velocity plateaus, both directions, 6-8 speeds, each at least one rotor turn"
52
+ },
53
+ "output_inertia": {
54
+ "required": false,
55
+ "key": true,
56
+ "measured_by": "chirps (or the datasheet)"
57
+ }
58
+ },
59
+ "together": [],
60
+ "exclusive": [],
61
+ "constraints": [],
62
+ "variants": {},
63
+ "backends": {
64
+ "python": {
65
+ "how": "reference",
66
+ "implementation": "model.py",
67
+ "implementation_sha256": "e30eb5e3ed7c4ae09b06fc448e31e52c81e5a4cad9bd3e9d0e61b504c6d0395c",
68
+ "engine": null,
69
+ "note": "The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI."
70
+ },
71
+ "js": {
72
+ "how": "reference",
73
+ "implementation": "model.js",
74
+ "implementation_sha256": "31f08577ba8ccdf3c12dd8bbe672a67ac870e94b1ccb6fc348fc64cb0640ddba",
75
+ "engine": null,
76
+ "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."
77
+ },
78
+ "mujoco": {
79
+ "how": "plugin",
80
+ "implementation": "robotparts.mujoco",
81
+ "engine": "mujoco",
82
+ "maps": {
83
+ "armature": "output_inertia",
84
+ "frictionloss": "coulomb_friction",
85
+ "damping": "viscous_friction"
86
+ },
87
+ "settings": {
88
+ "friction_solref": {
89
+ "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.",
90
+ "value": "number-list",
91
+ "length": 2
92
+ },
93
+ "friction_solimp": {
94
+ "definition": "The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.",
95
+ "value": "number-list",
96
+ "length": 5,
97
+ "bounds": {
98
+ "min": 0,
99
+ "min_exclusive": true
100
+ }
101
+ }
102
+ },
103
+ "note": "Friction natively; the plugin applies the ripple from the rotor angle each step."
104
+ }
105
+ },
106
+ "validity": {
107
+ "dims": {
108
+ "output_speed": {
109
+ "definition": "|v|, the output speed the terms were fitted or checked across.",
110
+ "unit": "rad/s"
111
+ }
112
+ },
113
+ "assumptions": [
114
+ "The ripple is periodic in the rotor angle and the same in both directions (cogging); direction-dependent ripple is not modelled.",
115
+ "The harmonics hold wherever the joint goes, because the magnets turn with the rotor."
116
+ ]
117
+ },
118
+ "readme": "README.md"
119
+ }
@@ -0,0 +1,27 @@
1
+ """Rotor ripple map (M4.ripple): 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, theta = inputs["v"], inputs["theta_rotor"]
17
+ tau = sum(h["amplitude"] * math.sin(h["rotor_harmonic"] * theta + h["phase"]) for h in terms["harmonics"])
18
+ tau += terms.get("coulomb_friction", 0.0) * _sign(v) + terms.get("viscous_friction", 0.0) * v
19
+ return tau, dict(state or {})
20
+
21
+
22
+ def static_level(terms, inputs, state=None):
23
+ """The level the friction holds at rest: the exact limit of the resisting torque's friction part as v -> 0+
24
+ (judge r3 #2: a backend that sticks natively, MuJoCo's frictionloss, holds this, never a torque sampled at a small
25
+ speed). The state is read, never advanced."""
26
+ # WHY friction only: the ripple is a position-locked torque, not a friction level
27
+ return float(terms.get("coulomb_friction", 0.0))
@@ -0,0 +1,65 @@
1
+ # M3.stribeck — Stribeck friction
2
+
3
+ **Coulomb + viscous + Stribeck.** Family: static friction. Rung: 3, friction that changes with state. Category: actuator.
4
+
5
+ Friction that is highest just as the output breaks away and falls to the Coulomb level as it speeds up (the Stribeck curve), plus viscous drag. In MuJoCo the breakaway level sticks natively and the plugin gives back the fall with speed each step.
6
+
7
+ **When to use it.** Use it when slow motion and starts from rest matter: the plateaus below 0.5 rad/s show the curve.
8
+
9
+ ## Equation
10
+
11
+ ```
12
+ tau_r = (coulomb_friction + (breakaway_torque - coulomb_friction)*exp(-(|v|/stribeck_velocity)^stribeck_exponent))*sign(v) + viscous_friction*v; stribeck_exponent is 2 when absent
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
+ | `breakaway_torque` | yes | N·m | N·m, mN·m | slow plateaus below 0.5 rad/s |
24
+ | `stribeck_velocity` | yes | rad/s | rad/s, rpm, deg/s | slow plateaus below 0.5 rad/s |
25
+ | `stribeck_exponent` | no | 1 | 1 | slow plateaus below 0.5 rad/s |
26
+ | `output_inertia` | no | kg·m² | kg·m², kg·cm², kg·mm², g·cm², g·mm² | chirps (or the datasheet) |
27
+
28
+ Declared terms (the rest are registry keys, defined in SCHEMA2.md §7.3):
29
+
30
+ - `stribeck_exponent`: Shape exponent d of the Stribeck curve, how sharply friction falls with speed; 2 when absent.
31
+
32
+ ## Inputs and state
33
+
34
+ - input `v` (rad/s): The output's angular speed.
35
+
36
+ ## Backends
37
+
38
+ | backend | how | engine | what runs |
39
+ |---|---|---|---|
40
+ | python | reference | — | `model.py` (sha256 `87f9bc8becd9…`). The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI. |
41
+ | js | reference | — | `model.js` (sha256 `15bdb5ab166d…`). 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. |
42
+ | mujoco | plugin | mujoco, release named by the fit | `robotparts.mujoco`. The static level sticks natively (frictionloss = breakaway_torque); the plugin adds back what friction falls by as the output speeds up, so sliding friction is the Stribeck curve. Maps: armature = `output_inertia`, frictionloss = `breakaway_torque`, damping = `viscous_friction`. |
43
+
44
+ **mujoco settings** a fit may state:
45
+
46
+ - `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.
47
+ - `friction_solimp`: 5 numbers, in (0, inf). The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.
48
+
49
+ ## Validity
50
+
51
+ - A fit states the range of `output_speed` (rad/s) it holds across: |v|, the output speed the terms were fitted or checked across.
52
+ - Friction depends on speed only: not on load, temperature or rest time.
53
+ - The curve holds across the speeds it was fitted on; below the slowest plateau the breakaway level is extrapolated.
54
+
55
+ ## Use it
56
+
57
+ ```python
58
+ import importlib.util
59
+ spec = importlib.util.spec_from_file_location("stribeck", "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 `stribeck` kind. The contract is SCHEMA2.md §4.3.2; the fit format is `schemas/model.schema.json`.
@@ -0,0 +1,17 @@
1
+ // Stribeck friction (M3.stribeck): 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
+ const fc = terms.coulomb_friction, fs = terms.breakaway_torque, vs = terms.stribeck_velocity;
9
+ const d = terms.stribeck_exponent ?? 2.0;
10
+ const level = fc + (fs - fc) * Math.exp(-((Math.abs(v) / vs) ** d));
11
+ return { tau: level * sign(v) + terms.viscous_friction * v, state: { ...state } };
12
+ }
13
+
14
+ // The level the friction holds at rest: the exact limit at v -> 0+ (see model.py's static_level).
15
+ export function static_level(terms, inputs = {}, state = {}) {
16
+ return terms.breakaway_torque;
17
+ }
@@ -0,0 +1,126 @@
1
+ {
2
+ "format": "robotparts-model-definition/1",
3
+ "category": "actuator",
4
+ "word": "stribeck",
5
+ "rung": 3,
6
+ "name": "M3.stribeck",
7
+ "family": "static friction",
8
+ "title": "Stribeck friction",
9
+ "description": "Coulomb + viscous + Stribeck",
10
+ "summary": "Friction that falls from its breakaway value to the Coulomb value as the output speeds up, plus viscous friction (the Stribeck curve).",
11
+ "equation": "tau_r = (coulomb_friction + (breakaway_torque - coulomb_friction)*exp(-(|v|/stribeck_velocity)^stribeck_exponent))*sign(v) + viscous_friction*v; stribeck_exponent is 2 when absent",
12
+ "since": "robotparts/2.3",
13
+ "v2_3_kind": "stribeck",
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
+ "breakaway_torque": {
39
+ "required": true,
40
+ "key": true,
41
+ "measured_by": "slow plateaus below 0.5 rad/s"
42
+ },
43
+ "stribeck_velocity": {
44
+ "required": true,
45
+ "key": true,
46
+ "measured_by": "slow plateaus below 0.5 rad/s"
47
+ },
48
+ "stribeck_exponent": {
49
+ "required": false,
50
+ "definition": "Shape exponent d of the Stribeck curve, how sharply friction falls with speed; 2 when absent.",
51
+ "value": "number",
52
+ "si_unit": "",
53
+ "units": {
54
+ "": 1
55
+ },
56
+ "positive": true,
57
+ "measured_by": "slow plateaus below 0.5 rad/s",
58
+ "default": 2
59
+ },
60
+ "output_inertia": {
61
+ "required": false,
62
+ "key": true,
63
+ "measured_by": "chirps (or the datasheet)"
64
+ }
65
+ },
66
+ "together": [],
67
+ "exclusive": [],
68
+ "constraints": [],
69
+ "variants": {},
70
+ "backends": {
71
+ "python": {
72
+ "how": "reference",
73
+ "implementation": "model.py",
74
+ "implementation_sha256": "87f9bc8becd9dd5db7e1811b349fb96eb31e422435ab4c18ed43db7ab3952a5b",
75
+ "engine": null,
76
+ "note": "The contract's own ruler: stdlib Python, torque(terms, inputs, state, dt) -> (tau_r, state), terms in SI."
77
+ },
78
+ "js": {
79
+ "how": "reference",
80
+ "implementation": "model.js",
81
+ "implementation_sha256": "15bdb5ab166da818de23201e58f524d1cfb5e0604aa64ecad9f2ce51d68f1c34",
82
+ "engine": null,
83
+ "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."
84
+ },
85
+ "mujoco": {
86
+ "how": "plugin",
87
+ "implementation": "robotparts.mujoco",
88
+ "engine": "mujoco",
89
+ "maps": {
90
+ "armature": "output_inertia",
91
+ "frictionloss": "breakaway_torque",
92
+ "damping": "viscous_friction"
93
+ },
94
+ "settings": {
95
+ "friction_solref": {
96
+ "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.",
97
+ "value": "number-list",
98
+ "length": 2
99
+ },
100
+ "friction_solimp": {
101
+ "definition": "The joint's solimpfriction (dmin, dmax, width, midpoint, power), every entry > 0.",
102
+ "value": "number-list",
103
+ "length": 5,
104
+ "bounds": {
105
+ "min": 0,
106
+ "min_exclusive": true
107
+ }
108
+ }
109
+ },
110
+ "note": "The static level sticks natively (frictionloss = breakaway_torque); the plugin adds back what friction falls by as the output speeds up, so sliding friction is the Stribeck curve."
111
+ }
112
+ },
113
+ "validity": {
114
+ "dims": {
115
+ "output_speed": {
116
+ "definition": "|v|, the output speed the terms were fitted or checked across.",
117
+ "unit": "rad/s"
118
+ }
119
+ },
120
+ "assumptions": [
121
+ "Friction depends on speed only: not on load, temperature or rest time.",
122
+ "The curve holds across the speeds it was fitted on; below the slowest plateau the breakaway level is extrapolated."
123
+ ]
124
+ },
125
+ "readme": "README.md"
126
+ }
@@ -0,0 +1,28 @@
1
+ """Stribeck friction (M3.stribeck): 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
+ fc, fs, vs = terms["coulomb_friction"], terms["breakaway_torque"], terms["stribeck_velocity"]
18
+ d = terms.get("stribeck_exponent", 2.0)
19
+ level = fc + (fs - fc) * math.exp(-((abs(v) / vs) ** d))
20
+ return level * _sign(v) + terms["viscous_friction"] * v, dict(state or {})
21
+
22
+
23
+ def static_level(terms, inputs, state=None):
24
+ """The level the friction holds at rest: the exact limit of the resisting torque's friction part as v -> 0+
25
+ (judge r3 #2: a backend that sticks natively, MuJoCo's frictionloss, holds this, never a torque sampled at a small
26
+ speed). The state is read, never advanced."""
27
+ # WHY breakaway exactly: (|v|/vs)^d -> 0 as v -> 0+ for any d > 0, so the curve starts at breakaway_torque
28
+ return float(terms["breakaway_torque"])