[patrickbrown4]

Summary

This PR addresses #35 (and a few other conditions that may surprise the user) by raising a prompt or error in the following conditions:

1. The run would use too few representative periods
   • This situation occurs if using GSw_HourlyClusterAlgorithm = optimized and a small number of the levels specified by GSw_HourlyClusterRegionLevel
2. Model zones would be islanded
   • This situation occurs, for example, when running with GSw_Region = transreg/PJM, which unrealistically islands the PJM parts of IL and MI
3. The resource adequacy (RA) thresholds are not met even after the final ReEDS/PRAS iteration
   • This check has to wait for stress_periods.py and is bypassed if debug > 0

Note that the Pacific test case will fail the first check! To avoid the prompt for small test cases, add the -f or --force flag when starting your run. Single-character flags can be combined with other flags. Any of the following would work:

python runreeds.py -b v20261002_mainM0 -c test -s Pacific -f
python runreeds.py -b v20261002_mainM0 -c test -s Pacific --force
python runreeds.py -b v20261002_mainM0 -c test -fs Pacific

Or you could add the following alias to your ~/.bashrc (on kestrel) or ~/.bash_profile (local) file:

alias testreeds='python runreeds.py -f'

and then

testreeds -b v20261002_mainM0 -c test -s Pacific

But you should be careful not to get in the habit of bypassing the check when doing actual analysis.

Technical details

Implementation notes

• The number of representative periods that counts as "too few" is debatable (happy to discuss if interested), but the amount you get when running an ISO with default settings (which are designed for the contiguous US) is definitely too small. I went with 24 (2 per month). But if you're analyzing ISO-size regions with otherwise-default settings, I would recommend just including all days via the following settings:
  • GSw_HourlyClusterAlgorithm = 'hierarchical'
  • GSw_HourlyNumClusters = 365

Additional changes

• cases_test.csv: Changed Pacific_2020 (which is mostly covered by other tests) to NY_365 to provide an example of running a region with 365 days
• Moved check_compatibility() from runreeds.py to reeds.checks to keep all the checks together
• Added a reminder to the PR template to update the switch checks when switches are added or modified

Issues resolved

#35

Relevant sources or documentation

The 'optimized' representative day selection + weighting method, and the reasons why it produces a small number of periods when running a small number of zones, are described in https://doi.org/10.1016/j.energy.2025.135830.

Validation, testing, and comparison report(s)

Zero change for USA_defaults: results-v20261030_mainK0_USA_defaults,v20261020_warnK0_USA_defaults.pptx

Checklist for author

Details to double-check

• Charge code provided to reviewers
• Included comparison reports for appropriate test cases
• Code formatting standardized
• Reusable functions used where possible instead of copy/pasted code

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

No

[bsergi]

above it says "needs ~33 days"--with 11 regions and 3 features is it correct to say that the max days is 33 days but that it could come up with fewer (presumably if there is some overlap in days across regions/features)?

[patrickbrown4]

This is just meant as an empirical rule of thumb based on what I've observed across many runs. It's not always the absolute max; for example, if looking at 1 region and 1 feature, you need 2 days to minimize the error (one on either side of the average, weighted to reproduce the average). I haven't tried to derive the absolute max, but the previous sentence says "there will be a maximum number of days it needs to reproduce the distribution".

[bsergi]

What do you think about including a conditional here that also allows proceeding with a warning if numperiods >= GSw_HourlyNumClusters? That would still prevent people from inadvertently running with too few representative days but also allow people to run specific use cases with fewer than 24 days without neededing to force.

[patrickbrown4]

I guess I'm on the fence. I generally worry that warnings are too easy to miss, and I'm not sure if all users know that 4 periods (for example) is absolutely not enough for analysis. I guess I feel like the extra keystoke when intentionally testing low numbers of periods is worth it to catch problematic settings earlier in the process for analysis users. But it's probably worth more discussion.

[bsergi]

Is the exceptions list just to deal with the WECC and EI parts of TX?

[patrickbrown4]

No, it's because TX showed up as an island when using the z48 zone set. But that's just because I forgot to include B2B connections in the determination of islands. I've added those so we can get rid of ISLAND_EXCEPTIONS.

[bsergi]

Long-term I could see developing some ITL estimates for an islanded PJM, but I suppose that is only needed for people that might be running it. My recent tests with an islanded PJM have involved taking the entire state with any PJM region which has helped avoid this issue.

[patrickbrown4]

We'd need to modify the ITL definition to support it since no lines directly connect the separate regions; the alternative would be to add them to hvdc_planned-baseline.csv (which, even though it has hvdc in the name, should allow AC additions too). But yeah I agree, I would generally recommend modeling full interconnections for analysis since there's so much trade between regions.