README,doc: soften warnings, add limitations section to doc

README.md

@@ -7,19 +7,8 @@
 
 # PyPSA-Eur-Sec: A Sector-Coupled Open Optimisation Model of the European Energy System
 
-
+PyPSA-Eur-Sec is an open model dataset of the European energy system at the
-
+transmission network level that covers the full ENTSO-E area.
-**WARNING**: This model is under construction and contains serious problems that
-distort the results. See the github repository
-[issues](https://github.com/PyPSA/pypsa-eur-sec/issues) for some of the problems
-(please feel free to help or make suggestions). There is neither a full
-documentation nor a paper yet, but we hope to have a preprint out by the end of 2021.
-You can find out more about the model capabilities in [a recent
-presentation at EMP-E](https://nworbmot.org/energy/brown-empe.pdf) or the
-following [preprint with a description of the industry
-sector](https://arxiv.org/abs/2109.09563). We cannot support this model if you
-choose to use it.
-
 
 PyPSA-Eur-Sec builds on the electricity generation and transmission
 model [PyPSA-Eur](https://github.com/PyPSA/pypsa-eur) to add demand
@@ -28,6 +17,18 @@ heating, biomass, industry and industrial feedstocks, agriculture,
 forestry and fishing. This completes the energy system and includes
 all greenhouse gas emitters except waste management and land use.
 
+**WARNING**: PyPSA-Eur-Sec is under active development and has several
+[limitations](https://pypsa-eur-sec.readthedocs.io/en/latest/limitations.html) which
+you should understand before using the model. The github repository
+[issues](https://github.com/PyPSA/pypsa-eur-sec/issues) collects known
+topics we are working on (please feel free to help or make suggestions). There is neither a full
+documentation nor a paper yet, but we hope to have a preprint out by mid-2022.
+You can find out more about the model capabilities in [a recent
+presentation at EMP-E](https://nworbmot.org/energy/brown-empe.pdf) or the
+following [paper in Joule with a description of the industry
+sector](https://arxiv.org/abs/2109.09563). We cannot support this model if you
+choose to use it.
+
 Please see the [documentation](https://pypsa-eur-sec.readthedocs.io/)
 for installation instructions and other useful information about the snakemake workflow.
 

doc/index.rst

@@ -29,10 +29,21 @@ heating, biomass, industry and industrial feedstocks. This completes
 the energy system and includes all greenhouse gas emitters except
 waste management, agriculture, forestry and land use.
 
+
+**WARNING**: PyPSA-Eur-Sec is under active development and has several
+`limitations <https://pypsa-eur-sec.readthedocs.io/en/latest/limitations.html>`_ which
+you should understand before using the model. The github repository
+`issues <https://github.com/PyPSA/pypsa-eur-sec/issues>`_ collects known
+topics we are working on (please feel free to help or make suggestions). There is neither a full
+documentation nor a paper yet, but we hope to have a preprint out by mid-2022.
+We cannot support this model if you
+choose to use it.
+
+
 .. note::
     More about the current model capabilities and preliminary results
     can be found in `a recent presentation at EMP-E <https://nworbmot.org/energy/brown-empe.pdf>`_
-    and the the following `preprint with a description of the industry sector <https://arxiv.org/abs/2109.09563>`_.
+    and the following `paper in Joule with a description of the industry sector <https://arxiv.org/abs/2109.09563>`_.
 
 This diagram gives an overview of the sectors and the links between
 them:
@@ -131,6 +142,7 @@ Documentation
 **References**
 
 * :doc:`release_notes`
+* :doc:`limitations`
 
 .. toctree::
    :hidden:
@@ -138,18 +150,7 @@ Documentation
    :caption: References
 
    release_notes
-
+   limitations
-
-Warnings
-========
-
-**WARNING**: This model is under construction and contains serious
-problems that distort the results. See the github repository
-`issues <https://github.com/PyPSA/pypsa-eur-sec/issues>`_ for some of
-the problems (please feel free to help or make suggestions). There is
-neither documentation nor a paper yet, but we hope to have a preprint
-out by summer 2020. We cannot support this model if you choose to use
-it.
 
 
 Licence

doc/limitations.rst

@@ -0,0 +1,61 @@
+##########################################
+Limitations
+##########################################
+
+While the benefit of an openly available, functional and partially validated
+model of the European energy system is high, many approximations have
+been made due to missing data.
+The limitations of the dataset are listed below,
+both as a warning to the user and as an encouragement to assist in
+improving the approximations.
+
+This list of limitations is incomplete and will be added to over time.
+
+See also the `GitHub repository issues <https://github.com/PyPSA/pypsa-eur-sec/issues>`_.
+
+- **Electricity transmission network topology:**
+  The grid data is based on a map of the ENTSO-E area that is known
+  to contain small distortions to improve readability. Since the exact impedances
+  of the lines are unknown, approximations based on line lengths and standard
+  line parameters were made that ignore specific conductoring choices for
+  particular lines. There is no openly available data on busbar configurations, switch
+  locations, transformers or reactive power compensation assets.
+
+- **Assignment of electricity demand to transmission nodes:**
+  Using Voronoi cells to aggregate load and generator data to transmission
+  network substations ignores the topology of the underlying distribution network,
+  meaning that assets may be connected to the wrong substation.
+
+- **Incomplete information on existing assets:** Approximations have
+  been made for missing data, including: existing distribution grid
+  capacities and costs, existing space and water heating supply,
+  existing industry facilities, existing transport vehicle fleets.
+
+- **Exogenous pathways for transformation of transport and industry:**
+  To avoid penny-switching the transformation of transport and
+  industry away from fossil fuels is determined exogenously.
+
+- **Energy demand distribution within countries:**
+  Assumptions
+  have been made about the distribution of demand in each country proportional to
+  population and GDP that may not reflect local circumstances.
+  Openly available
+  data on load time series may not correspond to the true vertical load and is
+  not spatially disaggregated; assuming, as we have done, that the load time series
+  shape is the same at each node within each country ignores local differences.
+
+- **Hydro-electric power plants:**
+  The database of hydro-electric power plants does not include plant-specific
+  energy storage information, so that blanket values based on country storage
+  totals have been used. Inflow time series are based on country-wide approximations,
+  ignoring local topography and basin drainage; in principle a full
+  hydrological model should be used.
+
+- **International interactions:**
+  Border connections and power flows to Russia,
+  Belarus, Ukraine, Turkey and Morocco have not been taken into account;
+  islands which are not connected to the main European system, such as Malta,
+  Crete and Cyprus, are also excluded from the model.
+
+- **Demand sufficiency:** Further measures of demand reduction may be
+  possible beyond the assumptions made here.