Surge workflow
Start by loading a network with load_builtin_case, load_network, or create_empty_network. Solve the base case before any advanced study — contingency, sensitivity, and OPF results are meaningless on a non-convergent base.
Default tool ladder
load_builtin_case(name) (e.g. case118), load_network(file_path, format?), or create_empty_network(...).get_network_info() for counts, totals, areas, zones, voltage levels. get_topology(...) / get_islands() / find_path(...) for connectivity reasoning.run_ac_power_flow(...) for the base operating point. run_dc_power_flow(...) only when a linearized study is explicitly requested.- Sensitivities:
compute_ptdf, compute_lodf, compute_otdf for screening and transfer analysis.
run_n1_branch_contingency / run_n1_generator_contingency / run_n2_branch_contingency once the base case solves.run_dc_opf → run_ac_opf → run_scopf for optimization. Pass explicit lp_solver / nlp_solver only when the deployment requires it.run_sced (single-period) and run_scuc (multi-period commitment). Call get_dispatch_request_schema() before constructing the request dict.compute_nerc_atc / compute_ac_atc for transfer capability. Build source/sink bus lists from list_buses output.export_tables(output_dir) to hand CSVs back to the user.
Network construction & editing
For synthetic cases, scenario edits (outage, dispatch change, load scaling), or mutations to a loaded case. Re-solve run_ac_power_flow after any material edit.
- Build:
create_empty_network, add_bus, add_generator, add_load, add_line, add_transformer, add_storage.
- Edit:
set_branch_rating, set_branch_in_service (outages), set_generator_limits, set_generator_in_service.
- Scale:
scale_loads(factor, area?), scale_generators(factor, area?).
- Remove:
remove_bus, remove_branch, remove_generator, remove_load.
Working rules
- Do not read contingency or sensitivity results from a non-convergent base case.
- Sensitivity tools default to
format="summary". Use "sparse" or "full" only when CSR or dense output is actually needed.
- Solver selection is a deployment question. Default to auto-detect (
"default"); pass "highs" / "ipopt" for open-source runs, "gurobi" for large MIPs. See references/SOLVER_GUIDE.md.
- Call
get_dispatch_request_schema() before building a run_sced / run_scuc request dict.
- Hand off RMS / transient-stability questions to ANDES, harmonic / unbalanced questions to OpenDSS.
Escalation triggers
Map observed violations to the mitigation skill that handles them. If multiple triggers fire, escalate voltage → thermal → contingency.
| Observation |
Escalate to |
Any bus vm_pu < 0.95 or > 1.05 |
voltage-violation-mitigation |
Any branch loading > 100% of rate_a_mva |
thermal-overload-mitigation |
run_n1_* returns ≥ 1 binding contingency |
contingency-mitigation |
get_islands() returns > 1 island after a contingency |
contingency-mitigation |
| SCED / SCUC infeasible, reserve shortage, or LMP volatility |
operations-planning-mitigation |
run_ac_power_flow fails to converge on the base case |
convergence-failure-mitigation |
| The study is a new generator, storage, or large-load connection at a POI |
interconnection-impact-mitigation |
Report the specific numbers that triggered the escalation (bus + vm_pu, branch + loading %, contingency label). Do not say "violations exist" without values.
Local assets
scripts/network_analysis.py — inspection and base PF review.scripts/sensitivity_analysis.py — PTDF, LODF drill-down.scripts/contingency_analysis.py — N-1 / N-2 summaries.scripts/contingency_ranking.py — N-1 → severity rank → CSV → mitigation-skill mapping. python contingency_ranking.py <case> <out_dir>.scripts/opf_analysis.py — DC / AC / SCOPF with solver-selection examples.scripts/dispatch_analysis.py — SCED / SCUC.scripts/transfer_capability.py — NERC ATC and AC ATC path setup.scripts/test_scripts.py — end-to-end smoke test on a built-in case.references/API_REFERENCE.md — 44-tool catalog.references/SOLVER_GUIDE.md — HiGHS / Gurobi / Ipopt selection.references/EXAMPLES.md — multi-tool workflows.references/DISPATCH_REQUEST_SCHEMA.json — JSON schema for run_sced / run_scuc request. Also served by get_dispatch_request_schema().
Report back
- Case loaded (name or path) and key counts from
get_network_info.
- Base-case convergence. If not converged, stop and report the mismatch.
- Main result of the requested study (violations, LMPs, ATC MW, top sensitivity entries).
- Which mitigation skill is next, if any.
1---2name: surge3description: Use this skill for transmission power-system studies — AC/DC power flow, DC-OPF / AC-OPF / SCOPF, N-1 / N-2 contingency analysis, PTDF / LODF / OTDF sensitivities, NERC and AC Available Transfer Capability (ATC), SCED economic dispatch, and SCUC unit commitment. Also use for building or editing a transmission network (add / remove / scale buses, lines, transformers, generators, loads, storage). Use whenever the user references an IEEE benchmark case (case9, case14, case30, case57, case118, case300, market30) or IEEE 14-/30-/57-/118-/300-bus network, or asks to load a MATPOWER .m, PSS/E RAW, XIIDM, or CIM/CGMES file and run a steady-state study. Trigger on phrases like "power flow", "run OPF", "contingency analysis", "PTDF", "ATC", "economic dispatch", "unit commitment", "build a network", or "scale load by X%" — even if the user does not mention Surge by name. Not for transient-stability dynamics (route to ANDES) or harmonic / unbalanced distribution feeders (route to OpenDSS).4---56# Surge workflow78Start by loading a network with `load_builtin_case`, `load_network`, or `create_empty_network`. Solve the base case before any advanced study — contingency, sensitivity, and OPF results are meaningless on a non-convergent base.910## Default tool ladder111. `load_builtin_case(name)` (e.g. `case118`), `load_network(file_path, format?)`, or `create_empty_network(...)`.122. `get_network_info()` for counts, totals, areas, zones, voltage levels. `get_topology(...)` / `get_islands()` / `find_path(...)` for connectivity reasoning.133. `run_ac_power_flow(...)` for the base operating point. `run_dc_power_flow(...)` only when a linearized study is explicitly requested.144. Sensitivities: `compute_ptdf`, `compute_lodf`, `compute_otdf` for screening and transfer analysis.155. `run_n1_branch_contingency` / `run_n1_generator_contingency` / `run_n2_branch_contingency` once the base case solves.166. `run_dc_opf` → `run_ac_opf` → `run_scopf` for optimization. Pass explicit `lp_solver` / `nlp_solver` only when the deployment requires it.177. `run_sced` (single-period) and `run_scuc` (multi-period commitment). Call `get_dispatch_request_schema()` before constructing the `request` dict.188. `compute_nerc_atc` / `compute_ac_atc` for transfer capability. Build source/sink bus lists from `list_buses` output.199. `export_tables(output_dir)` to hand CSVs back to the user.2021## Network construction & editing22For synthetic cases, scenario edits (outage, dispatch change, load scaling), or mutations to a loaded case. Re-solve `run_ac_power_flow` after any material edit.2324- **Build:** `create_empty_network`, `add_bus`, `add_generator`, `add_load`, `add_line`, `add_transformer`, `add_storage`.25- **Edit:** `set_branch_rating`, `set_branch_in_service` (outages), `set_generator_limits`, `set_generator_in_service`.26- **Scale:** `scale_loads(factor, area?)`, `scale_generators(factor, area?)`.27- **Remove:** `remove_bus`, `remove_branch`, `remove_generator`, `remove_load`.2829## Working rules30- Do not read contingency or sensitivity results from a non-convergent base case.31- Sensitivity tools default to `format="summary"`. Use `"sparse"` or `"full"` only when CSR or dense output is actually needed.32- Solver selection is a deployment question. Default to auto-detect (`"default"`); pass `"highs"` / `"ipopt"` for open-source runs, `"gurobi"` for large MIPs. See `references/SOLVER_GUIDE.md`.33- Call `get_dispatch_request_schema()` before building a `run_sced` / `run_scuc` request dict.34- Hand off RMS / transient-stability questions to ANDES, harmonic / unbalanced questions to OpenDSS.3536## Escalation triggers37Map observed violations to the mitigation skill that handles them. If multiple triggers fire, escalate voltage → thermal → contingency.3839| Observation | Escalate to |40|---|---|41| Any bus `vm_pu < 0.95` or `> 1.05` | `voltage-violation-mitigation` |42| Any branch loading > 100% of `rate_a_mva` | `thermal-overload-mitigation` |43| `run_n1_*` returns ≥ 1 binding contingency | `contingency-mitigation` |44| `get_islands()` returns > 1 island after a contingency | `contingency-mitigation` |45| SCED / SCUC infeasible, reserve shortage, or LMP volatility | `operations-planning-mitigation` |46| `run_ac_power_flow` fails to converge on the base case | `convergence-failure-mitigation` |47| The study is a new generator, storage, or large-load connection at a POI | `interconnection-impact-mitigation` |4849Report the specific numbers that triggered the escalation (bus + vm_pu, branch + loading %, contingency label). Do not say "violations exist" without values.5051## Local assets52- `scripts/network_analysis.py` — inspection and base PF review.53- `scripts/sensitivity_analysis.py` — PTDF, LODF drill-down.54- `scripts/contingency_analysis.py` — N-1 / N-2 summaries.55- `scripts/contingency_ranking.py` — N-1 → severity rank → CSV → mitigation-skill mapping. `python contingency_ranking.py <case> <out_dir>`.56- `scripts/opf_analysis.py` — DC / AC / SCOPF with solver-selection examples.57- `scripts/dispatch_analysis.py` — SCED / SCUC.58- `scripts/transfer_capability.py` — NERC ATC and AC ATC path setup.59- `scripts/test_scripts.py` — end-to-end smoke test on a built-in case.60- `references/API_REFERENCE.md` — 44-tool catalog.61- `references/SOLVER_GUIDE.md` — HiGHS / Gurobi / Ipopt selection.62- `references/EXAMPLES.md` — multi-tool workflows.63- `references/DISPATCH_REQUEST_SCHEMA.json` — JSON schema for `run_sced` / `run_scuc` `request`. Also served by `get_dispatch_request_schema()`.6465## Report back66- Case loaded (name or path) and key counts from `get_network_info`.67- Base-case convergence. If not converged, stop and report the mismatch.68- Main result of the requested study (violations, LMPs, ATC MW, top sensitivity entries).69- Which mitigation skill is next, if any.
power-agent