Skip to content

Documentation Fixes - #278

Open
wesleyjcole wants to merge 4 commits into
mainfrom
wjc/doc_fixes
Open

wesleyjcole wants to merge 4 commits into
mainfrom
wjc/doc_fixes

Conversation

@wesleyjcole

Copy link
Copy Markdown
Contributor

Summary

This pull request fixes several small issues with out-of-date documentation, mostly related to switch updates.

Validation, testing, and comparison report(s)

I verified each switch/parameter name change to ensure accuracy. Because this change only impacts documentation, model results are unaffected.

Checklist for author

Details to double-check

  • Charge code provided to reviewers
  • [ ] Included comparison reports for appropriate test cases
  • Documentation updated if necessary

General information to guide review

  • Zero impact on results of default case
  • No large data file(s) added/modified
  • 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

Yes, I used Claude to scan the documentation files to look for inconsistencies. The model documentation updates are my own.

@jvcarag jvcarag left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved: all documentation updates, including PSH-related ones, look good - thanks for catching these!

- Control the iteration between ReEDS and PRAS
- `GSw_PRM_StressThreshold` (default `transgrp_1_EUE_sum`): Regional RA threshold for stress period iteration
- `GSw_PRM_StressThresholdMetrics` (default `NEUE`): RA metric(s) checked during stress period iteration
- `GSw_PRM_StressThreshold{metric}` (default `GSw_PRM_StressThresholdNEUE=transgrp_1`): Regional RA threshold for each metric

@patrickbrown4 patrickbrown4 Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be a bit more explicit:

Suggested change
- `GSw_PRM_StressThreshold{metric}` (default `GSw_PRM_StressThresholdNEUE=transgrp_1`): Regional RA threshold for each metric
- `GSw_PRM_StressThresholdNEUE` (default `transgrp_1`): Region level at which to apply the NEUE threshold and the value of the threshold in parts per million [ppm]
- NEUE is the only RA threshold active by default. Other thresholds that can be activated, in conjunction with the `GSw_PRM_StressThresholdMetrics` switch, are:
- `GSw_PRM_StressThresholdDepth`: Outage depth threshold [MW_EUE/MW_peak_load] (fraction)
- `GSw_PRM_StressThresholdDuration`: Outage duration threshold [hours]
- `GSw_PRM_StressThresholdLOLD`: Loss-of-load-days threshold [event-days/year]
- `GSw_PRM_StressThresholdLOLE`: Loss-of-load-events threshold [events/year]
- `GSw_PRM_StressThresholdLOLH`: Loss-of-load-hours threshold [event-hours/year]

(We'll eventually have a paper on multi-metric RA to cite here)

Comment thread docs/source/user_guide.md
(i.e., if a representative route is 11 miles long and the straight-line distance between its endpoints is 10 miles, giving a squiggliness factor of 1.1, its cost and length are scaled up by 1.3 / 1.1 = 1.18).
1. `GSw_TransHurdle`: Intra-US hurdle rate for interzonal flows, measured in $2004/MWh
1. `GSw_TransHurdleLevel`: Indicate the level of hierarchy.csv between which to apply the hurdle rate specified by `GSw_TransHurdle`. i.e. if set to ‘st’, intra-state flows will have no hurdle rates but inter-state flows will have hurdle rates specified by `GSw_TransHurdle`.
1. `GSw_TransHurdleRate`: Turn on (1) or off (0) hurdle rates for intra-US interzonal flows. The rates [2004$/MWh] are taken by year from the column of `inputs/transmission/cost_hurdle_intra.csv` that matches the selected hierarchy level.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to leave the door open to moving away from 2004$, it'd be nice to remove hardcoded 2004's whenever we come across them. Here, I think the most consistent approach would be to remove the mention of 2004$ and add cost_hurdle_intra.csv to inputs/transmission/dollaryear.csv.

Comment thread docs/source/user_guide.md
- The third argument can be 'NEUE' or 'EUE', specifying which metric to use when selecting stress periods. If set to 'NEUE' the model will add stress periods with the largest **fraction** of dropped load; if set to 'EUE' the model will add stress periods with the largest **absolute MWh** of dropped load.
- The fourth argument can be 'sum' or 'max', specifying whether to add stress periods in order of their daily per-hour max dropped load or by their daily sum of dropped load when selecting stress periods.
- If desired you can provide /-delimited entries like 'transgrp_10_EUE_sum/country_1_EUE_sum', meaning that each transgrp must have ≤10 ppm NEUE and the country overall must have ≤1 ppm NEUE.
- `GSw_PRM_StressThresholdMetrics` and `GSw_PRM_StressThreshold{metric}`: Resource adequacy thresholds used to decide whether to add new stress periods.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about moving this part to the ReEDS2PRAS and PRAS section (and maybe renaming that to Resource adequacy)?

Comment thread docs/source/user_guide.md
- `{level}` can be selected from ['country', 'interconnect', 'nercr', 'transreg', 'transgrp', 'st', 'r'] and specifies the hierarchy level within which to compare RA performance against the threshold.
- `{value}` is a non-negative number in the units of the metric: NEUE [ppm]; LOLD [event-days/year]; LOLE [events/year]; LOLH [event-hours/year]; Depth [maximum hourly EUE as a fraction of peak load]; Duration [hours in the longest outage event].
- If desired you can provide /-delimited entries like `GSw_PRM_StressThresholdNEUE=transgrp_10/country_1`, meaning that each transgrp must have ≤10 ppm NEUE and the country overall must have ≤1 ppm NEUE.
- For each region that exceeds a threshold, `GSw_PRM_StressIncrement` new stress periods are added, ranked by a metric-specific criterion: daily sum of EUE (NEUE), daily maximum hourly EUE (Depth), daily maximum hourly loss-of-load probability (LOLD, LOLE), daily sum of hourly loss-of-load probability (LOLH), or longest EUE events (Duration).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not always days; they could be 5-day weks

Suggested change
- For each region that exceeds a threshold, `GSw_PRM_StressIncrement` new stress periods are added, ranked by a metric-specific criterion: daily sum of EUE (NEUE), daily maximum hourly EUE (Depth), daily maximum hourly loss-of-load probability (LOLD, LOLE), daily sum of hourly loss-of-load probability (LOLH), or longest EUE events (Duration).
- For each region that exceeds the threshold for a given metric, `GSw_PRM_StressIncrement` new stress periods (2 by default) are added for that metric:
- NEUE: Periods with the highest sum of EUE [MWh]
- Depth: Periods with the highest peak hourly EUE [MW]
- Duration: Periods with the longest continuous EUE event [hours]
- LOLD or LOLE: Periods with the highest peak hourly loss-of-load probability [fraction]
- LOLH: Periods with the highest sum of loss-of-load hours [hours]

Comment thread docs/source/user_guide.md
- `GSw_PRM_StressThresholdMetrics` (default `NEUE`) is a /-delimited list of the metrics that can be used. Supported metrics are `NEUE`, `LOLD`, `LOLE`, `LOLH`, `Depth`, and `Duration`.
- Each listed metric reads its threshold from the matching `GSw_PRM_StressThreshold{metric}` switch, formatted as `{level}_{value}`. The default `GSw_PRM_StressThresholdNEUE=transgrp_1` means a threshold of "**1** ppm NEUE in each **transgrp**".
- `{level}` can be selected from ['country', 'interconnect', 'nercr', 'transreg', 'transgrp', 'st', 'r'] and specifies the hierarchy level within which to compare RA performance against the threshold.
- `{value}` is a non-negative number in the units of the metric: NEUE [ppm]; LOLD [event-days/year]; LOLE [events/year]; LOLH [event-hours/year]; Depth [maximum hourly EUE as a fraction of peak load]; Duration [hours in the longest outage event].

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duration is measured in terms of EUE ('outage' could be interpreted to mean a sample-level outage in one of the 100 samples, which is not what we use, so probably better to be explicit)

Suggested change
- `{value}` is a non-negative number in the units of the metric: NEUE [ppm]; LOLD [event-days/year]; LOLE [events/year]; LOLH [event-hours/year]; Depth [maximum hourly EUE as a fraction of peak load]; Duration [hours in the longest outage event].
- `{value}` is a non-negative number in the units of the metric: NEUE [ppm]; LOLD [event-days/year]; LOLE [events/year]; LOLH [event-hours/year]; Depth [maximum hourly EUE as a fraction of peak load]; Duration [hours in the longest EUE event].

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants