Merge pull request #445 from ktehranchi/kt/tx_county_cost_fix

docs updates & multiple fixes

Author: ktehranchi

docs/source/_static/networks/FERC1000.png

@@ -9,7 +9,7 @@ PyPSA-USA allows for flexible configuration of the spatial scope of your energy
 
 ### Example: Modeling California
 
-To create a model that includes only California, you can specify the relevant ReEDS zone IDs (p8-11) as shown below. This will limit the spatial scope to the specified regions within California.
+To create a model that includes only California, you can specify the relevant ReEDS zone IDs (p8-11) as shown below. This will limit the spatial scope to the specified regions within California. Your interconnect could be set to `western` or `usa`.
 
 ```yaml
 model_topology:
@@ -19,48 +19,62 @@ model_topology:
 
 Alternatively, you can use the reeds_state: 'CA' option to achieve the same result by specifying the entire state.
 
-<!-- ### Custom Aggregation Example
-If you'd like to create custom nodal aggregations, you can use the model_topology: aggregate: option. For instance, to cluster Arizona, Nevada, and New Mexico into a single region (WECC_SW), you would configure the model as follows:
+## Configuring Resource Resolution
+PyPSA-USA allows you to independently configure the resolution of resource zones from the transmission network. You can control this using the simpl and clusters parameters in the configuration file.
 
+For example, if you want a transmission network with 10 nodes and a resource model with 100 nodes, you would configure it as follows:
 
 ```yaml
-model_topology:
-   aggregate:
-      reeds_state:
-         WECC_SW : ['AZ', 'NV', 'NM']
+scenario:
+   clusters: [10m]
+   simpl: [100]
 ```
 
-This configuration will dissolve the borders between these states, effectively creating a copper-plate network where resources can be clustered and shared across the region. -->
-
-## Configuring Spatial Resolution
+This setup results in a model with 10 transmission nodes and 100 distinct resource zones, allowing for more granular modeling of renewable resource distribution while keeping the transmission network simplified.
 
-PyPSA-USA gives you control over the spatial resolution of your transmission and resource networks, allowing for detailed or aggregated views depending on your modeling needs.
+## Configuring Transmission Resolution
 
 ### Transmission Network Selection
-You can specify the transmission network you want to use by setting the model_topology: transmission_network: option. There are two available options:
+You can specify the transmission network you want to use by setting the `model_topology: transmission_network:` option. There are two available options:
 
+- 'reeds': The ReEDS NARIS networks.
 - 'tamu': The synthetic BE-TAMU nodal network.
-- 'reeds': The ReEDS zonal network.
-
-### Configuring Node Clusters
-When using the ReEDS network, you need to specify the number of clusters (nodes) for your modeled interconnection. The number of nodes for each zone is **detailed in the table below**. If you're working with custom configurations, PyPSA-USA will notify you during the cluster_network stage, indicating the correct number of nodes to set in the clusters configuration.
 
-### Resource Group Resolution
-PyPSA-USA allows you to independently configure the resolution of resource zones from the transmission network. You can control this using the simpl and clusters parameters in the configuration file.
+When selecting between the three ReEDS NARIS networks, you will need to also specify the `model_topology: topological_boundaries:`. Currently you can set either `county` or `reeds_zone`. To use the FERC 1000 regions, you will need to use the custom network topologies described in the example below.
 
-For example, if you want a transmission network with 10 nodes and a resource model with 100 nodes, you would configure it as follows:
+### Transmission Network Resolution
 
-```yaml
-scenario:
-   clusters: [10m]
-   simpl: [100]
-```
-This setup results in a model with 10 transmission nodes and 100 distinct resource zones, allowing for more granular modeling of renewable resource distribution while keeping the transmission network simplified.
+IF you are using the TAMU/BE network, you can flexibly set an arbitrary number of clusters between the min and max number of nodes. If using a ReEDS NARIS network, you need to specify the minimum number of clusters (nodes) for your modeled interconnection. The number of nodes for each zone is **detailed in the table below**.
 
+If you're working with custom configurations, PyPSA-USA will notify you during the cluster_network stage, indicating the correct number of nodes to set in the clusters configuration.
 
 ```{eval-rst}
 .. csv-table::
    :header-rows: 1
    :widths: 22,22,33
    :file: datatables/transmission_nodes.csv
 ```
+
+#### Example: Meshed ReEDS NARIS WECC Topology
+
+If you would like to mesh the three ReEDS NARIS networks you can do so by using the `model_topology: aggregate:` option. For instance, to create a model where California is represented at a county level resolution, but Non-CA WECC areas are represented at the FERC 1000 level, you would configure the model as follows:
+
+
+```yaml
+scenario:
+   interconnect: [western]
+   clusters: [87]
+   simpl: [380] # can be set differently based on number of resource zones you'd like to keep
+
+
+model_topology:
+  transmission_network: 'reeds'
+  topological_boundaries: 'county'
+  interface_transmission_limits: false
+  include:
+    # nothing specified here since we are modeling the entire WECC
+  aggregate:
+    trans_grp: ['NorthernGrid_South', 'NorthernGrid_West', 'NorthernGrid_East', 'WestConnect_North','WestConnect_South']
+```
+
+This configuration will copper plate the Non-CA regions listed under `trans_grp`, effectively creating a copper-plate network where resources can be clustered and shared across the region. Using these custom aggregation requires information on the region memberships which you can find in `workflow/repo_data/ReEDS_Constraints/membership.csv`.

docs/source/config-spatial.md

@@ -48,35 +48,28 @@ The `{ll}` wildcard specifies what limits on
 line expansion are set for the optimisation model.
 It is handled in the rule :mod:`prepare_network`.
 
-The wildcard, in general, consists of two parts:
+We reccomend using the line volume limit for constraining
+transission expansion. Use ``lv`` (for setting a limit on line volume)
 
-    1. The first part can be
-       ``v`` (for setting a limit on line volume) or
-       ``c`` (for setting a limit on line cost)
+After ``lv`` you can specify two type of limits:
 
-    2. The second part can be
        ``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
-           (where the choice ``v`` only considers overhead costs for HVDC transmission lines, while
-           ``c`` uses more accurate costs distinguishing between
-           overhead and underwater sections and including inverter pairs).
+           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.
 
-       (c) ``c1.25`` will allow to build a transmission network that
-           costs no more than 25 % more than the current system.
 
 (opts)=
 ## 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. `Co2L-3H` contains the `Co2L` trigger and the `3H` switch.
+i.e. `REM-3H` contains the `REM` regional emissions limit trigger and the `3H` switch.
 
 The REM, SAFER, 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),

docs/source/config-wildcards.md

@@ -9,4 +9,4 @@ feature,str," {'solar+onwind-time', 'solar+onwind-cap', 'solar-time', 'solar-cap
 aggregation_strategies:,,,
 table --> {key},str,"{'mean','max','min',etc}","Specifiy the method of aggregating fields within the generators, buses tables. "
 focus_weights:,,,
-region_name',float,,Specify the proportion of nodes to be attributed to a given zone in the form (California: 0.5) for half of all nodes to be located in California
+region_name',float,,Specify the proportion of nodes to be attributed to a given zone in the form (California: 0.5) for half of all nodes to be located in California. Only used with TAMU Network

docs/source/configtables/clustering.csv

@@ -1,17 +1,13 @@
 ,Unit,Values,Description
 conventional_carriers,--,"Any subset of {nuclear, oil, OCGT, CCGT, coal, geothermal, biomass}","List of conventional power plants to include in the model from ``resources/powerplants.csv``. If an included carrier is also listed in ``extendable_carriers``, the capacity is taken as a lower bound."
 renewable_carriers,--,"Any subset of {solar, onwind, offwind-ac, offwind-dc, hydro}",List of renewable generators to include in the model.
-voltage_simplified,kV,int,Voltage level to simplify network to in rule ``simplify_network``
-gaslimit,MWhth,float or false,Global gas usage limit (Set False for development)
-co2limit,:math:`t_{CO_2-eq}/a`,float,Cap on total annual system carbon dioxide emissions
-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.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
---contingency,MW,float,fixed reserve capacity
+#NAME?,bool,true or false,Whether to take operational reserve requirements into account during optimisation
+#NAME?,--,float,share of total load
+#NAME?,--,float,share of total renewable supply
+#NAME?,MW,float,fixed reserve capacity
 ,,,
 max_hours:,,,
 battery,h,float,Maximum state of charge capacity of the battery in terms of hours at full output capacity ``p_nom``. Cf. `PyPSA documentation <https://pypsa.readthedocs.io/en/latest/components.html#storage-unit>`_.
@@ -23,14 +19,14 @@ Store,--,Any subset of {``battery``},Adds extendable storage units (battery and/
 Links,--,Any subset of {},Adds extendable linksat every connection where there are lines or HVDC links without capacity limits and with zero initial capacity. Hydrogen pipelines require hydrogen storage to be modelled as ``Store``.
 ,,,
 demand:,,,
---profile,--,"One of {``efs``, ``eia``}",Datasource for electrical load data. ``EFS`` pulls future state level electrical demand data. ``EIA`` pulls historical balancing level electrical demand dataa.
---scale,--,"One of {``efs``, ``aeo``}, or a float",(UNDER DEVELOPMENT) Used to scale the demand profile data. ``AEO`` will scale according to demand projections from the Annual Energy Outlook. ``EFS`` will scale according to growth rates from the Electrification Futures Study. Or can sclae according to a user defined value.
---disaggregation,--,One of {``pop``},Method to dissagreagate load data. ``pop`` will dissagregate based on population from Breakthrough Energy.
+#NAME?,--,"One of {``efs``, ``eia``}",Datasource for electrical load data. ``EFS`` pulls future state level electrical demand data. ``EIA`` pulls historical balancing level electrical demand dataa.
+#NAME?,--,"One of {``efs``, ``aeo``}, or a float",(UNDER DEVELOPMENT) Used to scale the demand profile data. ``AEO`` will scale according to demand projections from the Annual Energy Outlook. ``EFS`` will scale according to growth rates from the Electrification Futures Study. Or can sclae according to a user defined value.
+#NAME?,--,One of {``pop``},Method to dissagreagate load data. ``pop`` will dissagregate based on population from Breakthrough Energy.
 scenario:,,,
---efs_case,--,"One of {``reference``, ``medium``, ``high``}",(UNDER DEVELOPMENT) Extracts EFS data according to level of adoption
---efs_speed,--,"One of {``slow``, ``moderate``, ``fast``}",(UNDER DEVELOPMENT) Extracts EFS data according to speed of electrification
---aeo,--,One of the AEO scenarios `here <https://www.eia.gov/outlooks/aeo/data/browser/>`_,(UNDER DEVELOPMENT) Scales future demand according to the AEO scenario
+#NAME?,--,"One of {``reference``, ``medium``, ``high``}",(UNDER DEVELOPMENT) Extracts EFS data according to level of adoption
+#NAME?,--,"One of {``slow``, ``moderate``, ``fast``}",(UNDER DEVELOPMENT) Extracts EFS data according to speed of electrification
+#NAME?,--,One of the AEO scenarios `here <https://www.eia.gov/outlooks/aeo/data/browser/>`_,(UNDER DEVELOPMENT) Scales future demand according to the AEO scenario
 ,,,
 autarky,,,
---enable,bool,``true`` or ``false``,Require each node to be autarkic by removing all lines and links.
---by_country,bool,``true`` or ``false``,Require each region to be autarkic by removing all cross-border lines and links. ``electricity: autarky`` must be enabled.
+#NAME?,bool,``true`` or ``false``,Require each node to be autarkic by removing all lines and links.
+#NAME?,bool,``true`` or ``false``,Require each region to be autarkic by removing all cross-border lines and links. ``electricity: autarky`` must be enabled.

docs/source/configtables/electricity.csv

@@ -3,5 +3,4 @@ types,--,"Values should specify a `line type in PyPSA <https://pypsa.readthedocs
 s_max_pu,--,"Value in [0.,1.]",Correction factor for line capacities (`s_nom`) to approximate :math:`N-1` security and reserve capacity for reactive power flows
 s_nom_max,MW,float,Global upper limit for the maximum capacity of each extendable line.
 max_extension,MW,float,Upper limit for the extended capacity of each extendable line.
-length_factor,--,float,Correction factor to account for the fact that buses are *not* connected by lines through air-line distance.
-interface_transmission_limits, --, true or false, Activate the Interface Transmission Limits (ITL) zones limits.
+length_factor,--,float,Correction factor to account for the fact that buses are *not* connected by lines through air-line distance. Only used in TAMU network.

docs/source/configtables/lines.csv

@@ -1,15 +1,10 @@
 Trigger, Description, Definition, Status
 ``nH``; i.e. ``2H``-``6H``, Resample the time-resolution by averaging over every ``n`` snapshots, ``prepare_network``: `average_every_nhours() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L110>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L146>`__), In active use
 ``nSEG``; e.g. ``4380SEG``, Apply time series segmentation with `tsam <https://tsam.readthedocs.io/en/latest/index.html>`_ 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
-``Co2L``, Add an overall absolute carbon-dioxide emissions limit configured in ``electricity: co2limit``. If a float is appended an overall emission limit relative to the emission level given in ``electricity: co2base`` is added (e.g. ``Co2L0.05`` limits emissisions to 5% of what is given in ``electricity: co2base``), ``prepare_network``: `add_co2limit() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L19>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L154>`__, 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() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L19>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L154>`__, 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
 ``SAFE``, Add a capacity reserve margin of a certain fraction above the peak demand to which renewable generators and storage do *not* contribute. Ignores network., ``solve_network`` `add_opts_constraints() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/solve_network.py#L73>`__,In active use
 ``SAFER``,Adds Regional Capacity Reserve Margin (SAFE) Constraints for defined region- set to a percentage above peak demand level for which renewables and storage do not contribute to. , ``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() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L24>`_ and its `caller <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/prepare_network.py#L158>`__, In active use
 ``CCL``,Add minimum or maximum levels of generator nominal capacity per carrier for individual countries. Each constraint can be designated for a specified planning horizon in multi-period models. Opts and path for agg_p_nom_minmax.csv must be defined, ``solve_network``, In active use
-``EQ``," ""Require each country or node to on average produce a minimal share of its total consumption itself. Example: ``EQ0.5c`` demands each country to produce on average at least 50% of its consumption; ``EQ0.5`` demands each node to produce on average at least 50% of its consumption.""", ``solve_network``, In active use
-``ATK``," ""Require each node to be autarkic. Example: ``ATK`` removes all lines and links. ``ATKc`` removes all cross-border lines and links.""", ``prepare_network``, In active use
-``BAU``, Add a per-``carrier`` minimal overall capacity; i.e. at least ``40GW`` of ``OCGT`` in Europe; configured in ``electricity: BAU_mincapacities``, ``solve_network``: `add_opts_constraints() <https://github.com/PyPSA/pypsa-eur/blob/6b964540ed39d44079cdabddee8333f486d0cd63/scripts/solve_network.py#L66>`__, Untested
-``carrier+{c|p|m}factor``,"Alter the capital cost (``c``), installable potential (``p``) or marginal costs (``m``) of a carrier by a factor. Example: ``solar+c0.5`` reduces the capital cost of solar to 50\% of original values.", ``prepare_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