[transfix]

The four-wheel plant (inc/cvc/nav/detail/dyn_4w.h, P8d) now has an explicit port-Hamiltonian form and per-step energy books. It follows the single track's form from #831 (dyn_ph_*, dyn_plant_books).

The form

In x = (q, p), with q = (z, φ, θ) and p = M ξ for the twist ξ = (vx, vy, r, ż, φ̇, θ̇), dyn4_plant's vector field is exactly:

H  = ½ ξᵀ M ξ + Σᵢ ½ kᵢ lᵢ² + m g z          lᵢ = Fz0ᵢ/kᵢ + hgᵢ − cᵢ·q
x' = (J(p) − R) ∂H/∂x + G u + f_lever         u = (F_x1 … F_x4),  y = Gᵀ ∂H/∂x
J  = [[0, 0, I], [0, J_h(p_h), 0], [−I, 0, 0]]
R  = blockdiag(0, c_x e_x e_xᵀ + Σᵢ Sᵢ nᵢ nᵢᵀ, Σᵢ c'ᵢ cᵢ cᵢᵀ)

• No speed-floor term (f_ε = 0). Each slip is measured in its wheel's frame and rooted at wᵢ = nᵢ·v = 0. The exact secant Sᵢ = −F_yᵢ / wᵢ (dyn4_ph_secant) therefore carries the whole lateral force. Sᵢ ≥ 0 at any slip and any steering angle, so R is positive semi-definite whether the tires slide or not.
• H holds the corners' springs and gravity on heave. R's vertical block holds the dampers.
• G's columns are the wheels' drive and brake forces at their contact patches, h below the centre of gravity. So yᵢ includes the roll and pitch rates, and yᵀu is all the power those forces deliver. Steering only turns nᵢ and G's columns, so it does no work.
• f_lever is the one term that differs from the single track. It is the moment the tires' lateral forces exert on roll and pitch (h·FY). The plant's slips never see the body's roll and pitch rates, so this coupling runs one way only: it can't go in J or in R. It gets its own line in the books, and it is zero when h = 0.
• Energy rate: dH/dt = −∂Hᵀ R ∂H + yᵀu + ξᵀ f_lever, plus the ground lifting the springs as the wheels roll over it (zero on flat ground).

The grade force (opt-in)

dyn_4w has no gravity along the ground. The terrain only lifts the springs, so a vehicle climbs a hill for free, and the books show that energy as the ground line, coming from outside.

dyn4_params::grade_force (and dyn4_si::grade_force) adds it. It is off by default, so the plant, its goldens and GRL-SNAM's twin are unchanged.

• dyn4_grade applies each spring's horizontal reaction on the slope under its wheel, −Fᵢ ∇h(Pᵢ), as a force and yaw moment on (vx, vy, r).
• That is minus the gradient of H's springs in the pose, so it's conservative. With the pose in the state it belongs to J, and the terrain's energy is in H, as the paper describes.
• The slope comes from central differences of the ground sampler over 1e-3 L, so any sampler works.
• The pH form gains f_grade (dyn4_ph_grade), and the rates and books gain a grade line. Its power cancels the ground line's.

The books

dyn4_plant takes an optional dyn_step_free*, as dyn_plant does. dyn4_plant_books returns each step's books: dH = supplied − dissipated + lever + grade + ground + limiter + residual.

• The ground line is exact: the springs' energy at the step's end, on the new ground minus on the ground the step stood on.

The plant's outputs and VJP are unchanged. On the Windows build, dyn4_golden.json and dyn4_ext_rollout_golden.json regenerate byte-for-byte the same from this branch as from master. GRL-SNAM's test_dyn4_parity.py fixtures stay valid.

Gates (nav_dyn_4w_test, Dyn4PH.*)

• Structure. 500 states on each of: flat ground (μ 0.9 and 0.6) and the golden's split-and-bump ground, sprung and rigid. 267 of the 500 have a tire past its peak.
  • J is skew.
  • R is symmetric, with λ_min ≥ −1e-9‖R‖.
  • ∂H/∂x matches H's central differences to 6e-8.
  • Nothing is supplied when the wheels' forces are zero.
• Vector field. A 1e-5 s dyn4_plant step against dyn4_ph_rhs, forward and reversing, on flat and split-and-bump ground. Worst error: 2.0e-4 of each row's scale.
• Step books. 8 s of a 0.2 Hz weave to near full lock (the steering slews at 0.35 rad/s), with 27% of steps having a tire past its peak (slips reach 0.68 rad; the peak is at 0.345).
  • The per-step residual falls 3.85–3.98× per halving of hdt, on flat ground and over hills.
  • At hdt 0.01, |Σ residual| / flow is 5.0e-4 on flat ground and 1.0e-3 over hills.
  • Braking to a stop charges the speed clamp and the low-speed blend.
  • The ground line is zero on flat ground; the lever line is zero with h = 0.
• The grade force is −∂H/∂pose. Checked against H's central differences in (x, y, ψ): within 3.6e-7 m·g on the golden's bump, and 2.1e-8 m·g over hills. The vector-field gate also passes with it on.
• Grade force on versus off, over hills, swerving past the peak.
  • Off: the ground line is +2868 J at hdt 0.01.
  • On: ground is +3373 J and grade −3372 J.
  • |ground + grade| per step falls 4.0× per halving of hdt (second order).
• Coasting up a 5% ramp for 2 s from 10 m/s, with no drag and the dampers nearly off:
  • Off: the speed holds, and H gains m·g·climb, all of it from the ground line.
  • On: the coast loses 0.986 m/s against g·s·t = 0.981, and H holds to within 0.8% of the climb at hdt 0.0025.
  • The remaining error is the step holding the ground at its start. It is first order: 4× smaller than at hdt 0.01.

Two findings about the plant, left for a separate decision (not changed here):

• The lever term is one-way (above). Making it reciprocal would change the plant and its goldens.
• The dampers are skyhook dampers. They act on the body's own vertical rate, not on its rate relative to the ground. With them, a steady climb also pays c·ż² per corner (about 11 kJ on that ramp); the books show it as dissipation.

Run locally on Windows (MSVC, Release): nav_dyn_4w_test 21/21 (including Dyn4.Golden and Dyn4ExtRollout.Golden) and nav_dyn_bike_test 21/21.