feat: skidpad score sensitivity experiment

data/sensitivity/README.md

@@ -0,0 +1,67 @@
+# Skidpad score sensitivity study
+
+One-at-a-time (OAT) local sensitivity of the **average timed-lap time** (the FS
+*score*, `profiling.skidpad_score_s` = mean of the two timed laps) to the
+four-wheel vehicle/solver parameters.
+
+Reproduce with:
+
+```bash
+OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 \
+PYTHONPATH=src python src/experiments/skidpad_sensitivity.py \
+    --config configs/skidpad.yaml --delta 0.15 --jobs 4
+```
+
+## Method
+
+- Skidpad track is built once from `configs/skidpad.yaml`; the four-wheel OCP is
+  then re-solved for each perturbation (IPOPT, euler integrator, identical
+  `time_weights`/`terminal_speed`).
+- Each parameter is moved **±15 %** around the baseline, one at a time. Knobs
+  that group several params (`D_rear` = `D_rr` & `D_rl`, `D_front` = `D_fl` &
+  `D_fr`) scale all of them together.
+- **Elasticity** `E = (Δscore/score) / (Δp/p)` is a dimensionless slope: `E=-0.45`
+  means a +1 % parameter increase lowers the average lap by 0.45 %. The ranking
+  uses the absolute lap-time **swing** (seconds) over the ±15 % window.
+- Baseline average timed-lap score: **4.740 s**. All 19 solves returned
+  `Solve_Succeeded`.
+
+## Results (ranked by influence)
+
+| Rank | Parameter | Base | −15 % | +15 % | swing [s] | elasticity |
+|-----:|-----------|-----:|------:|------:|----------:|-----------:|
+| 1 | rear grip `D_rear` | 1.20 | 5.095 | 4.457 | **0.638** | −0.449 |
+| 2 | front grip `D_front` | 1.20 | 4.902 | 4.629 | 0.273 | −0.192 |
+| 3 | mass `m` | 170 | 4.615 | 4.835 | 0.219 | +0.154 |
+| 4 | downforce `C_l` | 5.54 | 4.844 | 4.634 | 0.210 | −0.148 |
+| 5 | margin `boundary_margin` | 0.20 | 4.732 | 4.748 | 0.016 | +0.011 |
+| 6 | drag `C_d` | 1.58 | 4.733 | 4.748 | 0.015 | +0.011 |
+| 7 | `reg_u_l2` | 0.015 | 4.734 | 4.748 | 0.014 | +0.010 |
+| 8 | CG height `h` | 0.246 | 4.737 | 4.744 | 0.007 | +0.005 |
+| 9 | yaw inertia `Iz` | 250 | 4.738 | 4.742 | 0.004 | +0.003 |
+
+See `skidpad_sensitivity.png` (tornado plot), `skidpad_sensitivity.csv` (every
+raw solve), and `skidpad_sensitivity_summary.json` (machine-readable summary).
+
+## Takeaways
+
+- **Tyre peak grip dominates.** Rear grip `D_rear` is the single biggest lever
+  (~3× the next parameter); front grip is second. Skidpad is a steady-state,
+  grip-limited corner, so peak `D` maps almost directly into corner speed, and
+  the rear-biased static load (`lf > lr`) makes the rear tyres the limiting
+  pair. This is also the least free parameter physically — it reflects the tyre
+  model, not something you tune.
+- Of the *tunable / design* knobs, **mass** and **aero downforce `C_l`** are the
+  meaningful ones (~0.21–0.22 s over ±15 %, elasticity ≈ 0.15). They trade off
+  in opposite directions, as expected. Note `C_l` only enters through downforce,
+  so its grip benefit scales with v² and is modest at skidpad speeds (~12 m/s).
+- **Solver / corridor knobs are negligible**: `reg_u_l2`, `boundary_margin`,
+  `C_d`, `h`, and `Iz` each move the score by <0.02 s (elasticity ≤ 0.01). The
+  L2 regularisation is well below the level where it distorts the lap, and yaw
+  inertia barely matters in this near-steady manoeuvre — both reassuring for the
+  current setup.
+
+> Caveat: these are *local* ±15 % OAT sensitivities about one operating point.
+> Interactions between parameters and larger excursions (e.g. big margin or grip
+> changes) can be non-linear; widen `--delta` or run a coupled sweep to probe
+> those.

data/sensitivity/skidpad_sensitivity.csv

@@ -0,0 +1,20 @@
+knob,tag,multiplier,param_value,score_s,timed_time_s,full_time_s,status,solve_time_s,iters
+baseline,baseline,1.0,nan,4.740072009101534,9.480144018203069,24.408978411789178,Solve_Succeeded,103.158144795,36
+m,m_x0p85,0.85,144.5,4.615329978661124,9.230659957322247,23.733437263235718,Solve_Succeeded,103.07811617699997,37
+m,m_x1p15,1.15,195.49999999999997,4.834693092402854,9.669386184805708,24.93276289268389,Solve_Succeeded,86.61417656799995,35
+Iz,Iz_x0p85,0.85,212.5,4.737568582217398,9.475137164434797,24.37953623746616,Solve_Succeeded,91.54032464400007,38
+Iz,Iz_x1p15,1.15,287.5,4.742002966935889,9.484005933871778,24.433947555840923,Solve_Succeeded,90.80592223899998,34
+reg_u_l2,reg_u_l2_x0p85,0.85,0.01275,4.733660775527216,9.467321551054432,24.316874679803124,Solve_Succeeded,90.239864238,38
+reg_u_l2,reg_u_l2_x1p15,1.15,0.017249999999999998,4.747747794848977,9.495495589697954,24.495904367233393,Solve_Succeeded,77.98857451999993,35
+D_rear,D_rear_x0p85,0.85,1.02,5.094813913837953,10.189627827675906,26.049556440109733,Solve_Succeeded,83.41913291800006,40
+D_rear,D_rear_x1p15,1.15,1.38,4.456787934473439,8.913575868946879,23.101462714559105,Solve_Succeeded,91.38867170399999,35
+boundary_margin,boundary_margin_x0p85,0.85,0.17,4.732085539416261,9.464171078832521,24.387458259898395,Solve_Succeeded,77.02125245299999,36
+boundary_margin,boundary_margin_x1p15,1.15,0.22999999999999998,4.7480569541913695,9.496113908382739,24.434465704566502,Solve_Succeeded,93.01054706900004,37
+C_l,C_l_x0p85,0.85,4.709,4.8439512656554555,9.687902531310911,24.881045259787204,Solve_Succeeded,77.36289373099999,36
+C_l,C_l_x1p15,1.15,6.3709999999999996,4.633963737301138,9.267927474602276,23.921053788576025,Solve_Succeeded,75.75866207400009,35
+D_front,D_front_x0p85,0.85,1.02,4.90179078112475,9.8035815622495,25.11281055420629,Solve_Succeeded,76.651006639,36
+D_front,D_front_x1p15,1.15,1.38,4.629125252379634,9.258250504759268,23.929064563227428,Solve_Succeeded,114.6799860220001,51
+C_d,C_d_x0p85,0.85,1.343,4.732673846625645,9.46534769325129,24.373709527780054,Solve_Succeeded,91.18542284300008,36
+C_d,C_d_x1p15,1.15,1.817,4.747695161405053,9.495390322810106,24.442892572842457,Solve_Succeeded,75.72656160200006,35
+h,h_x0p85,0.85,0.20909999999999998,4.736617700377183,9.473235400754366,24.388892039984515,Solve_Succeeded,76.00479720299995,36
+h,h_x1p15,1.15,0.2829,4.743668823804108,9.487337647608216,24.426229710426636,Solve_Succeeded,90.405708581,36

data/sensitivity/skidpad_sensitivity_summary.json

@@ -0,0 +1,88 @@
+{
+  "config": "configs/skidpad.yaml",
+  "delta": 0.15,
+  "score_base_s": 4.740072009101534,
+  "knobs": [
+    {
+      "knob": "m",
+      "label": "mass m",
+      "base_value": 170.0,
+      "score_lo": 4.615329978661124,
+      "score_hi": 4.834693092402854,
+      "swing_s": 0.21936311374173023,
+      "elasticity": 0.1542614495592229
+    },
+    {
+      "knob": "Iz",
+      "label": "yaw inertia Iz",
+      "base_value": 250.0,
+      "score_lo": 4.737568582217398,
+      "score_hi": 4.742002966935889,
+      "swing_s": 0.004434384718490669,
+      "elasticity": 0.0031183666337952203
+    },
+    {
+      "knob": "reg_u_l2",
+      "label": "reg_u_l2",
+      "base_value": 0.015,
+      "score_lo": 4.733660775527216,
+      "score_hi": 4.747747794848977,
+      "swing_s": 0.01408701932176104,
+      "elasticity": 0.009906332853672681
+    },
+    {
+      "knob": "D_rear",
+      "label": "rear grip D_rear",
+      "base_value": 1.2,
+      "score_lo": 5.094813913837953,
+      "score_hi": 4.456787934473439,
+      "swing_s": -0.6380259793645138,
+      "elasticity": -0.4486753071397957
+    },
+    {
+      "knob": "boundary_margin",
+      "label": "margin",
+      "base_value": 0.2,
+      "score_lo": 4.732085539416261,
+      "score_hi": 4.7480569541913695,
+      "swing_s": 0.015971414775108883,
+      "elasticity": 0.011231485333585482
+    },
+    {
+      "knob": "C_l",
+      "label": "downforce C_l",
+      "base_value": 5.54,
+      "score_lo": 4.8439512656554555,
+      "score_hi": 4.633963737301138,
+      "swing_s": -0.20998752835431755,
+      "elasticity": -0.14766831105175554
+    },
+    {
+      "knob": "D_front",
+      "label": "front grip D_front",
+      "base_value": 1.2,
+      "score_lo": 4.90179078112475,
+      "score_hi": 4.629125252379634,
+      "swing_s": -0.27266552874511607,
+      "elasticity": -0.19174499755950541
+    },
+    {
+      "knob": "C_d",
+      "label": "drag C_d",
+      "base_value": 1.58,
+      "score_lo": 4.732673846625645,
+      "score_hi": 4.747695161405053,
+      "swing_s": 0.015021314779407824,
+      "elasticity": 0.010563352026836309
+    },
+    {
+      "knob": "h",
+      "label": "CG height h",
+      "base_value": 0.246,
+      "score_lo": 4.736617700377183,
+      "score_hi": 4.743668823804108,
+      "swing_s": 0.007051123426925265,
+      "elasticity": 0.004958520611350927
+    }
+  ]
+}