diff --git a/docs/PROJECT_STATE.md b/docs/PROJECT_STATE.md new file mode 100644 index 0000000..0b5272f --- /dev/null +++ b/docs/PROJECT_STATE.md @@ -0,0 +1,72 @@ +# Project State — Session Handoff + +**Last updated: 2026-07-11** · Refresh this file at each phase boundary so any new session can resume exactly here. + +--- + +## 1. Current status — resume banner + +The **simulation phase is complete** — see [`docs/EOD_SUMMARY_2026-07-11.md`](EOD_SUMMARY_2026-07-11.md) for the formal phase-close record. The project is now entering the **paper / writing phase**, gated on the literature review in issue **#50**. A presentation of the three control-law block diagrams and the three-regime co-design story was **well received; reviewers want to see the paper**, which is why the writing phase is starting now. + +--- + +## 2. What is done (link — do not re-derive) + +- **Plant validation (foundation):** validated vs WEC-Sim / Husain & Ogden et al. (ASME JOMAE 145(3):030905) — ω_n within ±0.6% (Table 2), ζ vs Fig. 4 (~30–50×10⁻⁴); Table 2 ×10⁻³/×10⁻⁴ exponent-discrepancy finding documented. See [`docs/freedecay_validation.md`](freedecay_validation.md). +- **Three-regime co-design relay:** CC → opt_passive → ff+PID across VGM-0/10/20/45/90 on shared T = 0.5–7 s grid at H = 0.05 m; resonance slides with flap angle (T₀ 2.99 s @ VGM-90 → 5.86 s @ VGM-0). See [`analysis/FINDINGS_3REGIME.md`](../analysis/FINDINGS_3REGIME.md) and [`scripts/three_regime_comparison.py`](../scripts/three_regime_comparison.py). +- **Dual operating envelopes:** power hull (peak 2.34 W at T = 1.5 s, VGM-0, CC) and mask-respecting efficiency hull (CC near-Budal ~99% at short T); the power and efficiency co-design schedules diverge at long T — power favors VGM-0 opt_passive (largest excitation); efficiency favors ff+PID on more-open flaps (largest fraction of P_opt). See [`analysis/three_regime/operating_envelope.csv`](../analysis/three_regime/operating_envelope.csv) and [`operating_envelope_efficiency.csv`](../analysis/three_regime/operating_envelope_efficiency.csv). +- **Reproducibility:** every dataset regenerable from documented commands. See [`docs/REPRODUCTION.md`](REPRODUCTION.md). + +--- + +## 3. Paper plan / positioning + +### Working thesis / novelty framing +The contribution is **not** a new control law. Two of the three controllers are textbook-mature: + +- **Optimal-passive** (`B_opt = |Z_intrinsic(ω₀)|`, optimal resistive loading) — foundational result; Falnes; covered as the passive baseline in Ringwood's reviews. +- **Complex-conjugate / reactive impedance matching** — the classical theoretical optimum / Budal bound; Falnes, Ringwood 2014. Its non-causality and reactive-power requirements are extensively documented in the literature. + +The third, **ff+PID** (excitation feedforward + velocity-tracking PID + passive-safety guard), is an engineered causal scheme positioned in the Fusco & Ringwood excitation-feedforward / velocity-reference lineage and the passivity-guarded control literature (Bacelli, Faedo, Ringwood). + +The **real novelty is the controller × variable-geometry (flap-angle) operating map** — the regime relay over (wave period × flap vent angle × controller). + +### Honest-framing rules to preserve in the manuscript +- Regime ordering is physically expected → frame as **systematic simulated quantification**, not discovery. +- Fixed-passive was pruned as degenerate → do not promote it as a meaningful arm. +- ff+PID "ties opt_passive at resonance" — do **not** claim it is universally optimal. +- ff+PID uses **empirical (not formally optimized) gains**; formal gain optimization is the #54 second-paper scope. + +### Known limitation to disclose +ff+PID tracks the raw un-hinge-referred pitch excitation with a signed `alpha` absorbing the phase/sign mismatch — see [`docs/CONTROLLERS.md`](CONTROLLERS.md) §Known limitations. Decide in the manuscript whether to fix hinge-referencing or pre-empt it in the limitations section. + +### Maturity caveat +The maturity placements above are drawn from general knowledge of the Ringwood / Fusco / Faedo body of work, **not a live citation check**. Every citation and novelty claim **must** be verified against the actual papers as part of issue **#50** before submission. Do not cite a Ringwood reference without confirming its exact framing. + +--- + +## 4. Presentation decisions (captured so the talk is reproducible) + +- Three control-law block diagrams (opt_passive, CC, ff+PID) share one template: wave → F_exc source, magenta PTO block, summing junction, `G(s)` plant, `D(s)` kinematics feedback. +- **`G(s) = 1/(ms²+cs+k)` is a deliberate schematic simplification** for the talk; the real simulated plant carries frequency-dependent added mass A₅₅(ω) and radiation-damping memory B_rad,55(ω) — state this caveat verbally or in a footnote so it does not contradict the WEC-Sim validation. +- **Do NOT combine all three into one diagram** (too dense) — keep three separate slides or a staged build/morph where only the PTO block changes panel-to-panel. Add a summary slide ("same plant G(s), three PTO laws → three operating regimes") with an operating-envelope thumbnail. +- The CC / opt_passive gains are evaluated at a design frequency ω₀ (not general Laplace s) — keep s-vs-ω notation honest in captions and any spoken clarification. + +--- + +## 5. Open tracks / issue board + +| Issue | Track | Status | +|-------|-------|--------| +| **#50** | Literature positioning & related-work verification | **First-paper critical path / next action** | +| **#54** | ff+PID gain optimization | Follow-on / second paper | +| **#4** | ROS 2 HIL bridge (`RosPTOModel`) | Deployment track — parked | + +**Closed during consolidation:** #29, #30, #41 (completed); #9 (consolidated into #4). + +--- + +## 6. Immediate next actions + +1. **Kick off #50** — deep-research literature review to produce the related-work section skeleton + novelty verdict; this is the gate before any manuscript drafting begins. +2. **Refresh this file** at each subsequent phase boundary (end of lit review, start of drafting, etc.).