Update documentation.

Author: mfleschutz

README.md

@@ -54,13 +54,23 @@ The software is described and demonstrated in the open-access [draf demo paper].
    cd draf
    ```
 
-1. Create and activate the `draf` conda environment (based on environment.yml including a full editable local version of `draf`):
+1. Create and activate the `draf` conda environment (`conda env create` will create a conda environment based on [environment.yml](environment.yml) which will install the newest versions of the required packages including the full editable local version of `draf`.):
 
    ```sh
    conda env create
    conda activate draf
    ```
 
+1. (optional) To use the latest electricity prices and carbon emission factors from [`elmada`], request an [ENTSO-E API key] and set it to elmada:
+
+    ```py
+    # You have to run this Python code only once (it writes to a permanent file):
+    import elmada
+    elmada.set_api_keys(entsoe="YOUR_ENTSOE_KEY")
+    ```
+
+1. (optional) To use Gurobi (fast optimization), install a valid Gurobi license (its [free for academics](https://www.gurobi.com/academia/academic-program-and-licenses)).
+
 1. (optional) Run tests:
 
    ```sh
@@ -73,20 +83,23 @@ The software is described and demonstrated in the open-access [draf demo paper].
    jupyter notebook
    ```
 
-1. (optional) To use Gurobi (fast optimization), install a valid Gurobi license (its [free for academics](https://www.gurobi.com/academia/academic-program-and-licenses)).
-
-1. (optional) To use the latest electricity prices and carbon emission factors from [`elmada`], request an [ENTSO-E API key] and set it to elmada:
+1. Check if the imports work:
 
     ```py
-    # Python code that you have to run only once:
+    import draf
     import elmada
-    elmada.set_api_keys(entsoe="YOUR_ENTSOE_KEY")
     ```
 
-1. Start modeling
+1. (optional) Installing the newest packages via `conda env create` might create issues. Alternatively, you could use a more specific conda environment with:
+
+   ```sh
+   conda env create --file environments\environment_py39all.yml
+   conda activate draf39
+   ```
 
-1. Have a look at the [examples](examples).
-  Start with the [`minimal`](examples/minimal.py) example.
+1. Start modeling.  Have a look at the [examples](examples).
+  Start with the [`minimal`](examples/minimal.py) if you want to write your own component.
+  Start with the [`PV`](examples/pv.py) example if you want to import existing components.
   For more advanced modeling look at the [draf_demo_case_studies].
 
 ## For users

examples/bev.py

@@ -1,3 +1,11 @@
+"""This example optimizes the charging of battery electric vehicles (BEV).
+
+Two time series are considered:
+    `P_BEV_drive_TB`: The discharging power of BEV during its utilization.
+    `y_BEV_avail_TB`: The availability (0 or 1) for charging.
+Here, we assume that the BEV is available for charging when it is not used.
+"""
+
 import draf
 from draf.components import *
 

examples/der_hut.py

@@ -1,4 +1,4 @@
-"""Distributed Energy Resources (DER) and Heat Upgrading Technologies (HUT)"""
+"""Example model for Distributed Energy Resources (DER) and Heat Upgrading Technologies (HUT)"""
 
 
 import draf

examples/minimal.py

@@ -1,17 +1,16 @@
-"""Very simple example with only one user-defined component.
+"""Minimal example with only one user-defined component.
 
 Notes:
-    - There is nothing to optimize.
-    - Most of the imports are type hints and can be omitted.
+    - The model just determines the total costs `C_TOT_`. There is nothing to "optimize".
     - param_func is DRAF syntax, the model_func is GurobiPy syntax.
     - Most of the CaseStudy functions can be chained.
 """
 
 from gurobipy import GRB, Model, quicksum
 
 import draf
-from draf import Collectors, Dimensions, Params, Scenario, Vars
-from draf.abstract_component import Component
+from draf import Collectors, Dimensions, Params, Scenario, Vars  # only used for type hinting
+from draf.abstract_component import Component  # only used for type hinting
 
 
 class Minimal(Component):
@@ -20,10 +19,10 @@ def param_func(self, sc: Scenario):
 
         # Define the optimization variable C_TOT_:
         sc.var("C_TOT_", doc="Total costs", unit="€/a")
-        
+
         # Prepare time-dependent day-ahead market prices as parameter c_EG_RTP_T:
         sc.prep.c_EG_RTP_T()
-        
+
         # Prepare a time-dependent G1 standard load profile (Business on weekdays 08:00 - 18:00)
         # with the annual energy of 5 GWh:
         sc.prep.P_eDem_T(profile="G1", annual_energy=5e6)

examples/prod.py

@@ -1,8 +1,6 @@
-"""Flexible operation of an industrial process"""
-
-
+"""Flexible operation of an industrial process."""
 import draf
-from draf.components import *
+from draf.components import eDem, EG, PP, PS, pDem, Main
 
 
 def main():

examples/pv.py

@@ -1,4 +1,8 @@
-"""A small script using the model pv_bes."""
+"""A small example with a fixed electricity demand (eDem), an electricity grid (EG), a
+photovoltaic system (PV), and the Main component which contains the objective function and the
+energy balances. There is no controllable component, so the operation is determined and cannot be
+optimized. That means the Solver will solve the problem in pre-solve.
+"""
 
 import draf
 from draf.components import *

examples/pv_bes.py

@@ -1,5 +1,7 @@
-"""A model with a Photovoltaic and a Battery Energy Storage System. It is used in the showcase
-see: https://mfleschutz.github.io/draf-showcase/#/2
+"""Optimizing the operation of a 100 kWh Battery Energy Storage (BES) considering a Photovoltaic
+(PV), a fixed electricity demand (eDem), and an existing 1 MWp Photovoltaic system.
+
+The example is used in the DRAF showcase see: https://mfleschutz.github.io/draf-showcase/#/2
 """
 
 import draf

examples/pyomo_pv.py

@@ -1,7 +1,7 @@
 """This minimal example simulates the electricity purchase for a given demand and PV production.
-All variables are solves in the presolve. The aim of this file is to show the syntax of parameter
-& model definition. They are used by the main function to create a case-study with 2 scenarios: 
-`REF` and `REF_PV`.
+All variables are solved in the presolve. The aim of this file is to show the syntax of parameter
+& model definition when using Pyomo. They are used by the main function to create a case-study with
+two scenarios: `REF` and `REF_PV`.
 """
 
 import pyomo.environ as pyo
@@ -11,8 +11,9 @@
 from draf import Collectors, Dimensions, Params, Results, Scenario, Vars
 from draf.abstract_component import Component
 
+
 class TEST_COMP(Component):
-    
+
     def param_func(_, sc: draf.Scenario):
 
         # Total
@@ -34,7 +35,6 @@ def param_func(_, sc: draf.Scenario):
         sc.param("P_PV_CAPx_", 0, "existing capacity", "kW_peak")
         sc.prep.P_PV_profile_T(use_coords=True)
 
-
     def model_func(_, sc: Scenario, m: pyo.Model, d: Dimensions, p: Params, v: Vars, c: Collectors):
 
         m.obj = pyo.Objective(