Conventions
2,642 words8 subsections4 tables2 listingsPlan version 1.1
On this page8
One convention per concept, converted at exactly one boundary each. The table of §11.1 is normative. §11.2 to
§11.8 write as formulas the conventions on which a sign, a transpose or a boundary case is easy to get wrong,
each with a check a reader can do by hand. All of them are checked against fs-ga at M0 (PO-MARROW-01).
11.1 The table
| Concept | Convention |
|---|---|
| World frame | Right-handed, z up, metres. Gravity points along −z. A passive change of basis rotates gravity and every extrinsic consistently. |
| Transform names | a_from_b maps coordinates in b to coordinates in a. Composition reads left to right by cancelling inner names. A pose is g = (R, p) and acts as x_a = R·x_b + p. |
| Twist | ξ = (ω, v), angular part first, as fs_ga::Twist::new(angular, linear) (FACT). Body-frame by default: ξ = g⁻¹ġ. Perturbations act on the right. |
| Wrench | (τ, f), torque first, as fs_ga::Wrench::new(torque, force) (FACT). Pairing ⟨w, ξ⟩ = τ·ω + f·v is power in watts. |
| Adjoint and coadjoint | Ad_g moves twists; Ad_g⁻ᵀ moves wrenches; ad*_ξ = ad_ξᵀ, with μ̇ = ad*_ξ μ + w (§11.2). The three frame maps are three types (§11.3). |
| Reflection | Polar vectors map by P and axial vectors by det(P)·P (§11.4). |
| Rotation storage | Unit quaternion; component order and sign rule are FrankenSim's, confirmed at M0 (PO-MARROW-01). The double cover is resolved by a deterministic sign rule. |
| Revolute coordinate | A unit complex number (c, s) plus an integer turn count. No raw angle is stored in state. |
| Link numbering | Topological: the parent index λ(i) is less than i. Depth levels are precomputed. |
| Inertia | Pseudo-inertia about the body-frame origin; a declared wall thickness makes a shell (§11.5). |
| Connection | ξ = −𝔸(s)·ṡ; curvature components and their sign by §11.6. |
| Units | SI. fs-qty types at every public API. GPU buffers are raw f32 with the dimension recorded in the buffer schema. Tolerances carry dimensions: one unitless epsilon across angles, impulses and temperatures is invalid. |
| Time | Integer ticks of a rational base unit. Every periodic process has a rational period and an integer phase accumulator, and need not be a multiple of the physics step (§11.7). |
| Instants | Seven per datum: sample, exposure, timestamp, arrival, decision, command, actuation (§11.8). |
| Windows | Half-open, (a, b]: an event at instant b belongs to the window that ends at b. |
| Comparators | Strict, non-strict and equality are declared per predicate and evaluated exactly (D-18). |
| World address | WorldAddr = (run_seed, world, episode). A random stream is keyed by (WorldAddr, step, stream_id). A fork's child has its own address. Sensor noise is keyed by logical sensor, episode, sample and component. |
| Anchored position | A position is an integer cell index plus an f32 offset in a cell of side 8 m. The offset is centred, in [−4, 4) m, so that a cell shift is exact in either direction (§35). |
| Tier names | referee, batch-cpu, gpu-cuda, gpu-metal. |
| Identities | DesignId, ModelId, SceneId, KernelId, PolicyId, EpisodeId are content hashes (BLAKE3, fs-blake3). An identity names bytes and carries no verdict (D-11). |
| Exact numbers in artifacts | A rational is a reduced pair of integers with a positive denominator. An interval is outward-rounded with its implementation and precision declared. An integer above 2⁵³ travels as a string. |
11.2 Adjoint, coadjoint and the Euler–Poincaré sign
For g = (R, p) = a_from_b, a twist ξ = (ω, v) and a momentum or wrench μ = (π, ℓ):
Ad_g = [[ R, 0 ], [ p̂·R, R ]] (ω, v) ↦ (R·ω, R·v + p × R·ω) twists, b to a
Ad_g⁻ᵀ = [[ R, p̂·R ], [ 0, R ]] (τ, f) ↦ (R·τ + p × R·f, R·f) wrenches, b to a
ad_ξ = [[ ω̂, 0 ], [ v̂, ω̂ ]] ad_ξ η = [ξ, η] = (ω × η_ω, ω × η_v + v × η_ω)
ad*_ξ = ad_ξᵀ ad*_ξ μ = (π × ω + ℓ × v, ℓ × ω)
μ̇ = ad*_ξ μ + w π̇ = π × ω + ℓ × v + τ, ℓ̇ = ℓ × ω + f
The algebra coadjoint is the dual map, defined by ⟨ad*_ξ μ, η⟩ = ⟨μ, [ξ, η]⟩. In coordinates it is the
transpose of ad_ξ, with no minus sign, and with it the Euler–Poincaré equation of a left-invariant system in
body velocity reads μ̇ = ad*_ξ μ. The map ξ ↦ −ad_ξᵀ, which is a representation of the Lie algebra and which some
texts call the coadjoint action, is never written ad* in this project; where it is needed it is written
−ad_ξᵀ. The group coadjoint is the inverse transpose Ad_g⁻ᵀ, as fs_ga::Se3::coadjoint documents (FACT).
Checks. For a free body with the frame origin at the centre of mass, π = I·ω and ℓ = m·v give Euler's equation I·ω̇ = (I·ω) × ω and v̇ = v × ω. The world-frame velocity R·v of a force-free body is then constant, because d(R·v)/dt = R·(ω × v + v̇) = 0; with the opposite sign it would be 2R·(ω × v). The identity ⟨ad_ξᵀ μ, η⟩ = ⟨μ, [ξ, η]⟩ is a polynomial identity in eighteen variables (T-16).
11.3 Three typed maps between frames
| Type | Matrix for g = a_from_b |
Takes | Law |
|---|---|---|---|
TwistMap |
Ad_g | A twist in b to a twist in a | Preserves the bracket; composes as Ad(gh) = Ad(g)·Ad(h) |
WrenchPushforward |
Ad_g⁻ᵀ | A wrench in b to a wrench in a | ⟨Ad_g⁻ᵀ w, Ad_g ξ⟩ = ⟨w, ξ⟩ |
WrenchPullback |
Ad_gᵀ | A wrench in a to a wrench in b | Inverse of the pushforward; a Jacobian transpose is a pullback |
No function accepts one where another is expected. Check: with R = I and p = (1, 0, 0) m, the wrench (0, (0, 0, 1) N) in b pushes forward to torque p × f = (0, −1, 0) N·m and the same force. Moving it with the twist map gives zero torque: the moment arm is lost, and the planar fixture of C-04 fails.
11.4 Reflection parity
For an improper isometry x ↦ P·x + t with PᵀP = I and det P = −1:
| Quantity | Kind | Image |
|---|---|---|
| Position difference, linear velocity, force, linear momentum | polar | P·u |
| Angular velocity, torque, angular momentum, a joint axis read as a rotation axis | axial | det(P)·P·a = −P·a |
| Twist or wrench at the origin | mixed | T(P) = diag(det(P)·P, P) applied to (angular, linear) |
| Rotational inertia about a point | rank two | P·I·Pᵀ |
| Pseudo-inertia | rank two, homogeneous | G·𝖯·Gᵀ with G = [[P, t], [0, 1]] |
| Unit quaternion (w, u) | scalar and axial | (w, det(P)·P·u) |
| Joint coordinate | signed | Negated when the mirrored joint declares its axis as +P·a instead of the axial image −P·a |
T(P) preserves the pairing, because det(P)² = 1, and the bracket (T-16). The action of a symmetry on joint coordinates, actions and observation channels is the signed permutation that follows from this table (C-09). Check: under the sagittal mirror P = diag(1, −1, 1) a pitch axis e_y maps to itself, a roll axis e_x to −e_x and a yaw axis e_z to −e_z. A wheel rolling forward keeps its angular momentum under the mirror; a robot turning left becomes a robot turning right. Treating angular velocity as polar leaves the yaw rate unchanged, which is the mix-up the step-equivariance test of T-10 catches.
11.5 Inertia: pseudo-inertia, shells and mass support
With Σ = ∫ x·xᵀ dm, h = ∫ x dm = m·c and rotational inertia about the origin Ī = tr(Σ)·I − Σ, the pseudo-inertia is 𝖯 = [[Σ, h], [hᵀ, m]], and Σ = ½·tr(Ī)·I − Ī recovers it. The parameters are consistent exactly when 𝖯 ≻ 0. (C-03 writes the same matrix as P; the sans-serif letter is used in this chapter to keep it apart from the reflection P of §11.4.)
- Shell rule. A body with outer region Ω and declared wall thickness t has the mass and inertia of Ω minus its inward offset Ω_t at the same density: 𝖯_shell = 𝖯(Ω, ρ) − 𝖯(Ω_t, ρ), both in the same frame, computed in exact rational arithmetic at model compile time so that the subtraction of two nearly equal matrices loses nothing. A body without a wall thickness is solid. A solid body whose mass exceeds the plausibility bound of its part class is refused (FROB-REF-168) unless the design declares the fill as intended, because a solid default for an enclosure is wrong by an order of magnitude (C-03 gives a case with a factor of 18.8). Check: as t → 0 a spherical shell of radius r tends to I = (2/3)·m·r², against (2/5)·m·r² for the solid ball.
- Mass-support bound. A body whose mass lies in a ball of centre o and radius ρ satisfies ‖c − o‖² + tr(I_C)/(2m) ≤ ρ², with I_C the rotational inertia about the centre of mass. The left side is the mass-weighted mean squared distance from o, since ∫‖x − c‖² dm = tr(Σ_C) = ½·tr(I_C). The bound is applied to a declared mass envelope and never to an unrelated collision proxy.
11.6 Curvature of the connection
With reconstruction ġ = g·ξ and ξ = −𝔸(s)·ṡ, where 𝔸 = 𝔸ᵢ ds^i takes values in the Lie algebra of the group:
(D𝔸)ᵢⱼ = ∂ᵢ𝔸ⱼ − ∂ⱼ𝔸ᵢ − [𝔸ᵢ, 𝔸ⱼ]
g(loop) ≈ exp( −(D𝔸)ᵢⱼ · da ) small loop of area da in the (i, j) plane, traversed from i towards j
The first-order part is Stokes' theorem applied to −∮𝔸·ds. The bracket part is the second-order term of the ordered exponential: for a rectangle with sides a and b the four legs contribute −a·𝔸₁, −b·𝔸₂, +a·𝔸₁, +b·𝔸₂ in that order, and half the sum of the brackets of earlier with later legs is +a·b·[𝔸₁, 𝔸₂]. Large loops keep the ordered product and do not use the area formula. Sign control: for the constant connection 𝔸₁ = e_x, 𝔸₂ = e_y on SO(3), where the bracket is the cross product, the curl vanishes and (D𝔸)₁₂ = −e_z, so a small loop of area da rotates the body by +da about z; the same follows directly from exp(−a·e_x)·exp(−b·e_y)·exp(a·e_x)·exp(b·e_y) ≈ exp(a·b·e_z). A formula with +[𝔸ᵢ, 𝔸ⱼ] predicts −da and is wrong by twice the answer. This fixture is the wrong-sign negative control of C-08 and the statement of T-20.
11.7 Rational clocks and phase accumulators
- Every period in a model is an exact rational number of seconds. The base unit is 1/L seconds, with L the least common multiple of the denominators of all periods; a model whose base unit would be finer than a declared limit is refused at admission.
- Process i has an integer period Nᵢ = Tᵢ·L and an integer phase accumulator. The scheduler advances one integer clock n and process i fires when n ≡ φᵢ (mod Nᵢ). No floating-point time is compared anywhere; n/L is computed for display only.
- When a firing instant falls strictly inside a physics step, the profile decides. The referee and the strict
batch-cpuprofile end a substep at that instant. Throughput tiers apply the channel's declared rule: sample-and-hold, with the age of the held value exposed as a field, or interpolation with a declared error bound. The rule is part of the task's clock contract and ofModelId. - A sensor clock reads t_stamp = (1 + δ)·t + o with rational skew δ and offset o. Jitter, delay and loss are draws from keyed streams, quantized to base units.
- A checkpoint contains every accumulator, scheduled callback, pending packet and action queue. A latency bound is computed per task, and a task whose history buffers cannot cover its longest exposure window is refused.
Check: physics at 400 Hz, an IMU at 100 Hz and a policy at 30 Hz give L = 1,200 and periods of 3, 12 and 40 base units. The policy tick at unit 40 falls one unit after the physics boundary at 39 and two before the one at 42; the pattern repeats every 120 units, 0.1 s. Nothing is rounded to every thirteenth physics step. Over any run the number of firings of process i up to clock n is ⌊(n − φᵢ)/Nᵢ⌋ + 1 exactly, and a replay from a checkpoint taken just after a shutter opens, after a dropped packet, or just before a controller update reproduces the same packet history.
11.8 The seven instants
| # | Instant | Definition |
|---|---|---|
| 1 | sample | The physical quantity begins to be read: emission of a ray, start of an exposure, latch of an encoder. |
| 2 | exposure | The end of the integration window that began at the sample instant. Equal to it for an instantaneous sensor. |
| 3 | timestamp | The time the sensor writes on the packet, on its own clock and by its own convention (start, middle or end of exposure). A label, which may be wrong. |
| 4 | arrival | The packet becomes available to its consumer, after transport delay and jitter. It may be out of order or never happen. |
| 5 | decision | The tick at which an estimator or controller reads its inputs. |
| 6 | command | The command is latched on the bus, after computation delay. |
| 7 | actuation | The actuator's effect begins, after driver delay, and holds over an open interval. |
Ordering. For one packet, sample ≤ exposure ≤ arrival; the timestamp is unconstrained by causality. A decision may use only packets whose arrival is not later than the decision. For one command, decision ≤ command ≤ actuation. When several of these coincide at one instant t, they are processed in a fixed order:
- commit the physical state at t;
- close the exposures that end at t;
- enqueue the samples taken at t;
- deliver the packets whose arrival is at or before t;
- evaluate estimators and controllers;
- latch commands; a zero-delay command takes effect on the open interval that follows t.
Rules that follow. A sensor's reading is a functional of the physical history over its window (a, b], so a camera that straddles an impact samples the segmented pose history and never a linear blend across a velocity reset. A force sensor accumulates continuous wrench over its exposure, adds each impact impulse once, and divides by the exposure. An out-of-order arrival may change a buffered estimator's future outputs; it never changes a past decision or the observation that was delivered at that decision. Truth, measurements, belief and policy observations live in separate namespaces with declared access.
Checks. An impact of 0.2 N·s inside a 10 ms exposure contributes 20 N to that window's average and nothing to its neighbour; an impact at exactly instant b belongs to the window ending at b. In the docking fixture of C-19 the same packet is on time when its arrival precedes the second decision and worthless when it follows the third command. A packet is never visible before its arrival, and private truth behind a disconnected sensor cannot change an action: both are mutation tests of §38.