Merge pull request #327 from rl-institut/feature/revise_docs

Feature/revise docs

README.md

@@ -11,8 +11,19 @@ The model is a perfect-foresight, cost minimizing linear optimization model that
 [oemof.tabular](https://github.com/oemof/oemof-tabular),
 and [oemoflex](https://github.com/rl-institut/oemoflex).
 
-oemof-B3 is currently under heavy development, which means that first full scenario runs will be
-available in the coming months.
+There are six scenarios available, that you can calculate with oemof-B3:
+- 2050-80-el_eff
+- 2050-80-gas_moreCH4
+- 2050-95-el_eff
+- 2050-95-gas_moreCH4
+- 2050-100-el_eff
+- 2050-100-gas_moreCH4
+
+All six refer to the target year 2050. A further distinction is made between an emissions reduction
+of 80, 95 or 100 percent. Furthermore, the scenarios differ in their degree of electrification. 
+Scenarios with the index 'el_eff' represent strongly electrified scenarios, while 'gas_moreCH4'
+represent scenarios with increased use of methane.
+In the documentation you will find instructions on how to run the scenarios with oemof-B3.
 
 ## Getting started
 

docs/bibliography.bib

@@ -23,7 +23,7 @@ @misc{NEP2021_Entwurf_1
 	title        = {Netzentwicklungsplan Strom 2035 (2021), erster Entwurf},
 	author       = {Übertragungsnetzbetreiber CC-BY-4.0},
 	year         = 2021,
-	url          = {https://www.netzentwicklungsplan.de/sites/default/files/paragraphs-files/NEP_2035_V2021_1_Entwurf_Teil1.pdf},
+	url          = {https://www.netzentwicklungsplan.de/sites/default/files/2022-11/NEP_2035_V2021_1_Entwurf_Teil1_1.pdf},
 	note         = {accessed 2021-06-08}
 }
 @techreport{ISE_masterplan_solarcity,

docs/getting_started.rst

@@ -4,11 +4,6 @@
 Getting started
 ~~~~~~~~~~~~~~~
 
-.. contents:: `Contents`
-    :depth: 1
-    :local:
-    :backlinks: top
-
 Using oemof-B3
 ==============
 
@@ -50,10 +45,17 @@ If you have installation problems, consider opening an
 `issue <https://github.com/rl-institut/oemof-B3/issues>`_.
 
 
-How to install geopandas under Windows
---------------------------------------
-Geopandas is necessary in `oemof-B3` for a small subset of the modeling steps. Therefore it is part of the extras requirements.
-The installation of geopandas on Windows can be challenging. According to the geopandas documentation (https://geopandas.org/getting_started/install.html) there are multiple ways to install it. We recommend to use the conda-forge channel:
+How to install geopandas
+------------------------
+Geopandas is necessary in `oemof-B3` for a small subset of the modeling steps. Therefore it is part
+of the extras requirements. To install geopandas execute
+
+::
+
+    poetry install -E preprocessing
+
+
+The installation of geopandas on **Windows** can be challenging. According to the geopandas documentation (https://geopandas.org/getting_started/install.html) there are multiple ways to install it. We recommend to use the conda-forge channel:
 
 Simply type
 
@@ -139,10 +141,38 @@ Alternatively, to create just the output file or directory of one rule, run:
 
      snakemake -j<NUMBER_OF_CPU_CORES> <output file or folder>
 
+The calculations of scenarios in the :file:`results` directory can be deleted on Darwin/macOS
+systems by executing the following rule:
+
+::
+
+    snakemake -j1 clean
+
+To remove all scenario results on a Windows based system, the following rule can be executed:
+
+::
+
+    snakemake -j1 clean_on_win_sys
 
 Contributing to oemof-B3
 ========================
 
+You can use oemof-B3 to calculate your own scenarios.
+To adapt the energy system of Brandenburg and Berlin according to your requirements, a modification
+of the componentes in the subdirectory oemof_b3 can be done.
+But you can also modify oemof_b3 to define your own energy system of another city or district.
+For all these use cases, the data in the raw directory
+must be adapted. For this purpose, it is advisable to have energy system-specific empty scalar data
+and time series created for each scenario.
+
+Executing the rule
+
+::
+
+    snakemake -j1 create_empty_scalars
+
+will create empty scalars.
+
 The rule
 
 ::
@@ -152,6 +182,5 @@ The rule
 will create empty time series data.
 The empty scalars and time series data can be used to verify your energy system model in the preprocessing stage.
 
-
 You can write `issues <https://github.com/rl-institut/oemof-B3/issues>`_ to announce bugs or
 to propose enhancements.

docs/how_to_customize_oemof-B3.rst

@@ -4,11 +4,6 @@
 How to customize oemof-B3
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. contents:: `Contents`
-    :depth: 1
-    :local:
-    :backlinks: top
-
 To use oemof-B3, you may want to modify some files, depending on what you want to model.
 
 While you define scenarios in the directory :attr:`scenarios`, you can specify the structure of

docs/model_pipeline.rst

@@ -4,11 +4,6 @@
 Model pipeline
 ~~~~~~~~~~~~~~
 
-.. contents:: `Contents`
-    :depth: 1
-    :local:
-    :backlinks: top
-
 The main functionality of oemof-B3 is a data processing pipeline which is managed using snakemake.
 The pipeline preprocesses raw data into scalar and time series resources that are used to
 build tabular datapackages representing single energy system optimization problems. These can be
@@ -102,6 +97,18 @@ A few more conventions are important to know:
   * such powered with electricity with :attr:`config.settings.optimize.el_key` followed by :attr:`carrier` and :attr:`region` (example: :attr:`{"electricity-heat_decentral-B": 1}`).
   * Do not provide :attr:`output_parameters` or leave their :attr:`var_value` empty to neglect a component in the constraint.
 
+* The capacity of specific components of a scenario can be expanded during an optimization, if the facade attribute `expandable` is set on `True`.
+
+  * To adjust this setting, the attribute needs to be specified in the file :attr:`costs_efficiencies.csv`.
+  * An overview of all facades, which includes `expandable` can be found in the facade attributes overview <https://oemof-tabular.readthedocs.io/en/latest/facades.html#>`_ provided by oemof.tabular.
+
+* There is a distinction between the maximum capacity and the already installed capacity of specific components.
+  Both of the two attributes can be set individually:
+
+  * The attribute :attr:`capacity` in :attr:`var_name` relates to the already installed capacity. The value can be set to 0 for
+    a Greenfield assumption or to a positive numeric value for a Brownfield assumption.
+  * The attribute :attr:`capacity_potential` in :attr:`var_name` relates to the maximum capacity,
+    which can be set to a positive numeric value or left empty. In the latter case, an infinite capacity potential is assumed.
 
 .. _prepare_resources_label:
 

docs/whats_new.rst

@@ -4,11 +4,6 @@
 What's new
 ~~~~~~~~~~
 
-.. contents:: `Releases`
-    :depth: 1
-    :local:
-    :backlinks: top
-
 .. include:: whats_new/v0-0-3.rst
 .. include:: whats_new/v0-0-2.rst
 .. include:: whats_new/v0-0-1.rst

oemof_b3/tools/geo.py

@@ -6,7 +6,10 @@
 
 except ImportError:
     raise ImportError(
-        "No module named 'geopandas'. You need to install 'geopandas' in order to use this script."
+        "No module named 'geopandas'. You need to install 'geopandas' in order to use this "
+        "script. Please execute 'poetry install -E preprocessing' to install it. \nCheck also "
+        "our documentation if you are running into problems on "
+        "[`How to install geopandas`](https://oemof-b3.readthedocs.io/en/latest/getting_started.html#how-to-install-geopandas)"  # noqa: E501
     )