pnnl/ll-risk-assessment

1. What this repository is

This is a batch Python workflow around PSS/E for assessing risk from large dynamic digital loads (LDDLs). It is not a web service or library package; the architecture is a sequence of standalone scripts that pass files between stages.

2. Primary boundary: Python orchestration vs. PSS/E simulation engine

The Python scripts call into PSS/E v35 to read power-flow and dynamic cases, modify models, run time-domain simulations, and extract channel outputs. The main external dependency is the local PSS/E installation configured in psse_config.py.

3. Input case layer

Network models live in PSSE_Cases/ as .sav, .raw, and .dyr files. These are the base system artifacts that every stage reads and/or clones. The repo includes a WECC 240-bus example plus legacy/demo cases in RATLLE_v1.0/PSSE_Cases/.

4. Configuration-driven control plane

User choices are not hardcoded into the pipeline; they come from CSVs:

- Pre_Screening_config.csv for screening and modal prep

- modal_analysis_config.csv for impulse and mode estimation

- simulation_config.csv for oscillation scenario definition

These configs determine case name, bus, load size, oscillation shape, frequency, and amplitude.

5. Stage 1: case extraction and system summaries

Step1_extract_case_info.py reads the base PSS/E case and writes structured summaries into Processing/:

buses, branches, generators, loads, and areas. These CSVs become the data foundation for later selection, monitoring, and reporting steps.

6. Module 1: pre-screening for vulnerable locations

Step2a_locational_sensitivity.py computes local sensitivity metrics such as dV/dP, dV/dQ, and dθ/dP by applying small fictitious injections at candidate buses.

Step2b_load_impulse.py injects a load impulse at a selected bus and records the ringdown response.

Step2c_mode_estimates.py analyzes that response to identify excitable oscillatory modes.

Together, these scripts narrow the search space from “entire system” to “specific risky buses and frequencies.”

7. Module 2: simulation model preparation

Step3a_simsetup_loadadd.py transforms a chosen load into an LDDL scenario by modifying the case, creating LLmod.sav, LLmod.snp, and a modified .dyr. It also adds the oscillation injection block.

Step3b_simsetup_monitoredqty.py generates the monitored bus/branch/load/generator lists used for channel logging during simulation.

This stage is the main model-boundary transition from screening artifacts to executable dynamic simulation setup.

8. Stage 4: dynamic simulation execution

Step4_runsim.py runs the PSS/E time-domain simulation using the scenario parameters from simulation_config.csv.

The outputs are scenario-tagged and stored in results/ as simulation traces, typically a .out file plus a CSV export. The naming convention keeps multiple runs side-by-side without overwriting.

9. Module 3: post-simulation risk analysis

Step5_analyze_sim.py reads simulation time series and computes risk metrics for buses, generators, lines, loads, and LDDL-related quantities. It produces summary and detail CSVs for threshold violations, worst elements, and time-series metrics.

This is the main data-reduction boundary: dense simulation traces become decision-oriented risk reports.

10. Visualization and engineering checks

Step6_metrics_visualization.py turns analysis outputs into a self-contained HTML dashboard in results/, making the risk output directly reviewable without rerunning PSS/E.

Step7a_distance_z3_reach.py adds a protection-oriented boundary check by comparing apparent impedance trajectories against a Zone 3 distance relay reach.

Step7b_RAS_check.py evaluates simple remedial action scheme trigger rules against the simulated time series.

11. Working directories and artifact flow

Processing/ is the intermediate workspace for extracted case data, sensitivities, impulse responses, and monitored-element lists.

results/ is the final output workspace for simulation traces, metrics, violation tables, and dashboards.

The overall flow is: base case → extracted summaries → pre-screening/modal analysis → modified LDDL case + monitored channels → dynamic run → metrics/visualization/protection checks.

12. Legacy/packaged subproject

RATLLE_v1.0/ is a self-contained version of the same workflow with its own case examples, input configs, scripts, and documentation. Architecturally it mirrors the root-level pipeline, so you can treat it as an older packaged distribution rather than a separate subsystem.