Wildcards

It is easy to run PyPSA-USA for multiple scenarios using the wildcards feature of snakemake. Wildcards generalise a rule to produce all files that follow a regular expression pattern which e.g. defines one particular scenario. One can think of a wildcard as a parameter that shows up in the input/output file names of the Snakefile and thereby determines which rules to run, what data to retrieve and what files to produce.

Note

Detailed explanations of how wildcards work in snakemake can be found in the `relevant section of the documentation.

The {interconnect} wildcard

The {interconnect} wildcard sets the geographc scope of the model run. Models can be run for the western, eastern, texas, or usa grid. The interconnects follow the representation described by Breakthrough Energy.

A visual representation of each {interconnect} is shown below:

The {simpl} wildcard

The {simpl} wildcard specifies number of buses a detailed network model should be pre-clustered to in the rule :mod:simplify_network (before :mod:cluster_network).

The {clusters} wildcard

The {clusters} wildcard specifies the number of buses a detailed network model should be reduced to in the rule :mod:cluster_network. The number of clusters must be lower than the total number of nodes and higher than the number of balancing authoritites.

If an m is placed behind the number of clusters (e.g. 100m), generators are only moved to the clustered buses but not aggregated by carrier; i.e. the clustered bus may have more than one e.g. wind generator.

The {ll} wildcard

The {ll} wildcard specifies what limits on line expansion are set for the optimisation model. It is handled in the rule :mod:prepare_network.

We reccomend using the line volume limit for constraining transission expansion. Use lv (for setting a limit on line volume)

After lv you can specify two type of limits:

   ``opt`` or a float bigger than one (e.g. 1.25).

   (a) If ``opt`` is chosen line expansion is optimised
       according to its capital cost.

   (b) ``v1.25`` will limit the total volume of line expansion
       to 25 % of currently installed capacities weighted by
       individual line lengths; investment costs are neglected.

The {opts} wildcard

The {opts} wildcard is used for electricity-only studies. It triggers optional constraints, which are activated in either :mod:prepare_network or the :mod:solve_network step. It may hold multiple triggers separated by -, i.e. REM-3H contains the REM regional emissions limit trigger and the 3H switch.

The REM, ERM, RPS can be defined using either the reeds zone name ‘p##’, the state code (eg, TX, CA, MT), pypsa-usa interconnect name (western, eastern, texas, usa), or nerc region name.

Warning

TCT Targets can only be used with renewable generators and utility scale batteries in sector studies.

There are currently:

Trigger	Description	Definition	Status
nH; i.e. 2H-6H	Resample the time-resolution by averaging over every n snapshots	prepare_network: average_every_nhours() and its caller)	In active use
nSEG; e.g. 4380SEG	Apply time series segmentation with tsam package to n adjacent snapshots of varying lengths based on capacity factors of varying renewables hydro inflow and load.	prepare_network: apply_time_segmentation()	In active use
REM	Add regional carbon-dioxide emissions limits configured in electricity: regional_Co2_limits. These can be specified in the file linked at electricity: regional_Co2_limits in the configuration. File defaults to repo_data/regional_co2_limits.csv.	prepare_network: add_co2limit() and its caller	In active use
RPS	Add Renewable Portfolio Standard (RPS) constraints to shares of generator production (MWh) per carrier for individual countries. Standards can be set for single carriers or groups of carriers. Each constraint can be designated for a specified planning horizon in multi-period models. Opts and path for portfolio_standards.csv must be defined	solve_network	In active use
ERM	Adds Energy Reserve Margin (ERM) constraints for defined region and planning horizon. Set to a percentage above peak demand level for which generators are credited according to their capacity factor of the peak period. Defaults to 15% reserve margin for all regions if not specified in config.	solve_network	In active use
Ep	Add cost for a carbon-dioxide price configured in costs: emission_prices: co2 to marginal_cost of generators (other emission types listed in network.carriers possible as well)	prepare_network: add_emission_prices() and its caller	In active use
TCT	Add minimum or maximum levels of generator nominal capacity per carrier(s), per region(s), per investment horizon. Opts and path for technology_capacity_targets.csv must be defined	solve_network	In active use
CH4L	Add an overall absolute gas limit. If configured in electricity: gaslimit it is given in MWh thermal, if a float is appended, the overall gaslimit is assumed to be given in TWh thermal (e.g. CH4L200 limits gas dispatch to 200 TWh termal)	prepare_network: add_gaslimit()	In active use

Energy Reserve Margin (ERM) Configuration

The ERM constraint ensures that each region has sufficient firm capacity to meet demand plus a reserve margin at every timestep. Unlike traditional planning reserve margins that only consider peak demand, ERM enforces the constraint across all snapshots.

Key Features:

• Resources must be “energy-backed” - storage devices must have sufficient state of charge to contribute to the reserve

• Supports multiple non-overlapping regions with different reserve margins

• Defaults to 15% reserve margin for all regions if not specified

Configuration:

To enable ERM, add ERM to the opts wildcard in your scenario configuration:

scenario:
  opts: [ERM-3h]  # or [REM-ERM-3h] to combine with other opts

To customize the ERM values per region, add an erm section under electricity in your config file:

electricity:
  erm:
    all: 0.15        # 15% reserve margin for all regions (default)
    # Or specify per region:
    # western: 0.15
    # SPP: 0.12
    # CISO: 0.17

If no erm configuration is provided, a default of {'all': 0.15} (15% reserve margin for all regions) is used.

Valid region identifiers:

• all - applies to all buses in the network

• State codes: TX, CA, MT, etc.

• Interconnect names: western, eastern, texas

• NERC region names

• ReEDS zone names: p1, p2, etc.

The {sector} wildcard

The {sector} wildcard is used to specify what sectors to include. If None is provided, an electrical only study is completed.

Sector	Code	Description	Status
Electricity	E	Electrical sector. Will always be run.	Runs
Natural Gas	G	All sectors added	Development

The {cutout} wildcard

The {cutout} wildcard facilitates running the rule :mod:build_cutout for all cutout configurations specified under atlite: cutouts:. Each cutout is descibed in the form {dataset}_{year}. These cutouts will be stored in a folder specified by {cutout}.

Valid dataset names include: era5 Valid years can be from 1940 to 2022

Note

Data for era5_2019 has been pre-pared for the user and will be automatically downloaded during the workflow. If other years are needed, the user will need to prepaer the cutout themself.