Bc cvar updates

[bcakire]

Summary

Add CVaR/NCVAR resource adequacy reporting and target checks to the PRAS and stress-period workflow.

This PR extends the existing PRAS risk-metric functionality so that CVaR is no longer only calculated internally during a PRAS run. The PRAS workflow can now also write CVaR/NCVAR reporting outputs and sample-level total shortfall files that can be reused by the Python stress-period workflow.

This PR adds:

CVAR/NCVAR reporting from run_pras.jl
A compact PRAS output file with per-sample total shortfall by region
Annual CVAR/NCVAR calculation in stress_periods.py
Threshold-based CVAR/NCVAR target checks
Check-only behavior for CVAR/NCVAR so risk targets can be evaluated without adding stress periods or changing PRM

Technical details

Implementation notes

run_pras.jl updates:

Added --cvar_alpha argument to control the CVaR confidence level
Added --write_shortfall_samples_totals argument
Added CVAR/NCVAR reporting when PRAS.ShortfallSamples() is available
Writes:
PRAS_{t}i{iteration}-risk_metrics.csv
PRAS_{t}i{iteration}-shortfall_totals_by_sample.h5
risk_metrics.csv reports:
CVAR in MWh
NCVAR in ppm
alpha
estimate
standard error
VaR
shortfall_totals_by_sample.h5 stores:
sample index
USA total shortfall by sample
regional total shortfall by sample

stress_periods.py updates:

Added CVAR_METRICS = {'CVAR', 'NCVAR'}
Added support for reading:
PRAS_{t}i{iteration}-shortfall_totals_by_sample.h5
Added:
get_cvar_alpha()
get_shortfall_totals_by_sample()
_sample_cvar()
get_annual_cvar_stress_metric()
evaluate_cvar_target_check()
CVAR/NCVAR are calculated annually by hierarchy level
NCVAR is normalized by annual load and reported in ppm
CVAR/NCVAR are intentionally excluded from stress-period selection

Additional changes

Replaced memory-intensive hourly shortfall sample aggregation with direct use of PRAS_*shortfall_totals_by_sample.h5 where sample-level total shortfall is sufficient
This avoids needing to read PRAS_*shortfall_samples.h5 only to aggregate it again by sample and region
Existing EUE/NEUE/LOLE stress-period selection behavior is unchanged

Switches added/removed/changed

Added:

GSw_PRM_CVARAlpha
GSw_PRM_StressThresholdNCVAR
GSw_PRM_StressThresholdCVAR

Example usage:

GSw_PRM_StressThresholdMetrics = EUE/NCVAR
GSw_PRM_StressThresholdEUE = transgrp_1000_EUE_sum
GSw_PRM_StressThresholdNCVAR = transgrp_10_NCVAR_cvar
GSw_PRM_CVARAlpha = 0.95

For PRAS reporting, run_pras.jl can be called with:

--write_shortfall_samples_totals 1
--cvar_alpha 0.95

Validation, testing, and comparison report(s)

Validation completed on the Pacific test case.

Tests performed:

Ran run_pras.jl with:
--write_shortfall_samples_totals 1
--cvar_alpha 0.95
Verified generation of:
PRAS_2032i0-risk_metrics.csv
PRAS_2032i0-shortfall_totals_by_sample.h5
Verified that shortfall_totals_by_sample.h5 contains sample-level total shortfall by USA and region
Verified that risk_metrics.csv reports CVAR and NCVAR
Verified:
get_shortfall_totals_by_sample()
get_annual_cvar_stress_metric()
evaluate_cvar_target_check()
Confirmed NCVAR threshold failures do NOT:
add stress periods
trigger PRM updates
Confirmed standard EUE stress-period workflow remains unchanged

Example validation output:

GSw_PRM_StressThreshold = country_-1_NCVAR_cvar failed for:
region
USA 0.0
Name: NCVAR, dtype: float64
NCVAR is check-only: no stress periods and no PRM increment will be added.

Checklist for author

Details to double-check

• Charge code provided to reviewers
• Included comparison reports for appropriate test cases
• Documentation updated if necessary
• If input data added/modified:
  • Dollar year recorded and converted to 2004$ for GAMS
  • Timeseries are in Central Time
  • Units are specified
  • Preprocessing steps have been documented and committed to ReEDS_Input_Processing
  • New large data files handled with .h5 instead of .csv
  • If spatially resolved inputs are modified, the following visualizations for each file are included in the PR description (time-averaged if the inputs are time-resolved):
    • Map of absolute values before
    • Map of absolute values after
    • Map of differences: (after - before) or (after / before)
  • If entries are added/removed/changed in the EIA-NEMS unit database:
    • Changes have been committed to ReEDS_Input_Processing
    • hourlize/resource.py was rerun to regenerate the existing/prescribed VRE capacity data
• Code formatting standardized
• Reusable functions used where possible instead of copy/pasted code

General information to guide review

• [X ] Zero impact on results of default case
• [X ] No large data file(s) added/modified
• [X ] No substantive impact on runtime for full-US reference case
• No substantive impact on folder size for full-US reference case
• No change to process flow (runreeds.py, reeds/core/solve/solve.py)
• No change to code organization
• No change to package requirements (environment.yml or Project.toml)

Did you use LLM tools (chatbot or copilot) in the preparation of this PR? If so, describe how

Tag points of contact here if you would like additional review of the relevant parts of the model