Merge pull request #147 from rl-institut/release/v4.6.1

Release/v4.6.1

CHANGELOG.md

@@ -19,6 +19,24 @@ Here is a template for new release sections
 -
 ```
 
+## [Offgridders V4.6.1] - 2020-11-07
+
+### Added
+- Docstrings to A1, B, C, D0, D1, E, F, G0-2 (#131, #132, #133, #134, #135, #136)
+- Literature file to readthedocs (#129)
+- Added some docstrings to functions in `G2a`, copied from `Components.rst` (#125)
+- Replaced "Yes" and "No" with True and False. In H0 and inside the Excel Files (#127)
+
+### Changed
+- Update README (#129)
+- Bump `black` version number (#144)
+- Devided the `requirements.txt` into a base one (users) and an extended one for developers and for troubleshooting (`requirements_dev.txt`) (#145)
+- Updated the installation instructions in `Readme.md` and of the RTD (#145)
+
+### Fixed
+- Small content corrections to readthedocs (#119,#123,#125)
+- Fixed parsing issue with `evaluation_prespective` by fixing definition of logging message and constant varibale definition of `AC_SYSTEM` (#143)
+
 ## [Offgridders V4.6] - 2020-08-17
 
 ### Changed

Offgridders.py

@@ -156,8 +156,10 @@ def main():
             logging.debug(
                 "Using grid availability timeseries that was randomly generated."
             )
-            blackout_experiment_name = generate_sensitvitiy_experiments.get_blackout_experiment_name(
-                sensitivity_experiment_s[experiment]
+            blackout_experiment_name = (
+                generate_sensitvitiy_experiments.get_blackout_experiment_name(
+                    sensitivity_experiment_s[experiment]
+                )
             )
             sensitivity_experiment_s[experiment].update(
                 {

README.md

@@ -2,16 +2,16 @@
 
 The simulation tool **Offgridders** * generates a model of an user-defined electricity supply system, optimizes the capacities of the system's generation, storage and electrical components and then performs a dispatch optimization of the optimized capacities.
 
-Oesmot is written in python3 and utilizes the Open Energy Modelling Framework ([Website](https://oemof.org/)) ([Code](https://github.com/oemof)) 
+Offgridders is written in python3 and utilizes the Open Energy Modelling Framework ([Website](https://oemof.org/)) ([Code](https://github.com/oemof)) 
 and as such uses linerarized component models. 
 The electricity system can include AC- as well as DC demand, inverters/rectifiers, 
 a connection to a central electricity grid (optional: with blackouts), diesel generator, 
 PV panels, wind plant and storage. 
 It is possible to allow a defined annual shortage or force a renewable share or system stability constraint. 
 For a visualization of the components and demands to be included, 
-see the [github wiki](https://github.com/smartie2076/simulator_grid-connected_micro_grid/wiki).
+see the [Readthedocs: Definition of an electricity supply system](https://offgridders.readthedocs.io/en/latest/Definition.html).
 
-Examples for electricity systems that can be simulated with oesmot: 
+Examples for electricity systems that can be simulated with Offgridders: 
 * Off-grid micro grid, purely fossil-fuelled or hybridized
 * On-grid micro grid, either only consuming or also feeding into the central grid
 * Off-grid SHS
@@ -22,13 +22,19 @@ If you have questions regarding the tool's execution or it's code pieces, please
 *) previous working name: oesmot - Open Electricity System Modelling and Optimization Tool
 
 # Setup
-* If python3 not pre-installed: Install miniconda
-* Download and integrate cbc solver
-* Open Anaconda prompt, create environment
+* Download and integrate cbc solver.
+* Open Anaconda prompt, create environment with `python==3.6`
 * Run: `pip install -r requirements.txt`
-* Execute: `python Offgridders.py ./inputs/test_input_template.xlsx`
+* Execute test data: `python Offgridders.py`
+* Run your own simulations by defining the path to your input excel file: `python Offgridders.py ./inputs/test_input_template.xlsx`
 
-For Details: See [github wiki](https://github.com/smartie2076/simulator_grid-connected_micro_grid/wiki/Installation)
+When working as a dev, you need to install additional packages with `pip install -r requirements_dev.txt`
+
+For Details: See [Readthedocs: Installation](https://offgridders.readthedocs.io/en/latest/Installation.html)
+
+# Literature
+
+For further reading please refer to [Readthedocs: Literature](https://offgridders.readthedocs.io/en/latest/Literature.html)
 
 # Change log
 

docs/Blackouts.rst

@@ -56,7 +56,7 @@ Loading previous grid availability timeseries
 
 To enable the recalculation of a set of experiments, all grid availability time series are saved to an csv-file. Enabeling the option _restore_blackouts_if_existant_ will load previously generated series.
 
-**Currently this is performed lazily**, meaning that if the number of column heads of the data frame that reloaded the csv values equals the number of blackout events due to the sensitivity bounds defined in the current simulation, the tool assumes that the loaded grid availabilities fit the simulation. If, however, a blackout experiment can not be red from the data frame through its name (column header), the tool will abort the simulation.
+**Currently this is performed lazily**, meaning that if the number of column heads of the data frame that reloaded the csv values equals the number of blackout events due to the sensitivity bounds defined in the current simulation, the tool assumes that the loaded grid availabilities fit the simulation. If, however, a blackout experiment can not be read from the data frame through its name (column header), the tool will abort the simulation.
 
 => Analyze performance of grid extension WITHOUT local generation/storage, but keep in mind that allowed shortage has to be >0 to allow blackouts
 

docs/Components.rst

@@ -2,74 +2,75 @@
 Component library: oemof_generatemodel.py
 ==========================================
 
+For a deep insight into Offgridders energy system model, the components are presented below. This information is mainly important for developers that are thinking of changing module `G` (especially `G0` and `G2a`), eg. when adding new assets.
+
 To ease the definition of the models cases, a library of the utilized buses and components for the oemof model was generated. By combining them, the cases analyze specific energy systems with equal input parameters. The connections to the energy system model of oemof are automatically created, when a function is called.
 
 Buses
 ------------------------------------------
 
-* **bus_basic** (_micro_grid_system_):
+* **bus_basic** (*micro_grid_system*):
     Creates basic fuel bus "bus_fuel" for the generator and the micro grids electricity bus "bus_electricity_mg".
 
-* **bus_el_ng** (_micro_grid_system_):
+* **bus_el_ng** (*micro_grid_system*):
     Creates electricity bus of national grid "bus_electricity_ng".
 
 Sources
 ------------------------------------------
 
-* **fuel_oem** (_micro_grid_system, bus_fuel, experiment, total_demand_):
-    Creates fuel source "source_fuel" for OEM, including variable costs (based on fuel price and combustion value) and renewable share. ATTENTION: May this lead to infeasible OEM, if generator has minimal load share?
+* **fuel_oem** (*micro_grid_system*, *bus_fuel*, *experiment*, *total_demand*):
+    Creates fuel source "source_fuel" for OEM, including variable costs (based on fuel price and combustion value) and renewable share. ATTENTION: May this lead to infeasible OEM, if generator has minimal load share???
 
-* **fuel_fix** (_micro_grid_system, bus_fuel, experiment_):
+* **fuel_fix** (*micro_grid_system*, *bus_fuel*, *experiment*):
     Creates fuel source "source_fuel" for fix capacity scenarios, ALWAYS without boundary condition of renewable share, as this can create infeasible scenarios.
 
-* **shortage** (_micro_grid_system, bus_electricity_mg, sum_demand_profile, experiment_):
+* **shortage** (*micro_grid_system*, *bus_electricity_mg*, *sum_demand_profile*, *experiment*):
     Creates source for shortages "source_shortage" including boundary conditions  for maximal unserved demand and the variable costs of unserved demand.
 
-* **maingrid** (_micro_grid_system, bus_electricity_ng, price_electricity_main_grid, experiment_):
+* **maingrid** (*micro_grid_system*, *bus_electricity_ng*, *price_electricity_main_grid*, *experiment*):
     Creates main grid electricity source "source_maingrid" with variable_costs (electricity price).
 
 Components
 ------------------------------------------
 
-* **pv_fix** (_micro_grid_system, bus_electricity_mg, pv_generation_per_kWp, capacity_pv, experiment_):
+* **pv_fix** (*micro_grid_system*, *bus_electricity_mg*, *pv_generation_per_kWp*, *capacity_pv*, *experiment*):
     Creates PV generation source "source_pv" with fix capacity, using the PV generation profile per kWp (scaled by capacity) with variable costs.
 
-* **pv_oem** (_micro_grid_system, bus_electricity_mg, pv_generation_per_kWp, experiment_):
-    Creates PV generation source "source_pv" with for OEM, using the normed PV generation profile per kWp, investment costs and variable costs.
+* **pv_oem** (*micro_grid_system*, *bus_electricity_mg*, *pv_generation_per_kWp*, *experiment*):
+    Creates PV generation source "source_pv" for OEM, using the normed PV generation profile per kWp, investment costs and variable costs.
 
-* **genset_fix** (_micro_grid_system, bus_fuel, bus_electricity_mg, capacity_fuel_gen, experiment_):
+* **genset_fix** (*micro_grid_system*, *bus_fuel*, *bus_electricity_mg*, *capacity_fuel_gen*, *experiment*):
     Generates fossil-fueled genset "transformer_fuel_generator" with nonconvex flow (min and max loading), generator efficiency, fixed capacity and variable costs. If minimal loading = 0, the generator is modeled without a nonconvex flow (which would result in an error due to constraint 'NonConvexFlow.min').
 
-* **genset_oem** (_micro_grid_system, bus_fuel, bus_electricity_mg, experiment_):
+* **genset_oem** (*micro_grid_system, bus_fuel, bus_electricity_mg, experiment*):
     Generates fossil-fueled genset "transformer_fuel_generator" for OEM with generator efficiency, investment and variable costs.
 
-* **pointofcoupling_feedin_fix** (_micro_grid_system, bus_electricity_mg, bus_electricity_ng, capacity_pointofcoupling, experiment_):
-    Creates point of coupling "pointofcoupling_feedin" with fixed capacity, convesion factor and variable costs for the feed into the national grid.
-
+* **pointofcoupling_feedin_fix** (*micro_grid_system, bus_electricity_mg, bus_electricity_ng, capacity_pointofcoupling, experiment*):
+    Creates point of coupling "pointofcoupling_feedin" with fixed capacity, conversion factor and variable costs for the feed into the national grid.
 
-* **pointofcoupling_feedin_oem** (_micro_grid_system, bus_electricity_mg, bus_electricity_ng, experiment_):
-    Creates point of coupling "pointofcoupling_feedin" for OEM, convesion factor, investment and variable costs for the feed into the national grid.
+* **pointofcoupling_feedin_oem** (*micro_grid_system, bus_electricity_mg, bus_electricity_ng, experiment*):
+    Creates point of coupling "pointofcoupling_feedin" for OEM, conversion factor, investment and variable costs for the feed into the national grid.
 
-* **pointofcoupling_tomg_fix** (_micro_grid_system, bus_electricity_mg, bus_electricity_ng, cap_pointofcoupling, experiment_):
-    Creates point of coupling "pointofcoupling_feedin" with fixed capacity, convesion factor and variable costs for the consumption from the national grid.
+* **pointofcoupling_tomg_fix** (*micro_grid_system, bus_electricity_mg, bus_electricity_ng, cap_pointofcoupling, experiment*):
+    Creates point of coupling "pointofcoupling_feedin" with fixed capacity, conversion factor and variable costs for the consumption from the national grid.
 
-* **pointofcoupling_tomg_oem** (_micro_grid_system, bus_electricity_mg, bus_electricity_ng, experiment_):
-    Creates point of coupling "pointofcoupling_feedin" for OEM, convesion factor, investment and variable costs for the consumption from the national grid.
+* **pointofcoupling_tomg_oem** (*micro_grid_system, bus_electricity_mg, bus_electricity_ng, experiment*):
+    Creates point of coupling "pointofcoupling_feedin" for OEM, conversion factor, investment and variable costs for the consumption from the national grid.
 
-* **storage_fix** (_micro_grid_system, bus_electricity_mg, capacity_storage, experiment_):
+* **storage_fix** (*micro_grid_system, bus_electricity_mg, capacity_storage, experiment*):
     Create storage unit "generic_storage" with fixed capacity, variable costs, maximal charge and discharge per timestep,  capacity loss per timestep, charge and discharge efficiency, SOC boundaries (and initial SOC, possibly not needed).
 
-* **storage_oem** (_micro_grid_system, bus_electricity_mg, experiment_):
+* **storage_oem** (*micro_grid_system, bus_electricity_mg, experiment*):
     Create storage unit "generic_storage" for OEM with investment, variable costs, maximal charge and discharge per timestep,  capacity loss per timestep, charge and discharge efficiency, SOC boundaries (and initial SOC, possibly not needed).
 
 Sinks
 ------------------------------------------
 
-* **excess** (_micro_grid_system, bus_electricity_mg_):
+* **excess** (*micro_grid_system, bus_electricity_mg*):
     Creates sink for excess electricity "sink_excess", eg. if PV panels generate too much electricity.
 
-* **demand** (_micro_grid_system, bus_electricity_mg, demand_profile_):
+* **demand** (*micro_grid_system, bus_electricity_mg, demand_profile*):
     Creates demand sink "sink_demand" with fixed flow.
 
-* **feedin** (_micro_grid_system, bus_electricity_ng_):
-    Creates sink "sink_feedin" for electricity fed into the national grid. CURRENTLY WITHOUT FEEDIN TARIFF
+* **feedin** (*micro_grid_system, bus_electricity_ng*):
+    Creates sink "sink_feedin" for electricity fed into the national grid. CURRENTLY WITHOUT FEEDIN TARIFF

docs/Configuration.rst

@@ -3,7 +3,7 @@ Configuration
 ==========================================
 **to be updated, mostly accurate**
 
-The configuration file enables the user to adapt the simulation to ones need, as listed below. The input file should, however, not be overlooked, as it summarizes all simulation input data and especially enables a sensitivity analysis of a number of parameters. This file and the sensitivity parameters will be discussed in separate Wiki entries each.
+The configuration file enables the user to adapt the simulation to ones need, as listed below. The input file should, however, not be overlooked, as it summarizes all simulation input data and especially enables a sensitivity analysis of a number of parameters. The Input file as well as the sensitivity parameters will be discussed in separate entry.
 
 Coding mode
 -----------
@@ -13,19 +13,19 @@ To simplify the simulation during coding (speeding up the calculations), **codin
 
 Restoring results
 -----------------
-It is possible to continue a sensitivity analysis where it was interrupted by checking::
+It is possible to resume a sensitivity analysis at the point of interruption by checking::
 
         restore_oemof_if_existant   = True
 
-Otherwise, all previous results will be deleted and should be manually moved to another folder, if they should be stored long-term!
+Otherwise, all previous results will be deleted and should be manually moved to another folder, if they are to be stored long-term!
 
 For this setting to work, **setting_save_oemofresults** also has to be set to True.
 
 Please keep in mind that the oemof-files are saved with the name of their case and, if present, their sensitivity case. Changing values in the config-file or the input values will therefore will not generate a new oemof-file! When changing settings or values that are not sensitivity values, _restore_oemof_if_existant_ should be disabled to result in a new simulation!.
 
 Simulated cases
 ---------------
-* Base case OEM is by default performed without minimal loading of generators, enabling sizing of generators. If a minimal loading has to be taken into account, then the setting  **base_case_with_min_loading** fixes the generator capacity to the demand peak value (without security margin).::
+* Base case OEM is by default performed without minimal loading of generators, enabling their sizing. If a minimal loading has to be taken into account, then setting  **base_case_with_min_loading** fixes the generator capacity to the demand peak value (without security margin).::
 
             base_case_with_min_loading = True
 
@@ -75,12 +75,12 @@ If no input files are used for demand and weather, the calculated demand and irr
 
 Display of results and graphs
 ______________________________
-Oemof can generate and save .lp files and .oemof files with the simulation results. These can be saved to the output folder, **setting_save_lp_file**, **setting_save_oemofresults** if are set to True. Especially with long computing times, the oemof results should be saved.::
+Oemof can generate and save .lp files and .oemof files with the simulation results. These can be saved to the output folder,if **setting_save_lp_file**, **setting_save_oemofresults** are set to True. Especially with long computing times, the oemof results should be saved.::
 
         setting_save_lp_file        = False
         setting_save_oemofresults   = True
 
-During simulation, a number of graphs can be generated (**display_graphs_solar**, **display_graphs_demand**, **display_graphs_simulation**, display interrupts computation) and simulation results printed in the command line (**print_simulation_meta**, **print_simulation_main**, **print_simulation_invest**). If the performed simulation includes a sensitivity analysis, it is advisable to disable all these functions. The details of the simulated case can be displayed with **print_simulation_experiment**.::
+During simulation, a number of graphs can be generated (**display_graphs_solar**, **display_graphs_demand**, **display_graphs_simulation**, **display interrupts computation**) and simulation results printed in the command line (**print_simulation_meta**, **print_simulation_main**, **print_simulation_invest**). If the performed simulation includes a sensitivity analysis, it is advisable to disable all these functions. The details of the simulated case can be displayed with **print_simulation_experiment**.::
 
         display_graphs_solar        = False
         display_graphs_demand       = False
@@ -106,9 +106,8 @@ In general, the solver of oemof is set to cbc (**solver**). The solver output (*
 
 To increase computation speed (especially for nonconvex flows in the dispatch OEM), an additional solver option **cmdline_option** is added  with value _cmdline_option_value_. It influences, when the solver accepts the found solution as optimal. Possible options:
 
-* ratioGap: ?
-* allowedGap: ?
-* mipgap: ?
+* ratioGap
+* allowedGap
 
 Comand line options::