Quick-start: COPPER-PRAS¶

Assumes the setup guide is done: M3-linkages on the PRAS branch, COPPER in dependencies/copper, pras-linkage in dependencies/pras-linkage, and the m3linkages_env, copper_env and pras_env environments in place.

1. Stage a scenario¶

Copy an existing scenario folder (for example scenarios/Reference) to scenarios/<scenario> and edit its config.toml:

[General]
    models_to_run = ["COPPER", "PRAS"]
    ...

[Models.PRAS]
    repo_path = "dependencies\pras-linkage"
    env_name  = "pras_env"
    [Models.PRAS.Config]
        year = 2050
        pras_samples = 10000

Leave [Models.COPPER] as you would for any COPPER run; the year in [Models.PRAS.Config] must be one COPPER solves.

2. Run¶

conda activate m3linkages_env
python linkage.py -sc <scenario>

Useful flags:

Flag	Effect
`-t`	Test mode: COPPER's test settings and `test_pras_samples` (default 100) instead of `pras_samples`.
`-sk`	Skip a stage whose results already exist: COPPER if its outputs are present, PRAS if `global_metrics.txt` is present.
`-o <abs path>`	Write all outputs under an absolute path instead of the scenario folder.

What happens:

The COPPER stage runs and writes scenarios/<scenario>/<scenario>_1/copper/outputs/.
scripts/pras_runner.py reads [Models.PRAS], checks that a *_output_summary.csv exists in that folder, and writes dependencies/pras-linkage/scenarios/pras/config.yaml.
In pras_env, pras-linkage/main.py -sc pras -o <scenario>_1 pulls the CODERS backbone, merges COPPER's plan, writes the PRAS text groups and pras.pras, and launches PRAS_analysis.jl.

3. Read the outputs¶

All under scenarios/<scenario>/<scenario>_1/pras/:

File	Contents
`pras-output/global_metrics.txt`	System LOLE and EUE, plus the regional breakdown.
`pras-output/lole.txt`, `pras-output/eue.txt`	The two headline numbers alone, for scripting.
`pras-output/hourly_outages.csv`	Shortfall by region and hour (mean over samples).
`pras-output/hourly_utilization.csv`, `congested_interfaces.txt`	Interface flows and the interfaces that bind.
`pras-output/genstorage_injection.csv`, `genstorage_energy_soc.csv`	Reservoir-hydro injection and state of charge.
`pras-input/pras.pras`	The PRAS system model (HDF5), reusable for any further Julia analysis.
`pras-input/*.txt`	The PRAS groups as text (regions, generators, storages, lines, interfaces).
`pras-input/cem_processing_summary.txt`, `debug_cem_*`	What the preprocessor built from COPPER, for checking.

The pras-linkage dashboard renders hourly_outages.csv as a map, time series and table.

4. Re-run PRAS without re-running COPPER¶

Change the PRAS settings and either run with -sk (COPPER is skipped because its outputs exist) or call the PRAS stage directly:

conda activate m3linkages_env
python scripts/pras_runner.py -lp scenarios/<scenario> -i 1

Add -t for a short run and -o <abs path> if the outputs live elsewhere.

5. Use pras-linkage standalone¶

Any COPPER results folder can be assessed without the M3 runner. In dependencies/pras-linkage, copy scenarios/example_scenario/config.yaml to scenarios/<name>/config.yaml, set mode: "cem" and cem_path to the COPPER outputs folder, then:

conda activate pras_env
python main.py -sc <name> -o <results folder>

Outputs land in <results folder>/<name>/pras-input and pras-output. With mode: "coders" the same command assesses the CODERS fleet for year with no CEM at all.

6. Common variations¶

Extreme weather. Set apply_weather_multipliers = true and weather_multiplier_scenario to a folder under pras-linkage/configurations/. Each folder holds generator/<type>_capacity_multiplier.csv and <type>_failure_multiplier.csv (coal, gas, nuclear, oil, hydro storage) and a transmission/ set, by region and hour. Folders shipped on dev: 2025, 2025_extreme_draught10, 2025_extreme_draught10_noHeatwave. The scripts in pras-linkage/weather_data/ derive new multiplier sets from ERA5 temperature and drought indices (they need a Copernicus CDS account).

Provincial resolution. aggregate_provinces = true collapses the nodal network to ten provincial regions after preprocessing; include_interprovincial = false islands each region.

New transmission from COPPER. new_transmission_mode = "distribute" spreads COPPER's added capacity over the existing CODERS corridors; "new_line" adds explicit lines.

Equivalent firm capacity (EFC). Build two scenarios (for example current and expanded transmission), then in the baseline scenario's configuration set efc_enabled = true with efc_baseline_scenario and efc_comparison_scenario naming the two pras-linkage scenarios. PRAS_analysis_EFC.jl bisects up to efc_capacity_bound MW with efc_samples samples per step. Through the M3 runner every PRAS scenario is named pras, so EFC is easiest to run standalone with two named scenarios.

Effective load-carrying capability (ELCC) and the US-BC intertie are standalone-only options of pras-linkage (elcc_* and us_bc_intertie in config.yaml); the M3 runner does not write them.

7. Checks that a run is sound¶

cem_processing_summary.txt lists every group written; a missing generatorstorages_* set means reservoir hydro was not recognised.
Compare COPPER's capacity by province with the sum of generators_capacity and generatorstorages_* in pras-input; a gap usually means unmapped nodes (check debug_cem_* for regions that failed assignment).
An LOLE of exactly zero with few samples is not evidence of adequacy; use the full pras_samples before quoting a number.