exc_ff_pid: passive-safety guard, per-flap Kp×Kd tuning, surface plots, and 5-flap configs

[Copilot]

Consolidates empirical exc_ff_pid controller tuning (α=11 universal, Ki=5 fixed) across all five VGM flap variants with a passive-safety guard that prevents energy injection at band edges.

Passive-safety guard (src/active_pto.{h,cpp}, src/config_loader.{h,cpp}, src/demo_vgoswec.cpp)

New passive_safe boolean (default true) in ExcFFPIDConfig. When enabled, any candidate torque that would inject energy (τ · θ̇ > 0) is replaced by the guaranteed-dissipative damping floor before the final clip:

double tau = tau_damp + tau_pid;
if (passive_safe_ && (tau * vel > 0.0)) {
    tau = tau_damp;   // revert to -B_ctrl·vel — cannot inject
}
return std::clamp(tau, -clip_, clip_);

5 new smoke tests cover: guard triggers on injection, guard is no-op when dissipative, passive_safe=false restores unguarded behavior, and config schema (including default-true check).

Per-flap configs (config/)

• Created: vgoswec_10_exc_ff_pid.yaml, vgoswec_20_exc_ff_pid.yaml, vgoswec_90_exc_ff_pid.yaml
• Updated: vgoswec_0_exc_ff_pid.yaml, vgoswec_45_exc_ff_pid.yaml

All 5 carry: alpha: 11, ki: 5, clip_torque: 10, u_min/u_max: ±10, passive_safe: true. Tuned Kp/Kd:

Flap	T_res [s]	Band [s]	Kp	Kd
VGM-0	5.86	3.5–7.0	4	1
VGM-10	4.29	2.5–6.0	4	1
VGM-20	4.01	2.5–6.0	4	1
VGM-45	3.42	2.0–6.0	4	2
VGM-90	2.99	2.0–5.0	4	2

VGM-45/90 use Kd=2 to maintain corr(τ, θ̇) < 0 at the short-period band edge (T=2.0 s).

Sweep harness + analysis (scripts/, analysis/)

• scripts/sweep_kpkd_vgoswec.sh: sweeps Kp∈{2–6}×Kd∈{0,0.5,1,2,3} per flap over each flap's physical band; evaluates passive-safe, clamp-free, pitch<0.8 rad, and non-injecting-edge constraints in a single Python call per period.
• scripts/plot_kpkd_surface.py: generates journal-quality 3-D Kp×Kd capture-surface plots with infeasible-region overlay (red tint) and consistent color scale across flaps.
• analysis/kpkd_sweep_VGM*.csv + analysis/figures/: committed illustrative sweep data and generated figures (documented as synthetic in analysis/README.md; replace by running the sweep script against the built demo).

docs/CONTROLLERS.md

Updated exc_ff_pid section: full guard formula, passive_safe parameter, α=11/Ki=5 empirical rationale, per-flap Kp/Kd table, band-integrated tuning objective, and known-limitation section documenting the un-hinge-referred F_exc issue (peak-below-resonance + guard-contained short-period injection) with pointer to the follow-up PR.