Merge pull request #406 from PyPSA/develop

v0.3.0 Candidate

docs/source/about-introduction.md

@@ -1,31 +1,34 @@
 (introduction)=
 # Introduction
 
-```{warning}
-**This model is under active development. If you would like to chat about using the model please don't hesitate to reach out to [email protected] and [email protected] for support**
-```
+PyPSA-USA is an open-source tool that enables you to model and simulate the United States energy system with flexibility.
 
-PyPSA-USA is an open-source energy system dataset of the United States energy system with continental US coverage.
+PyPSA-USA offers a versatile toolkit that allows you to customize the **data** for your energy system model with ease. Through a simple configuration file, you can control the spatial, temporal, and operational resolution of your model. Access a range of cleaned and prepared historical and forecasted data to build a model tailored to your needs.
 
-PyPSA-USA provides you with a toolkit to customize the **data** of energy system model with ease. Through configuration file you can control the spatial, temporal, and operational resolution of your energy system model with access to cleaned and prepared historical and forecasted data. This means, you can build a model of **ERCOT, WECC, or the Eastern interconnection**, where the transmission network is clustered to **N# of user defined nodes**, which can respect the boundaries of **balancing areas, states, or REeDs GIS Shapes**, using **historical EIA-930 demand data years 2018-2023** OR **NREL EFS forcasted demand [2030, 2040, 2050]**, with **historical daily/monthly fuel prices from ISOs/EIA [choice of year]**, AND imported capital cost projections from the **NREL Annual Technology Baseline**.
+Whether you’re focusing on **ERCOT, WECC, or the Eastern Interconnection**, PyPSA-USA gives you the flexibility to:
+- Choose between multiple transmission networks.
+- Cluster the nodal network a user-defined number of nodes, respecting county lines, balancing areas, states, NERC region boundaries.
+- Utilize **historical EIA-930 demand data** (2018-2023) or **NREL EFS forecasted demand** (2030, 2040, 2050).
+- Incorporate **historical daily/monthly fuel prices** from ISOs/EIA for your chosen year.
+- Import cost projections from the **NREL Annual Technology Baseline** and **Annual Energy Outlook**.
 
-You can create data model- and export to use in your own homebrewed optimization model via csv tables, or xarray netCDF model.
+You can create and export data models for use in your own optimization models via CSV tables or xarray netCDF formats.
 
-Beyond creating a data model, PyPSA-USA also provides an interface for running capacity expansion planning and operational simulation models with DC power flow with the Python for Power System Analysis package. You can run expansion planning exercises which integrate regional and national policy constraints like RPS standards, emissions standards, PRMs, and more.
+PyPSA-USA also provides an interface for running capacity expansion planning and operational simulation models with the Python for Power System Analysis (pypsa) package. You can run expansion planning exercises which integrate regional and national policy constraints like RPS standards, emissions standards, PRMs, and more.
 
-PyPSA-USA builds on and leverages the work of [PyPSA-EUR](https://pypsa-eur.readthedocs.io/en/latest/index.html) developed by TU Berlin. PyPSA-USA is actively developed by the [INES Research Group](https://ines.stanford.edu) at Stanford University and the [ΔE+ Research Group](https://www.sfu.ca/see/research/delta-e.html) at Simon Fraser University.
+PyPSA-USA builds on and leverages the work of [PyPSA-EUR](https://pypsa-eur.readthedocs.io/en/latest/index.html) developed by TU Berlin. It is actively developed by the [INES Research Group](https://ines.stanford.edu) at Stanford University and the [ΔE+ Research Group](https://www.sfu.ca/see/research/delta-e.html) at Simon Fraser University. We welcome contributions and collaborations from the community- please don't hesitate to reach out!
 
 (workflow)=
 ## Workflow
 
+The diagram below illustrates the workflow of PyPSA-USA, highlighting how the data flows through the model scripts.
+
 ![pypsa-usa workflow](https://github.com/PyPSA/pypsa-usa/blob/master/workflow/repo_data/dag.jpg?raw=true)
 
 (folder-structure)=
 ## Folder Structure
 
-The project is organized based on the folder structure below. The workflow folder contains all data and scripts neccesary to run the pypsa-usa model. After the first time you run the snakemake file, your directory will be built and populated with the associated data. Because most of the files are too large to store on github, we pull data from various sources into the `data` folder. The `repo_data` folder contains smaller files suitable for github. The resources folder contains intermediate files built by snakemake rules through the workflow. You'll see sub-folders created for each interconnection you run the model with.
-
-The envs folder contains the conda env yaml files neccesary to build your mamba/conda environment. The scripts folder contains the individual python scripts that are referenced in the Snakefile rules.
+PyPSA-USA is organized to facilitate easy navigation and efficient execution. Below is the folder structure of the project. Each folder serves a specific purpose, from environment setup to data processing and storage. After running the Snakemake file for the first time, your directory will be built and populated with the necessary data files.
 
 ```bash
 ├── .gitignore
@@ -59,3 +62,8 @@ The envs folder contains the conda env yaml files neccesary to build your mamba/
 |   │   └── example_data.csv
 |   └── Snakefile
 ```
+
+
+```{warning}
+**This model is under active development. If you need assistance or would like to discuss using the model, please reach out to [email protected] and [email protected].**
+```

docs/source/conf.py

@@ -7,7 +7,7 @@
 
 
 project = "pypsa-usa"
-copyright = "2023, Kamran Tehranchi, Trevor Barnes"
+copyright = "2024, Kamran Tehranchi, Trevor Barnes"
 author = "Kamran Tehranchi, Trevor Barnes"
 
 # -- General configuration ---------------------------------------------------
@@ -37,6 +37,7 @@
     #'rinoh.frontend.sphinx',
     "sphinx.ext.imgconverter",  # for SVG conversion
 ]
+myst_heading_anchors = 3
 
 templates_path = ["_templates"]
 exclude_patterns = []

docs/source/config-configuration.md

@@ -208,42 +208,7 @@ See [here](./config-co2-base.md) for information on interconnect level base emis
 ``` -->
 
 ```{warning}
-Sector coupling studies are all under active development
-```
-
-```yaml
-sector:
-  co2_sequestration_potential: 0
-  natural_gas:
-    allow_imports_exports: true # false to be implemented
-    cyclic_storage: false
-  heating:
-    heat_pump_sink_T: 55.
-  demand:
-    profile:
-      residential: eulp # efs, eulp
-      commercial: eulp # efs, eulp
-      transport: efs # efs
-      industry: efs # efs
-    scale:
-      residential: aeo # efs, aeo
-      commercial: aeo # efs, aeo
-      transport: aeo # efs, aeo
-      industry: aeo # efs, aeo
-    disaggregation:
-      residential: pop # pop
-      commercial: pop # pop
-      transport: pop # pop
-      industry: pop # pop
-    scenarios:
-      aeo: reference
-```
-
-```{eval-rst}
-.. csv-table::
-   :header-rows: 1
-   :widths: 22,7,22,33
-   :file: configtables/sector.csv
+Sector coupling studies are all under active development. More info to come!
 ```
 
 

docs/source/config-sectors.md

@@ -1,16 +1,6 @@
 (sectors)=
 # Sectors
 
-```{note}
-More information to come!
-```
-
-(natural-gas-sector)=
-## Natural Gas
-
-Below is a schematic showing the representation of the natural gas network.
-
-```{eval-rst}
-.. image:: _static/sectors/natural-gas.png
-    :scale: 20 %
+```{warning}
+Sector coupling studies are all under active development. More info to come!
 ```

docs/source/config-wildcards.md

@@ -26,12 +26,12 @@ A visual representation of each `{interconnect}` is shown below:
     :scale: 100 %
 ```
 
-<!-- (simpl)=
-## The ``{simpl}`` wildcard -->
+(simpl)=
+## The ``{simpl}`` wildcard
 
-<!-- The ``{simpl}`` wildcard specifies number of buses a detailed
+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`). -->
+:mod:`simplify_network` (before :mod:`cluster_network`).
 
 (clusters)=
 ## The `{clusters}` wildcard
@@ -105,11 +105,7 @@ is provided, an electrical only study is completed.
 | Sector      | Code | Description                                    | Status      |
 |-------------|------|------------------------------------------------|-------------|
 | Electricity | E    | Electrical sector. Will always be run.         | Runs        |
-| Natural Gas | G    | Natural gas sector                             | Development |
-| Heating     | H    | Heating and Cooling                            | Development |
-| Industry    | I    | Industrial Processes                           | Development |
-| Transport   | T    | Transportation sector                          | Development |
-| Methane     | M    | Methane tracking. Requires natural gas sector. | Future      |
+| Natural Gas | G    | All sectors added                              | Development |
 
 (scope)=
 ## The `{scope}` wildcard
@@ -121,7 +117,6 @@ Sector coupling studies are all under active development
 Takes values `residential`, `urban`, `total`. Used in sector coupling studies to define
 population breakdown.
 
-
 (cutout_wc)=
 ## The `{cutout}` wildcard
 

docs/source/configtables/electricity.csv

@@ -7,7 +7,7 @@ co2limit,:math:`t_{CO_2-eq}/a`,float,Cap on total annual system carbon dioxide e
 co2base,:math:`t_{CO_2-eq}/a`,float,Reference value of total annual system carbon dioxide emissions if relative emission reduction target is specified in ``{opts}`` wildcard.
 retirement, --,One of ``economic`` or ``technical``,"Sets the retirement method for converntional generators. If ``technical`` all generators ``p_nom_min`` are set to ``p_nom`` to prevent selling off of the asset. Retirements are then tracked in post-proccessing. If ``economic`` existing plants have their ``p_nom_min`` set as ``0``,  ``p_nom_max`` set to ``p_nom``,  and capital costs set to fixed costs. Generators with ``p_nom`` are then added to handle capacity expansion."""
 ,,,
-operational_reserve:,,,Settings for reserve requirements following `GenX <https://genxproject.github.io/GenX/dev/core/#Reserves>`_
+operational_reserve:,,,Settings for reserve requirements following `GenX <https://genxproject.github.io/GenX.jl/stable/Model_Reference/core/#Operational-Reserves>`_
 --activate,bool,true or false,Whether to take operational reserve requirements into account during optimisation
 --epsilon_load,--,float,share of total load
 --epsilon_vres,--,float,share of total renewable supply

docs/source/configtables/onwind.csv

@@ -9,6 +9,6 @@ grid codes,--,Any subset of the Copornicus Land Cover code list (see assumptions
 distance,m,float,Distance to keep from areas specified in ``distance_grid_codes``
 distance_grid_codes,--,Any subset of the Copornicus Land Cover code list (see assumptions).,Specifies areas according to Land Cover codes which are generally eligible for wind turbine placement.
 natura,bool,"{true, false}",Switch to exclude Protected Planet natural protection areas. Area is excluded if ``true``.
-potential,--,"One of {'simple', 'conservative'}",Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`
+potential,--,"One of {'simple', 'conservative'}",Method to compute the maximal installable potential for a node
 clip_p_max_pu,p.u.,float,To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
 correction_factor,--,float,Correction factor for capacity factor time series.

docs/source/configtables/scenario.csv

@@ -1,3 +1,3 @@
 ,Unit,Values,Description
 planning_horizons,int,"(2018-2023, 2030, 2040, 2050)","Specifies the year of demand data to use. Historical values will use EIA930 data, Future years will use NREL EFS data. Specify multiple planning horizons to build a multi-horizon model."
-foresight,str,"perfect", "Specifies foresight option for multi-horizon optimization. Currently only "perfect" foresight is supported. Myopic foresight will be added in the future."
+foresight,str,perfect,Specifies foresight option for multi-horizon optimization. Currently only perfect foresight is supported. Myopic foresight will be added in the future.

docs/source/configtables/solar.csv

@@ -12,6 +12,6 @@ capacity_per_sqkm,:math:`MW/km^2`,float,Allowable density of solar panel placeme
 correction_factor,--,float,A correction factor for the capacity factor (availability) time series.
 corine,--,Any subset of the Copornicus Land Cover code list (see assumptions).,Specifies areas according to Land Cover codes which are generally eligible for wind turbine placement.
 natura,bool,"{true, false}",Switch to exclude Protected Planet natural protection areas. Area is excluded if ``true``.
-potential,--,"One of {'simple', 'conservative'}",Method to compute the maximal installable potential for a node; confer :ref:`renewableprofiles`
+potential,--,"One of {'simple', 'conservative'}",Method to compute the maximal installable potential for a node
 clip_p_max_pu,p.u.,float,To avoid too small values in the renewables` per-unit availability time series values below this threshold are set to zero.
 excluder_resolution,m,float,Resolution on which to perform geographical elibility analysis.

docs/source/data-costs.md

@@ -0,0 +1,36 @@
+(data-costs)=
+# Costs
+## Costs and Candidate Resources
+
+ In PyPSA-USA, candidate resource forecasted capital and operating costs are defined by the NREL Annual Technology Baseline (ATB) accessed through the PUDL project.
+
+### Implemented Candidate Resources
+
+PyPSA-USA includes a variety of candidate resources, each with specific parameters:
+
+- **Coal Plants**: With and without Carbon Capture Storage (CCS) at 95% and 99% capture rates.
+- **Natural Gas**: Combustion Turbines and Combined Cycle plants, with and without 95% CCS.
+- **Nuclear Reactors**: Small and Large Nuclear Reactors
+- **Renewable Energy**: Utility-scale onshore wind, fixed-bottom and floating offshore wind, utility-scale solar.
+- **Energy Storage**: 2-10 hour Battery Energy Storage Systems (BESS).
+- **Pumped Hydro Storage (PHS)**: A method of storing energy by moving water between reservoirs at different elevations.
+
+### Cost Parameters
+
+The model uses forecasted data from the NREL ATB for:
+
+- **Capital Expenditure (CapEx)**
+- **Operations and Maintenance (O&M) Costs**
+- **Capital Recovery Periods**
+- **Fuel Efficiencies**
+- **Weighted Average Cost of Capital (WACC)**
+
+To reflect regional differences, capital costs are adjusted using [EIA state-level CapEx multipliers](https://www.eia.gov/analysis/studies/powerplants/capitalcost/pdf/capital_cost_AEO2020.pdf).
+
+## Fuel Costs
+
+PyPSA-USA integrates fuel costs that varry across spatial scopes and temporal scales. For more information, see [here](./data-generators.md#fuel-costs)
+
+## Sector Costs
+
+Running sector studies will use the same power system costs as electrical only studies. Costs specific to each sector can be found in the [service sector](./data-services.md), [transportation sector](./data-transportation.md), and [industrial sector](./data-industrial.md) pages accordingly.

docs/source/data-demand.md

@@ -0,0 +1,47 @@
+(data-demand)=
+# Electricity Demand
+
+PyPSA-USA offers access to both exogenously defined historical and future forecasted electrical demand data.
+
+## Historical Demand
+
+Historical demand data is imported from the EIA930 via the [GridEmissions](https://github.com/jdechalendar/gridemissions) tool, covering the years 2018-2023. This data is defined at the balancing area region level.
+
+## Forecasted Demand
+
+Forecasted demand is sourced from the NREL Electrification Futures Study (EFS), providing hourly demand forecasts for the years 2030, 2040, and 2050. The EFS data includes forecasts for varying levels and speeds of electrification across sectorally specified residential, commercial, and industrial end-uses. The non-sector coupled setting in pypsa-usa aggregates these demands to one load per node.
+
+The EFS also provides electrification cases, with reference, medium, and high electrification cases, with slow, moderate, and rapid speeds. These scenarios can be controlled via the configuration `demand: scenario: efs_case: / efs_speed:`.
+
+## Demand Disaggregation
+
+Electrical load is disaggregated based on population, folling the implementation in the nodal network dataset. See the paper on the [nodal network](./data-transmission.md#tamu-synthetic-nodal-network) for more information on specifics of load disaggregation.
+
+## Usage
+
+The user determines weather to use historical demand years via a combination of the planning horizons setting, and the electricity demand setting. If conducting historical simulations, the user must select a planning horizon in the past (2018-2023), and set `profile: eia`.
+
+If conducting forward-looking planning cases the user must set future planning_horizon year (2025- 2050) and set `profile: efs`.
+
+For the years between 2030, 2040, and 2050, PyPSA-USA implements a scaling factor that interpolates between future years or scales historical demand using forecasts from the Annual Energy Outlook (AEO).
+
+```
+scenario:
+  planning_horizons: [] # Historical or Future Year(s)
+
+electricity:
+  demand:
+    profile: efs # efs, eia
+    scenario:
+      efs_case: reference # reference, medium, high
+      efs_speed: moderate # slow, moderate, rapid
+      aeo: reference
+```
+
+### Data
+```{eval-rst}
+.. csv-table::
+   :header-rows: 1
+   :widths: 22,22,22,22
+   :file: datatables/demand.csv
+```