[transfix]

For Joe's review before merge (auto-merge is not enabled).

Why

cvc::ph::se2_vehicle follows LieSPHGP's form, in which every logged input is a port, steering included. So y^T u, with y = G(v)^T v, books power through the steering input. A vehicle's steering does no work on its body: dyn_bike's exact pH form (#831) shows that steering only turns the directions the tires push along.

Measured:

• on the golden fit, steering is 13.4% of |y·u| at its 16 states, and with no drive at all it supplies energy at 10 of them;
• fit to the analytic plant's flights, the LieSPHGP-form model still books 5.6% of |y·u| through steering, against 0 in the plant.

What

se2_setup::modulation_dim (0 by default) makes the last inputs modulations:

D(v, delta) = spd(level + GP_D(v / twist_scale, delta))
G(v, delta) = level + GP_G(v / twist_scale, delta)
dp = ( ad*_v p - [R^T grad V; 0] - D(v, delta) v + G(v, delta) u ) dt,   y = G(v, delta)^T v

u is then the drive alone. With the drive at zero nothing is supplied, whatever delta is, and the steering still steers through D and G.

• Inputs: modulations are scaled like ports; control_scale has one entry per input, ports first. Plant logs (drive, steering) fit with control_dim 1 and modulation_dim 1.
• File format:
  • a modulated model is written as cvc-ph-se2/2, with modulation_dim and D_input/G_input set to "twist+modulation";
  • models without modulations are still written as /1, byte for byte;
  • a /1 reader refuses a /2 file.
• Reverse pass: it carries the modulation entries of the GP input and drops their gradient, since they are data.
• CLI: cvc ph-train --steer-modulates fits the modulated form, --init refuses a model that disagrees with the flag, and provenance records steering.
• Default unchanged: modulation_dim 0 is LieSPHGP's form, and the JAX parity tests hold as before.

Tests

Test	Shows	Measured
PhSe2.TheReferenceFormBooksSteeringAsPower	in LieSPHGP's form, steering alone supplies power	share 0.134; supplies energy at 10 of 16 states
PhSe2.ModulatedSteeringSuppliesNoPower	the balance holds; zero supply at zero drive; steering still changes the motion	balance to 1e-11 at 200 states; a 0.5 steer step changes the twist rate by ≥ 0.18
PhSe2.ModulatedModelRoundTripsExactly	/2 round-trips exactly; unmodulated models stay /1	exact
PhSe2.ModulatedStepIsSecondOrder	Lie-IMEX stays second order	×4.29, 4.08, 4.02
PhSe2Train.ModulatedGradientMatchesFiniteDifferences	the reverse pass is correct	worst 3.9e-7 over 68 entries (gate 2e-5)
PhSe2Train.ModulatedShortFitLowersTheLoss	the modulated form trains	held-out loss 1.417 → 0.070
PhSe2Train.BothFormsFitTheDynamicBicycle	both forms fit diff::dyn_plant's flights; only the reference form books steering power	reference 8.52 → 0.0006 (steering share 0.056, supplies energy at 74 of 250 steps); modulated 7.63 → 0.0092 (share 0)
CvcCliTest.PhTrainFitsSteeringAsAModulation	--steer-modulates end to end	passes

Note on BothFormsFitTheDynamicBicycle:

• It uses Adam at 1e-3.
• At the default 3e-3, the reference fit's gradient norm blew up (1e6 to 1e9) in all three runs I tried, while the modulated fit converged in all four configurations. That is one dataset and one seed, so it is reported here, not claimed.
• At 1e-3 the reference form fits this data better.

Locally (Windows, MSVC 19.44, Release): ph_se2_test 18, ph_se2_train_test 11 and the four PhTrain CLI tests pass. git clang-format (18) reports no changes. The Linux and macOS runs are CI's.

Not in this PR

• The EKF-ELBO stage (M3).
• Proposing the modulation to the LieSPHGP authors: a note is drafted for Joe to send. Public CVC-Lab/LieSPHGP (65db994) has no SE(2) vehicle package; the golden's provenance names 65db994 plus a separate SE(2) package.