Merge branch 'martavp:improve-doc' into improve-doc

doc/index.rst

@@ -120,6 +120,7 @@ Documentation
 
 * :doc:`spatial_resolution`
 * :doc:`supply_demand`
+* :doc:`technology_assumptions`
 
 .. toctree::
    :hidden:
@@ -128,7 +129,7 @@ Documentation
 
    spatial_resolution
    supply_demand
-
+   technology_assumptions
 
 **Foresight options**
 
@@ -143,6 +144,7 @@ Documentation
 
    overnight
    myopic
+   perfect
 
 **References**
 

doc/spatial_resolution.rst

@@ -4,55 +4,44 @@
 Spatial resolution
 ##########################################
 
-The default nodal resolution of the model follows the electricity
-generation and transmission model `PyPSA-Eur
-<https://github.com/PyPSA/pypsa-eur>`_, which clusters down the
-electricity transmission substations in each European country based on
-the k-means algorithm. This gives nodes which correspond to major load
-and generation centres (typically cities).
+The default nodal resolution of the model follows the electricity generation and transmission model `PyPSA-Eur <https://github.com/PyPSA/pypsa-eur>`_ , which clusters down the electricity transmission substations in each European country based on the k-means algorithm (See `cluster_network <https://pypsa-eur.readthedocs.io/en/latest/simplification/cluster_network.html#rule-cluster-network>`_ for a complete explanation). This gives nodes which correspond to major load and generation centres (typically cities).
 
-The total number of nodes for Europe is set in the ``config.yaml`` file
-under ``clusters``. The number of nodes can vary between 37, the number
-of independent countries / synchronous areas, and several
-hundred. With 200-300 nodes the model needs 100-150 GB RAM to solve
-with a commerical solver like Gurobi.
+Exemplary unsolved network clustered to 512 nodes:
 
+.. image:: ../graphics/elec_s_512.png 
 
-Not all of the sectors are at the full nodal resolution, and some
-demand for some sectors is distributed to nodes using heuristics that
-need to be corrected. Some networks are copper-plated to reduce
-computational times.
+Exemplary unsolved network clustered to 37 nodes:
 
-For example:
+.. image:: ../graphics/elec_s_37.png
 
-Electricity network: nodal.
+The total number of nodes for Europe is set in the config.yaml file under `clusters <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L20>`_.  The number of nodes can vary between 37, the number of independent countries/ synchronous areas, and several hundred. With 200-300 nodes, the model needs 100-150 GB RAM to solve with a commercial solver like Gurobi.
+Not all of the sectors are at the full nodal resolution, and some demand for some sectors is distributed to nodes using heuristics that need to be corrected. Some networks are copper-plated to reduce computational times.
 
-Electricity residential and commercial demand: nodal, distributed in
-each country based on population and GDP.
+Here are some examples of how spatial resolution is set for different sectors in PyPSA-Eur-Sec:
 
-Electricity demand in industry: based on the location of industrial
-facilities from `HotMaps database <https://gitlab.com/hotmaps/industrial_sites/industrial_sites_Industrial_Database>`_.
+•	Electricity network: Modeled as nodal
 
-Building heating demand: nodal, distributed in each country based on
-population.
+•	Electricity residential and commercial demand: Modeled as nodal, distributed in each country based on population and GDP.
 
-Industry demand: nodal, distributed in each country based on
-locations of industry from `HotMaps database <https://gitlab.com/hotmaps/industrial_sites/industrial_sites_Industrial_Database>`_.
+•	Electricity distribution network: Not included in the model, but a link per node can be used to represent energy transferred between distribution and transmission levels (explained more in detail below).
 
-Hydrogen network: nodal.
+•	Residential and commercial building heating demand: Modeled as nodal, distributed in each country based on population.
 
-Methane network: single node for Europe, since future demand is so low and no
-bottlenecks are expected. Optionally, if for example retrofitting from fossil
-gas to hydrogen is to be considered, the methane grid can be nodally resolved
-based on SciGRID_gas data.
+•	Electricity demand in industry: Modeled as nodal, based on the location of industrial facilities from HotMaps database.
 
-Solid biomass: choice between single node for Europe and nodal where biomass
-potential is regionally disaggregated (currently given per country,
-then distributed by population density within)
-and transport of solid biomass is possible.
+•	Industry demand (heat, chemicals, etc.) : Modeled as nodal, distributed in each country based on locations of industry from HotMaps database.
+•	Hydrogen network: Modeled as nodal (if activated in the `Config <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L260>`_ file).
 
-CO2:  single node for Europe, but a transport and storage cost is added for
-sequestered CO2. Optionally: nodal, with CO2 transport via pipelines.
+•	Methane network: It can be modeled as a single node for Europe or it can be nodally resolved if activated in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L266>`_ . One node can be considered reasonable since future demand is expected to be low and no bottlenecks are expected. Also, the nodally resolved methane grid is based on SciGRID_gas data.
 
-Liquid hydrocarbons: single node for Europe, since transport costs for
-liquids are low.
+•	Solid biomass: It can be modeled as a single node for Europe or it can be nodally resolved if activated in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L270>`_. Nodal modeling includes modeling biomass potential per country (given per country, then distributed by population density within) and the transport of solid biomass between countries.
+
+•	CO2: It can be modeled as a single node for Europe or it can be nodally resolved with CO2 transport pipelines if activated in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L248>`_ . It should mentioned that in single node mode a transport and storage cost is added for sequestered CO2, the cost of which can be adjusted in the `Config <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L247>`_ file. 
+
+•	Liquid hydrocarbons: Modeled as a single node for Europe, since transport costs for liquids are low and no bottlenecks are expected.
+
+**Electricity distribution network**
+
+Contrary to the transmission grid, the grid topology at the distribution level (at and below 110 kV) is not included due to very high computational burden. However, a link per node can be used (activated in `Config <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L257>`_ file) to represent energy transferred between distribution and transmission levels. So basically, only the total capacity from the transmission grid down to the low-voltage level is optimized. The Cost of this link between transmission level and distribution level can be adjusted from zero to any number in Config file `options <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L258>`_ , and is currently assumed to be 500 eur/kW. 
+
+Rooftop PV, heat pumps, resistive heater, home batteries and chargers for passenger cars are connected to low-voltage level. All the remaining generation and storage technologies are connected to the transmission grid. In practice this means that the distribution grid capacity is only extended if it is necessary to balance the mismatch between local generation and demand. 

doc/supply_demand.rst

@@ -383,18 +383,47 @@ Annual energy demands for land transport, aviation and shipping for every countr
 
 *Land transport*
 
+Both road and rail transport is combined as `land transport demand <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/build_transport_demand.py#L74>`_ although electrified rail transport is excluded because the energy is included in the electricity demand.
+
+The most important settings for land transport are the exogenously fixed fuel mix. In the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L181>`_, the share of battery electric vehicles (BEV) and hydrogen fuel cell vehicles (FCEV) can be set. The remaining percentage will be treated as internal combustion engines (ICE) that consume oil products.
+
+*Electric vehicles (BEV)*
+
+For the electrified land transport, country-specific factors are computed by comparing the `current car final energy consumption per km in <https://www.sciencedirect.com/science/article/pii/S0360544216310295>`_ (average for Europe 0.7 kWh/km) to the 0.18 kWh/km value assumed for battery-to-wheels efficiency in EVs. The characteristic `weekly profile <https://doi.org/10.1057/s41302-016-0009-6>`_ provided by the German Federal Highway Research Institute (BASt) is used to obtain hourly time series for European countries taking into account the corresponding local times. Furthermore, a temperature dependence is included in the time series to account for heating/cooling demand in transport. For temperatures `below <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L166>`_/`above <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L165>`_ certain threshold values, e.g. 15C/20C, `temperature coefficients <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L169>`_ of typically 0.98%/C and 0.63%/C are assumed, based on the `paper <https://www.sciencedirect.com/science/article/pii/S036054421831288X>`_.
+
+For BEVs the user can define the `storage energy capacity <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L173>`_, `charging power capacity <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L176>`_, and `charging efficiency <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L174>`_.
+
+For BEV, smart charging is an option. A `certain share <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L172>`_ of the BEV fleet can shift their charging time. The BEV state of charge is forced to be higher than a `set percentage <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L163>`_, e.g. 75%, every day at a `specified hour <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L164>`_, e.g., 7 am, to ensure that the batteries are sufficiently charged for peak usage in the morning. They also have the option to participate in vehicle-to-grid (V2G) services to facilitate system operation if that `is enabled <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L179>`_
+
+The battery cost of BEV is not included in the model since it is assumed that BEV owners buy them to primarily satisfy their mobility needs.
+
+*Hydrogen fuel cell vehicles (FCEV)*
+
+The share of all land transport that is specified to be be FCEV will be converted to a demand for hydrogen [link to hydrogen] using the `FCEV effeciency
+<https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L191>`_.
+
+FCEVs are typically used to simulate demand for transport that is hard to electrify directly, e.g. heavy construction machinery. But it may also be used to investigate a more widespread adoption of the technology.
+
+*Internal combustion engine vehicles (ICE)* 
+
+All land transport that is not specified to be either BEV or FCEV will be treated as conventional ICEs. The transport demand is converted to a demand for oil products [link to oil products] using the `ICE effeciency
+<https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L192>`_.
 
 *Aviation*
 
-The `demand for aviation <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2193>`_ includes international and domestic use. It is modeled as an oil demand since aviation consumes kerosene. This can be produced synthetically or have fossil-origin [link to oil product].
+The ‘demand for aviation <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2193>`_ includes international and domestic use. It is modeled as an oil demand since aviation consumes kerosene. This can be produced synthetically or have fossil-origin [link to oil product].
+
 
 *Shipping*
 
-Shipping energy demand is covered by a combination of oil and hydrogen. The amount of oil products that are converted into hydrogen follow an `exogenously defined path <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L198>`_. To estimate the `hydrogen demand <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2089>`_, the average fuel efficiency of the fleet is used in combination with the efficiency of the fuel cell defined in the technology data. The average fuel efficiency is set in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L196>`_.
+Shipping energy demand is covered by a combination of oil and hydrogen. Other fuel options, like methanol or ammonia, are currently not included in PyPSA-Eur-Sec.The share of shipping that is assumed to be supplied by hydrogen can be selected in the config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L198>`_.
 
-The consumed hydrogen comes from the general hydrogen bus where it can be produced by SMR, SMR+CC or electrolysers [link to hydrogen]. The fraction that is not converted into hydrogen use oil products, i.e. is connected to the general oil bus.
+To estimate the `hydrogen demand <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2090>`_, the average fuel efficiency of the fleet is used in combination with the efficiency of the fuel cell defined in the technology-data repository. The average fuel efficiency is set in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L196>`_.
+
+The consumed hydrogen comes from the general hydrogen bus where it can be produced by SMR, SMR+CC or electrolysers [link to hydrogen]. The fraction that is not converted into hydrogen use oil products, i.e., is connected to the general oil bus.
+
+The energy demand for liquefaction of the hydrogen used for shipping can be `included  <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L197>`_. If this option is selected, liquifaction will happen at the `node where the shipping demand occurs <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2064>`_.
 
-The user can toggle if the energy demand for liquefaction of the hydrogen used for shipping should be `included or not  <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L197>`_. If this option is selected, liquifaction will happen at the `node where the shipping demand occurs <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/scripts/prepare_sector_network.py#L2064>`_.
 
 
 Carbon dioxide capture, usage and sequestration (CCU/S)

doc/technology_assumptions.rst

@@ -0,0 +1,9 @@
+.. _technology_assumptions:
+
+##########################################
+Technology and cost assumptions
+##########################################
+
+*Techno-Economic Assumptions*
+
+For the technological assumptions (cost,efficiency, lifetime, etc.), we take estimates for the investment year specified in the `config file <https://github.com/PyPSA/pypsa-eur-sec/blob/3daff49c9999ba7ca7534df4e587e1d516044fc3/config.default.yaml#L43>`_. Many of those come from a database published by the Danish Energy Agency (`DEA <https://ens.dk/en/our-services/projections-and-models/technology-data>`_). Assumptions are maintained at the `technology data repository <https://github.com/PyPSA/technology-data>`_.