[transfix]

Stacked on #749 (feat/plant-log-liesphgp): cvc ph-train reads the run directories cvc plant-log writes.

This ports to C++ the SE(2) port-Hamiltonian vehicle (CVC-Lab/LieSPHGP's method, the variant fitted to Jolt runs of the Humvee and the RoboRacer), together with its rollout-loss trainer. Nothing here needs Python or JAX, at runtime or in CI. The JAX package is now only the parity reference.

What it adds

• inc/cvc/ph/ (new, cvc::ph):
  • mat3.h: 3x3 algebra, the six-level Cholesky form of an SPD matrix and its reverse, the SO(2) log.
  • rff.h: Matern random Fourier features and their GP.
  • rng.h: written-out normal and gamma draws. A seed draws the same features on every compiler; the std:: distributions differ between standard libraries.
  • se2_vehicle.h: H, the drift (coadjoint, potential, D(v), G(v)), the Lie-IMEX step with the damping implicit, and rollouts, in float or double. The model file is JSON (cvc-ph-se2/1).
  • optim.h: cosine decay, global-norm clipping, Adam and Prodigy, written to match optax 0.2.8.
  • se2_train.h: the rollout objective and its hand-written reverse pass, train.py's optimizer, the training loop, and the data.
    • The reverse pass is BPTT through every step: the implicit 3x3 solves, the SPD levels, the random-feature GPs, and grad V's own derivative.
    • The optimizer: clip, cosine-decayed Adam on the GP weights, Prodigy per level.
    • The data: plant-log directories, seed split, observation noise, RMS scales, windows.
    • A window whose rollout diverges is left out of the loss and the gradient, and reported.
• cvc ph-train (cvc-cli, beside cvc plant-log in the Vehicle Physics group):
  • fits a model to plant-log runs and writes the JSON;
  • --init continues a model with its own scales;
  • --dump-dataset writes the noisy flights it trained on.

Tests

ph_se2_test (12), ph_se2_train_test (8), and 3 cvc_cli_test cases. The goldens (ph_se2_golden.json, ph_optim_golden.json) were generated once, outside CI, from the JAX package in float64.

• Forward, against the Humvee fit (64 features, 1,691 parameters):
  • one step at 16 states is within 1.9e-16 relative in double and 1.1e-7 in float;
  • a 25-step rollout is within 3.1e-15;
  • dH/dt = -v.Dv + v.Gu holds exactly;
  • with the GPs off, the drift is the hand-written linear-tire bicycle;
  • the step is second order (x3.99 per halving).
• Gradient: within 8.1e-15 of JAX's autodiff of the same objective on all 1,691 entries, and within 2.2e-6 of central differences.
• Optimizer: 300 steps match optax to 1.6e-16, and Prodigy alone matches it while its d grows from 1e-3 to 1.95.
• Determinism: the objective is bit-identical on any thread count, and a refit on 4 threads reproduces an 8-thread model bit for bit.

Locally on this branch: ph_se2_test 12/12, ph_se2_train_test 8/8, physics_plant_log_test 7/7, nav_dyn_bike_test 9/9, and the cvc_cli_test plant-log, ph-train, help and dispatch cases.

How it was checked against JAX (outside CI)

The C++ rollout fits were held to JAX's own rollout fits: the same data and recipe, 3 seeds a side, scored by one evaluator on the held-out seed (open-loop prediction binned by lateral g, at 0.02 / 0.06 / 0.5 / 1 s).

• Within the seed spread: 98 of 100 cells per vehicle, and 199 of 200 with every seed (6 JAX and 6 C++ for the Humvee, 3 and 5 for the RoboRacer).
• Lockstep: from the same initial model, batches and reparameterization draws, the C++ training loop follows JAX's train step (float64) to 1e-14 in the parameters for 50 steps, and to 1e-11 after 200.
• The Humvee leaned higher at short horizons in the first 3 seeds (1.5x at one tick). It is the random initial draw:
  • with 6 seeds a side it is 1.24x, p = 0.11;
  • JAX in float64 lands beside JAX in float32;
  • started from JAX's initial models, the C++ fits reproduce each JAX seed to about 5%.
• On the 2 s rollout loss both sides train, the C++ fits are as good or better: Humvee 0.87-1.10 against 0.96-1.56 on the held-out monitor.
• Speed: a 5,000-step fit takes 71-87 s on 8 threads, against about 5 min for the JAX rollout fit and 35-47 min for the JAX EKF fit.

Known, for a later milestone

The rollout recipe can blow up on either side: the BPTT gradient explodes through a window whose learned dynamics have gone unstable, while the loss stays finite. It happened in 1 of 4 JAX RoboRacer seeds (float32 overflow at step 962) and 1 of 6 C++ ones (step 1,772). train.py aborts there, and so does this; a guard is open.

Next

• The EKF-ELBO trainer, held to the JAX EKF fits' prediction and calibration numbers.
• dyn_bike's linearization as the D/G prior.
• The GRL-SNAM torch twin.
• The hooks into the nav and GRL-SNAM training flows.