gfm-design

name: gfm-design description: "Use when designing, choosing, or tuning a grid-forming inverter control law for a Simulink/Simscape model, or when a gfm-validation report shows design assumptions or controller parameters need revision. Covers droop, VSG/synchronverter, dVOC, PSC, virtual impedance, inner V/I loops on an LCL, multi-unit P/Q sharing, nominal current/protection envelope checks, and validation-feedback retuning. Produces a populated gfm_params.m parameter struct plus analytical predictions. Out of scope: running sim(), certification/grid-code compliance proof, bridge/PWM correctness, grid-following controllers."

GFM Design

Overview

Forward-design workflow for grid-forming inverters:

specs (S, V, f_n, LCL, droop %, swing dynamics)
   |
   v
choose control law (droop / VSG / dVOC / PSC)
   |
   v
record protection envelope (current limits, modulation headroom, grid-code assumptions)
   |
   v
populate gfm_params.m  (analytical formulas + bandwidth ladder)
   |
   v
predict steady-state, current headroom, and small-signal behavior  (gfm_predict_steady_state + gfm_smallsignal)
   |
   v
hand the parameter struct off to the user's Simulink model — manual sim review closes the loop

The skill never invokes sim(). Stop using it once a model exists and the question becomes "does the sim match the design".

Companion skill: use gfm-validation for simulation-facing work after this skill produces a design. gfm-validation runs or inspects Simulink logs, compares them against gfm_predict_steady_state, and writes validation reports. Keep controller retuning and first-pass parameter design here; keep model execution and log comparison there.

When to use this skill

Use when the user:

• Asks to design or tune a GFM controller from specs
• Wants to choose between droop / VSG / dVOC / PSC for a new model
• Asks to size droop coefficients, virtual inertia, voltage-loop gains, or dVOC eta/alpha
• Modifies gfm_params.m and wants the dependent gains recomputed consistently
• Provides a gfm-validation report and asks whether design assumptions or controller parameters should change

Do NOT use when:

• Simulation is already done and the user is only asking to extract logs, compare signals, or judge pass/fail results → use gfm-validation
• Simulation is already done and the user is debugging raw waveforms without asking for design changes → use gfm-validation or manual sim review
• The question is about PWM correctness, bridge gate ordering, sector tables → out of scope
• The controller is grid-following (PLL-based, current-source) → out of scope

Resource map

References are organized by scope. Read essential ones for every design; read plus ones only when the scenario calls for them.

Essential — GFM-general (any control family)

Essential — Control-law-specific (read only the one you chose)

Essential — Simulation and implementation

These are independent of which control family you chose. Read both for any handoff to Simulink/SPS.

Plus — Read when the scenario demands it

Plus — Control-law implementation extras

Citations

Scripts (scripts/) — add the folder to MATLAB path before calling. All standalone (MATLAB ≥ R2024b; gfm_smallsignal also needs Control System Toolbox):

Workflow

Follow these steps in order. Skipping ahead invalidates downstream choices.

0. Check for a verified baseline. If the user already has a Simulink model that passes its own basic test and the task is "change one thing" (new disturbance, new setpoint, new logging) rather than "design a controller from specs", stop here and use references/verified-baseline-workflow.md. Rebuilding from scratch when a verified baseline exists is a known way to inject sqrt(2)/sqrt(3), sample-time, and convention errors that the baseline already handled correctly.
1. Confirm scope: single inverter or multi-unit? Grid-connected or islanded? SCR (X/R)? LVRT/FRT or strong-grid connection concern? — these gate the choice of control law more than tuning does.
2. Pick a control law using references/control-law-taxonomy.md. Record the why (a sentence) so it lands in the gfm_params.m header.
3. Set the bandwidth ladder before any gain math: f_pwr_filt ≪ f_outer_v ≪ f_inner_i ≪ f_sw/2, and m_p · S_rated · f_pwr_filt ≪ f_n. Reject specs that violate this — they will not be fixable by tuning.
4. Record the protection envelope before handoff math: continuous/short-time current, modulation ceiling, current-limiter mode, anti-windup expectation, and applicable standard/grid-code target. If the user does not provide these, label the output as a nominal controller design only. Read references/current-limiting-and-protection.md and references/standards-and-grid-codes.md for abnormal-event work.
5. If LVRT/FRT is in scope, record voltage-time curves, voltage measurement basis, current-priority rule, negative-sequence/per-phase behavior, momentary-cessation assumption, and current-limit exit rule. Read references/lvrt-and-fault-ride-through.md.
6. If high SCR / strong grid is in scope, check voltage-source stiffness, pre-synchronization assumptions, virtual impedance, damping, and SCR sweep expectations. Read references/strong-grid-stability.md.
7. Compute the law-specific gains via the matching reference + gfm_design_from_specs.m. The function returns a struct with the field names a build_*.m Simulink builder would expect. For dVOC handoff into a Simulink or switching model, read references/dvoc-implementation-conventions.md before declaring a gain or tracking issue.
8. Predict steady state with gfm_predict_steady_state.m. Confirm P_total matches the requested load and inspect frequency/voltage/current headroom before handing off. If any unit is current-limited or modulation-limited, the linear sharing prediction is invalid.
9. (Optional) Linearized check: gfm_smallsignal(p) for a pole/Bode quick-look. All poles in the LHP is the minimum bar; any RHP pole means the design is unstable. For strong-grid work, sweep L_g / SCR rather than checking only one grid strength.
10. Hand off. Give the user the populated p struct and a short rationale; tell them to plug it into their Simulink model and run manual sim review. If the user asks for model-building guidance, cite references/simulink-modeling-conventions.md and references/gfm-test-scenarios.md. Do NOT claim the design is verified by this skill alone — the skill only produces a design, not evidence.

Validation feedback loop

When the user returns with a gfm-validation report, read references/validation-feedback-loop.md before changing parameters. Triage findings in this order:

1. Measurement/logging issue: unit mismatch, sign convention, wrong PCC boundary, or bad settled window. Send the user back to gfm-validation or model logging fixes; do not retune.
2. Scenario outside assumptions: current limiting, modulation saturation, LVRT/FRT, unbalanced fault, high-SCR stress, or a grid impedance not represented in p. Update assumptions and protection notes before retuning.
3. Quantifiable steady-state offset (dVOC): if |P_pcc/P_set| is a stable ratio close to but not equal to 1, with sign and Q correct, check references/dvoc-steady-state-diagnosis.md BEFORE retuning. Two routine contributors (voltage-reference-vs-grid mismatch and filter ohmic loss) explain almost all such offsets with closed-form formulas — no controller change needed.
4. Design mismatch: prediction and logs are measured correctly but final P/Q/f/V, damping, sharing, or current headroom miss the target. Re-enter this skill's design workflow with the validation metrics as new specs.
5. Model implementation mismatch: controller interface, Park convention, limiter behavior, or inner-loop realization differs from the parameter-struct conventions. State the mismatch and either adapt the handoff assumptions or ask the user to align the model.

Never treat a failed validation report as automatic proof that droop/VSG/dVOC/PSC gains are wrong. First prove the simulation case matches the design assumptions.

Parameter-struct conventions

gfm_design_from_specs.m returns a struct in a schema that a typical Simulink GFM model can consume directly. The conventions below describe what each field assumes about the Simulink target; deviate only with reason.

• Plant topology assumed: DC bus → Universal Bridge → L_f (RL) → Cf-Rd shunt to Yg → L_2 (RL) → VI Meas → Grid Z → Three-Phase Source (Yg).
• Controller intended as a MATLAB Function block, codegen-compatible, sampled at p.Ts_ctrl. It owns all state (no inner V/I loops as separate blocks).
• Controller output: m_abc ∈ [-1, 1] direct to a PWM Generator (2-Level) with ModulatingSignals='off' (external modulation). No SVPWM, no dq-frame outputs.
• Protection fields (I_cont_peak, I_limit_peak, I_short_peak, t_short_limit, m_max, current_limit_mode) are design-screening assumptions. They do not implement protection unless the user's controller consumes them.
• LVRT/FRT fields (if present) are assumptions for a future simulation or HIL test harness: voltage-time curve, measurement basis, current-priority rule, sequence/per-phase behavior, and recovery logic.
• Strong-grid fields (if present) are stress-case assumptions: SCR/X/R sweep range, virtual impedance, pre-synchronization thresholds, and high-SCR damping checks.
• Discrete power system: powergui in Discrete mode, Ts = p.Ts_power = 1e-6. Solver ode23tb with MaxStep = 1e-4.
• gfm_params() should assignin('base','p',p) so block parameters like 'p.V_dc' resolve at compile time.

A Simulink model that violates these conventions will still accept the p struct, but the user must adapt the controller block to match the assumed interface (peak phase voltages, instantaneous P/Q from amplitude-invariant Park, etc.).

Output expectations

When the design phase ends, produce:

1. A populated gfm_params.m (printed inline, or written to disk on user request).
2. A short rationale: chosen law + one sentence why, the bandwidth ladder values, predicted steady-state P/Q/current headroom from gfm_predict_steady_state.
3. A protection/grid-code assumptions note: current limits used, limiter mode, modulation headroom, and whether IEEE/UNIFI/site requirements are known or still missing.
4. LVRT/FRT and strong-grid notes when relevant: what was assumed, what remains untested, and which scenarios must be run outside the skill.
5. (Optional) Small-signal pole locations from gfm_smallsignal if stability margin matters.

Ground non-obvious recommendations in a local reference doc and, where possible, the primary source listed in references/bibliography.md. If a recommendation is only an engineering heuristic, say so explicitly.

Do not pretend to have run simulations or compliance tests. The skill never invokes sim() — simulation and grid-code evidence come from the user running MATLAB+Simulink, EMT/HIL cases, and project-specific review.