also looking at this
feat: model one point-load intake with conserved momentum
#99
45 files
+3133
-169
| @@ -0,0 +1,53 @@ | ||
| 1 | # ADR 0036: One point-load intake for a receiving vehicle | |
| 2 | ||
| 3 | Status: accepted for software simulation. | |
| 4 | ||
| 5 | ## Context | |
| 6 | ||
| 7 | Cargo fleet handover needs a physical parcel to leave one carrier, undergo finite modeled | |
| 8 | station handling and enter another carrier's actual dynamics. A custody-label change or | |
| 9 | an initially loaded second vehicle would bypass that mass transfer. The rigid body already | |
| 10 | supports an attached point load and one zero-ejection separation, but had no empty joint. | |
| 11 | ||
| 12 | ## Decision | |
| 13 | ||
| 14 | Add `createReceivingRigidBody` over the same integrator, with a captured `expectedPointLoad`. | |
| 15 | Its lifecycle is `awaiting -> attached -> separated`. The initial body has base mass/inertia; | |
| 16 | the planned load is not an actual parcel. A successful intake consumes this one opportunity. | |
| 17 | The old `createRigidBody` constructor still starts attached and exposes no intake method or | |
| 18 | awaiting phase. Its default/no-load numerical paths and result projections remain unchanged. | |
| 19 | ||
| 20 | The receiving joint reports its position and velocity. The incoming parcel record contains | |
| 21 | its own id, mass, position and velocity. Match id/mass exactly and require exact coincident | |
| 22 | binary64 position components at invocation. This is an ideal programmatic contact condition, | |
| 23 | not a sensor tolerance or claim of physical positioning precision. Captured records and | |
| 24 | finite tuple elements reject accessors. Valid refusal or malformed input does not mutate | |
| 25 | the body or consume its intake opportunity. | |
| 26 | ||
| 27 | Let base mass be `m`, point mass `p`, body-forward joint vector `r`, and combined mass `M=m+p`. | |
| 28 | The new body-frame CG is `c=p*r/M`. Combined center velocity is `(m*vBody+p*vParcel)/M`. | |
| 29 | About that center, body-frame angular momentum is base `I*omega` plus | |
| 30 | `m*p/M * cross(r, inverseRotate(vParcel-vBody))`. Dividing by the combined principal inertia | |
| 31 | gives the new angular rate. Reconstruct datum velocity from center velocity and `omega cross c`. | |
| 32 | The joint is on the body x axis, so the existing diagonal parallel-axis inertia is sufficient. | |
| 33 | ||
| 34 | The base and incoming point jointly determine conserved linear/angular momentum. Structural | |
| 35 | position, quaternion and actual motor state remain unchanged. Kinetic energy may decrease; | |
| 36 | retain before/after energy and raw dissipation. Reject non-finite candidates or a gain beyond | |
| 37 | `64 * Number.EPSILON * max(1, kineticBeforeJ, kineticAfterJ)` before committing state. Keep the | |
| 38 | raw represented loss, including tolerated tiny negatives. NED potential is `-mass*g*down`. | |
| 39 | The event reports both potential values separately. | |
| 40 | ||
| 41 | ## Consequences | |
| 42 | ||
| 43 | The primitive models an instantaneous inelastic impulse, not contact duration, force peaks, | |
| 44 | parcel spin/deformation, latch actuation or restitution. The retained acceleration is the last | |
| 45 | continuous integration sample, not an invented impact acceleration. A later physics step uses | |
| 46 | the new mass/CG/inertia without resetting the controller, estimator, pose or motor lag. | |
| 47 | ||
| 48 | World/policy code must own and consume the single parcel, admit the physical operation, model | |
| 49 | finite transport to the joint and capture mechanism/vehicle acknowledgement with current | |
| 50 | authority and source epochs. This primitive does not globally prevent a caller from supplying | |
| 51 | the same record to two independent worlds. A joint pose is not a source parcel or proof of custody. | |
| 52 | Station handling and the actual two-vehicle protocol remain unimplemented at this checkpoint. | |
| 53 | No physical output, authenticated identity, battery endurance or fleet completion is claimed. | |