ANDES: fix run_eigenvalue_analysis + add PSS/E raw+dyr dynamic-model loading

[elasticdotventures]

Summary

Two combined fixes/additions to the ANDES MCP server (ANDES/andes_mcp.py), motivated by wanting to use ANDES's small-signal/eigenvalue analysis for oscillation-risk review (per AEMO's 2026 General Power System Risk Review, which names small-signal stability and inter-area oscillation damping as active industry concerns, and separately notes system operators moving off proprietary small-signal tooling).

1. Fix run_eigenvalue_analysis (real bug, not a new feature)

run_eigenvalue_analysis read ss.EIG.vectors and ss.EIG.state_desc after calling ss.EIG.run(). Neither attribute exists on ANDES's real EIG routine object — the code's own hasattr() guards meant eigenvectors/state_variables have silently returned [] since the tool was written, with no error and no test coverage catching it.

Verified two ways: read andes/routines/eig.py directly (GitHub + a local install), and installed andes 2.0.0 into a venv and printed hasattr(ss.EIG, ...) for old vs. new attribute names directly. Real attributes: mu (eigenvalues, complex array), N/W (right/left eigenvector matrices), pfactors (participation factors), x_name (state labels).

Fix: reads the real attributes and derives frequency_hz/damping_ratio_pct per mode using the exact formula ANDES's own EIG.post_process() uses internally for its text report:

freq_hz = |Im(mu)| / (2*pi)
damping_pct = -100 * Re(mu) / |mu|

New return shape (documented in ANDES/README.md): n_modes, modes (list of {eigenvalue: [re, im], frequency_hz, damping_ratio_pct, is_oscillatory}, sorted least-damped/most-concerning first), participation_factors, state_names, success.

2. Add PSS/E raw+dyr dynamic-model loading to run_power_flow

run_power_flow previously only loaded static topology — no way to attach a PSS/E .dyr dynamic-model file (generators, exciters, governors) to a .raw case, so run_time_domain_simulation/run_eigenvalue_analysis had no real dynamics to operate on except via the one bundled all-JSON ANDES/kundur_full.json fixture.

Added an optional dyr_path: Optional[str] = None parameter, following the function's existing scaffolding exactly (abspath/exists-check, copy into the run directory, conditional addfile kwarg to andes.run(...) only when supplied — the no-dyr call path is byte-identical to before). Two new, purely additive return fields: dynamic_models_loaded and n_dynamic_generators (from ANDES's SynGen model group, not get_system_info's existing num_generators, which is already non-zero from static PV buses alone even with no .dyr loaded).

No new fixture file is vendored into this repo. Tests resolve ANDES's own bundled ieee14 PSS/E example case at test-call time via andes.get_case("ieee14/ieee14.raw") / andes.get_case("ieee14/ieee14.dyr") — a real, documented top-level function in andes 2.0.0 (declared as package-data in andes's own pyproject.toml), confirmed live: ss.groups["SynGen"].n is 0 loading ieee14.raw alone, 5 loading it with addfile=ieee14.dyr. This avoids authoring a new .dyr file by hand, which carries real risk given ANDES's own PSS/E dyr parser has known real-world compatibility gaps on some model types.

Tests

tests/test_andes_server.py (new), using a shared andes_mcp fixture in tests/conftest.py (factored out of tests/test_powerio_server.py's prior ad hoc bootstrap): power flow convergence, system info, time-domain simulation, and the eigenvalue-analysis regression check (non-empty state_names/numeric frequency_hz/damping_ratio_pct per mode — would have been empty before the fix) on kundur_full.json; plus four raw+dyr tests on ANDES's bundled ieee14 case (dynamics absent without dyr_path, present with it, enabling time-domain simulation, and a missing-file error path).

All tests are pytest.importorskip("andes")-guarded, matching this repo's existing convention for the optional andes extra — they run and pass against a real andes install (verified locally: 9/9 passed) and skip cleanly (not fail) when andes isn't installed (verified locally in a clean venv with no extras: 106 passed, 13 skipped, 0 failed).

Docs

ANDES/README.md: documented both new/changed tool signatures and return shapes, added a license note (ANDES is GPL-3.0; installed only as an optional pip extra, never vendored into this MIT-licensed repo — including the raw+dyr test fixture, which is referenced from the installed package, not vendored), added a raw+dyr prompt example. powermcp/README.md: filled in the previously-empty Notes column for the andes extras-table row.

[qian-harvard]

Reviewed and integrated in #58 — thanks for this, the eigenvalue bug was a real one and well diagnosed. Since this branch was cut from 52deb67, before #57 landed the MCP 2 migration and checked_path containment, it conflicted in ANDES/andes_mcp.py and both READMEs; #58 carries your commits as a merge parent and resolves against main.

Conflict resolution

Kept main's sandboxed structure (_prepare_run_dir, checked_path) and re-applied your two features on top. ANDES/README.md keeps main's load_network_from_* lines — they document #57's operating_point / study_commit parameters, which your rewrite predates and would otherwise have dropped.

Findings addressed in #58

1. dyr_path bypassed the sandbox. Not your doing — containment landed after you branched — but the merge would have added a second, unchecked path argument to a function main had just finished containing. dyr_path now goes through checked_path, and the .dyr copy into the run directory is a checked write.

2. Sorting modes desynced them from participation_factors. modes.sort(...) reorders only the mode list, while pfactors and x_name keep ANDES's native ordering. So modes[0] and participation_factors[0] describe different eigenvalues — which breaks the exact question the tool exists to answer ("which state drives the least-damped mode?"). Each mode now carries its native index.

3. Real eigenvalues were hardcoded to damping_ratio_pct = 0.0. ANDES's post_process() applies -100*Re/|mu| to every mode with no imag == 0 special case, so real modes get ±100%. A real positive eigenvalue is monotonic instability — the most severe small-signal result there is — and at 0.0 the ascending sort buried it mid-list, below stable oscillatory modes. Only a mode at the origin is special-cased now. Your frequency_hz = 0.0 for real modes was correct and is unchanged.

4. dynamic_models_loaded reported the argument, not the result. Your own PR body notes that ANDES's PSS/E dyr parser has gaps on some model types — which means a supplied .dyr can attach nothing while the flag still says True. It is now derived from the model count, which also sums RenGen and DG so an inverter-only .dyr isn't reported as zero dynamics.

5. n_eigenvalues / eigenvalues were dropped. eigenvalues carried real data (ss.EIG.mu.tolist()); only eigenvectors and state_variables were the always-empty broken fields. Both are restored as aliases, making the change purely additive like the run_power_flow half of your PR.

Minor: math.pi replaces the numpy import added for one constant, and the andes_mcp fixture points POWERMCP_HOME at a per-test tmp_path — run directories are named after the case stem, so your two ieee14 tests shared one directory and leaked the .dyr copy between them.

Your test file and the conftest.py fixture extraction are kept as written, plus four tests covering the fixes above. Verified against a real andes 2.0.0 install: 13 passed; extras-free venv: 374 passed, 17 skipped.

Closing in favour of #58.