Merge pull request #197 from rl-institut/release/v0.2.0

Release/v0.2.0
@SabineHaas, @smartie2076

.gitignore

@@ -108,3 +108,7 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+
+# autogenerated json
+mvs_csv_config.json

.travis.yml

@@ -18,7 +18,7 @@ install:
 
 # commands to run tests 
 script:
-  - - black --check . --exclude docs/
+  - black --check . --exclude docs/
   - coverage run -m pytest
 
 after_success:

CHANGELOG.md

@@ -18,12 +18,44 @@ Here is a template for new release sections
 ```
 
 ## [Unreleased]
+
 ### Added
 
 ### Changed
 
 ### Removed
 
+
+## [0.2.0] - 2020-03-13
+
+### Added
+- Readthedocs documentation for input parameters (#128)
+- Doctring of module A0 (#138)
+- Constants in `src/constants.py` (#153, #154)
+- Readthedocs documentation for installation (#162)
+- Plotting an networkx graph can now be turned of/on via "plot_nx_graph" in simulation_settings (#172)
+- Plot all timeseries used as input data (#171)
+
+### Changed
+- Give priority from kwargs on command line arguments (#112, #138)
+- Docstrings of module A1 (#113)
+- Changed keyword argument to positional argument for `create_input_json` function (#113)
+- function `get_user_inputs` renamed `process_user_arguments` (#138)
+- Tests for the module A0 (#138)
+Terminal commands changed (#135)
+### Removed
+- Function welcome from module A0 (#138)
+- Parameters `input_file_name`, `overwrite`, `path_input_file`, `path_input_folder`, `path_input_sequences`, `path_output_folder`, `path_output_folder_inputs` from `simulation_settings.csv` (#178)
+### Fixed
+- Input directory of csv files specified by user is handed to `load_data_from_csv.create_input_json()` (#112)
+- \#111 & \#114 fix user choice of output folder via command line arguments(#115)
+- Demand is no longer aggregated across sectors when processing/plotting in E1 (#169)
+- Optimized storage capacities are printed into results matrix (#188)
+- Sector diagrams now also include SOC diagrams (#189)
+- Sources can now have variable costs (#173)
+- \#182 Boolean simulation settings now also take affect
+- Demand is no longer aggregated across sectors when processing/plotting in E1 (#169)
+
 ## [0.1.0] -2020-01-30
 
 ### Added
@@ -110,4 +142,3 @@ Here is a template for new release sections
 ### Removed
 - yet another thing
 
-

CONTRIBUTING.md

@@ -46,9 +46,15 @@ To install all packages required for the integration tests locally:
 pip install -r tests/test_requirements.txt
 ```
 
+**!!! Important !!!**: You also need to install the mvs package locally in develop mode:
+```bash
+python setup.py develop
+```
+Otherwise your changes will not be perceived by the tests unless you run `python setup.py install` each time.
+
 Please run the tests locally before pushing your feature to the developer branch. You do that by running:
 ```bash
-pytest ./tests/tests.py 
+pytest
 ```
 Integrated tests (see ./tests/tests.py):
 

README.md

@@ -1,7 +1,7 @@
 # MVS - Multi-Vector Simulator of the E-Land toolbox
 
 [![Documentation Status](https://readthedocs.org/projects/mvs-eland/badge/?version=latest)](https://mvs-eland.readthedocs.io/en/latest/?badge=latest)
-[![Build Status](https://travis-ci.org/rl-institut/mvs_eland.svg?branch=dev)](https://travis-ci.org/rl-institut/mvs_eland.svg?branch=dev)
+[![Build Status](https://travis-ci.com/rl-institut/mvs_eland.svg?branch=dev)](https://travis-ci.com/rl-institut/mvs_eland)
 [![Coverage Status](https://coveralls.io/repos/github/rl-institut/mvs_eland/badge.svg?branch=dev)](https://coveralls.io/github/rl-institut/mvs_eland?branch=dev)
 
 Rights: [Reiner Lemoine Institut (Berlin)](https://reiner-lemoine-institut.de/)
@@ -24,7 +24,7 @@ For advanced programmers: You can also use the dev version that includes the lat
 
 If you are interested to try out the code, please feel free to do so! In case that you are planning to use it for a specific or a larger-scale project, we would be very happy if you would get in contact with us, eg. via issue. Maybe you have ideas that can help the MVS move forward? Maybe you noticed a bug that we can resolve?
 
-We are still working on including a readthedocs for the MVS. You will be able to find further information on this tool and code [HERE](https://mvs-eland.readthedocs.io/en/latest/) (developer version).
+We are still working on including a readthedocs for the MVS. Some information on this tool and code is already available [here](https://mvs-eland.readthedocs.io/en/stable/) (stable version, latest developments [here](https://mvs-eland.readthedocs.io/en/latest/)).
 
 ## Setup and installation
 
@@ -88,18 +88,35 @@ To set up the MVS, follow the steps below:
     
 ## Using the MVS
 
-To run the MVS with custom inputs, edit the json input file and run
+To run the MVS with custom inputs you have several options:
 
-    `python mvs_tool.py -i path_input_file -o path_output_folder`
+##### 1) Use the command line
 
-With `path_input_file`: path to json input file
+Edit the json input file (or csv files) and run
 
-and `path_output_folder`: path of the folder where simulation results should be stored
+    `python mvs_tool.py -i path_input_file -ext json -o path_output_folder`
+
+With 
+`path_input_file`: path to json input file,
+
+`ext`: json for using a json file and csv for using csv files
+
+and `path_output_folder`: path of the folder where simulation results should be stored.
 
 For more information about the possible command lines
 
 `python mvs_tool.py -h`
 
+##### 2) Use the `main()` function
+
+Edit the csv files (or, for devs, the json file) and run the `main()` function. The following `kwargs` are possible:
+
+- `overwrite` (bool): Determines whether to replace existing results in `path_output_folder` with the results of the current simulation (True) or not (False). Default: `False`.
+- `input_type` (str): Defines whether the input is taken from the `mvs_config.json` file ("json") or from csv files ('csv') located within <path_input_folder>/csv_elements/. Default: `json`.
+- `path_input_folder` (str): The path to the directory where the input CSVs/JSON files are located. Default: `inputs/`.
+- `path_output_folder` (str): The path to the directory where the results of the simulation such as the plots, time series, results JSON files are saved by MVS E-Lands. Default: `MVS_outputs/`.
+
+
 ## Contributing
 
 If you want to contribute to this project, please read [CONTRIBUTING.md](https://github.com/rl-institut/mvs_eland/blob/dev/CONTRIBUTING.md). For less experienced github users we propose a workflow [HERE](https://github.com/rl-institut/mvs_eland/wiki/Examplary-Workflow).

docs/Installation.rst

@@ -2,10 +2,109 @@
 Getting started with MVS
 ========================
 
+Rights: `Reiner Lemoine Institut (Berlin) <https://reiner-lemoine-institut.de/en/>`_
+
+The multi-vector simulator (MVS) allows the evaluation of local sector-coupled energy systems that include the energy carriers electricity, heat and/or gas. The MVS has three main features:
+
+Firstly, an analysis of the current energy system, which can be set up automatically from a choice of components, including its costs and performance parameters. As a second step, near-future investments into power generation and storage assets can be optimized aiming at a least-cost supply of electricity and heat. Lastly, future energy supply scenarios that integrate emerging technologies helping to meet sustainability goals and decrease adverse climate effects, e.g. through high renewable energy shares or sector-coupling technologies, can be evaluated.
+
+The tool is being developed within the scope of the H2020 project E-LAND (Integrated multi-vector management system for Energy isLANDs, project homepage `here <https://elandh2020.eu/>`_). A graphical user interface for the MVS will be integrated.
+
+**Latest release**: Check the `latest release <https://github.com/rl-institut/mvs_eland/releases/tag/v0.1.1>`_, and includes the working code of the MVS using json as an input. It is not validated and test coverage is still 0%. Please check the `CHANGELOG.md <https://github.com/rl-institut/mvs_eland/blob/master/CHANGELOG.md>`_ for past updates and changes.
+
+**Upcoming**: As the MVS is still under development, many changes will still occur in the code as well as code structure. If you want to try the MVS, please make sure to check this project regularly.
 
 Setup process for users
 ------------------------
 
+To set up the MVS, please follow the steps below:
+
+1. If python3 is not pre-installed: Install miniconda (click `here <https://docs.conda.io/en/latest/miniconda.html>`_ for python 3.7)
+
+2. Clone or download the latest `MVS release <https://github.com/rl-institut/mvs_eland/releases>`_. Run this command in your Terminal or Command Prompt to clone MVS::
+
+    git clone https://github.com/rl-institut/mvs_eland.git
+   and move to the ``mvs_eland`` folder
+
+3. Download the `cbc-solver <https://projects.coin-or.org/Cbc>`_ into your system from `here <https://ampl.com/dl/open/cbc/>` and integrate it in your system, i.e., unzip, place into chosen path, and add path to your system variables (Windows: “System Properties” --> ”Advanced” --> “Environment Variables”, requires admin-rights).
+
+   You can also follow the `steps <https://oemof.readthedocs.io/en/latest/installation_and_setup.html>` from the oemof setup instructions
+
+4. Open Anaconda prompt (or other software as Pycharm) run the following command to create and activate a virtual environment::
+
+    conda create -n [your_env_name] python=3.5 activate [your env_name]
+    
+4. Install required packages from requirements.txt file using pip::
+
+    pip install -r requirements.txt
+    
+5. Test if that the cbc solver is properly installed by typing::
+
+    oemof_installation_test
+   You should at least get a confirmation as below that the cbc solver is working::
+   
+    *****************************
+    Solver installed with oemof:
+
+    cbc: working
+    glpk: not working
+    gurobi: not working
+    cplex: not working
+
+    *****************************
+    oemof successfully installed.
+    *****************************
+    
+6. Install the mvs_eland package locally::
+
+    python setup.py install
+    
+7. Test if the MVS is running by executing::
+
+    python mvs_tool.py
+    
+8. You can also run all existing tests by executing::
+
+    pip install -r tests/test_requirements.txt
+
+    pytest
+
+    
+Using the MVS
+-------------
+
+To run the MVS with custom inputs you have several options:
+
+##### 1) Use the command line
+
+Edit the json input file (or csv files) and run
+
+    `python mvs_tool.py -i path_input_file -ext json -o path_output_folder`
+
+With 
+`path_input_file`: path to json input file,
+
+`ext`: json for using a json file and csv for using csv files
+
+and `path_output_folder`: path of the folder where simulation results should be stored.
+
+For more information about the possible command lines
+
+`python mvs_tool.py -h`
+
+##### 2) Use the `main()` function
+
+Edit the csv files (or, for devs, the json file) and run the `main()` function. The following `kwargs` are possible:
+
+- `overwrite` (bool): Determines whether to replace existing results in `path_output_folder` with the results of the current simulation (True) or not (False). Default: `False`.
+- `input_type` (str): Defines whether the input is taken from the `mvs_config.json` file ("json") or from csv files ('csv') located within <path_input_folder>/csv_elements/. Default: `json`.
+- `path_input_folder` (str): The path to the directory where the input CSVs/JSON files are located. Default: `inputs/`.
+- `path_output_folder` (str): The path to the directory where the results of the simulation such as the plots, time series, results JSON files are saved by MVS E-Lands. Default: `MVS_outputs/`.
+
+
+Contributing and additional information for developers
+------------------------------------------------------
+
+If you want to contribute to this project, please read [CONTRIBUTING.md](https://github.com/rl-institut/mvs_eland/blob/dev/CONTRIBUTING.md). For less experienced github users we propose a workflow [HERE](https://github.com/rl-institut/mvs_eland/wiki/Examplary-Workflow).
 
-Additional setup for developers
--------------------------------
+For advanced programmers: You can also use the dev version that includes the latest updates and changes, but which in turn might not be tested. You can find the CHANGELOG.md `here <https://github.com/rl-institut/mvs_eland/blob/dev/CHANGELOG.md>`_. 

docs/MVS_parameters.rst

@@ -0,0 +1,136 @@
+======================================
+Parameters and Definitions in CSV/JSON 
+======================================
+
+project_data.csv
+----------------
+
+**country**: Name of the country where the project is being deployed. E.g.: Germany
+
+**latitude**: Latitude coordinate of the project’s geographical location
+
+**longitude**: Longitude coordinate of the project’s geographical location
+
+**Project_id**: Users can assign a project ID as per their preference. 
+
+**Project_name**: Users can assign a project name as per their preference.
+
+**scenario_id**: Users can assign a scenario id as per their preference.
+
+**scenario_name**: Users can assign a scenario name as per their preference.
+
+
+economic_data.csv
+-----------------
+
+**currency**: The currency of the country where the project is implemented. For example, in the case of Germany, the value is EUR. For Norway, it is NOK. 
+
+**discount_factor**: Discount factor is the factor which accounts for the depreciation in the value of money in the future, compared to the current value of the same money. 
+
+**Project_duration**: The name of years the project is intended to be operational. 
+
+**tax**: Tax factor. 
+
+simulation_settings.csv
+-----------------------
+
+**display_output**: [Developer setting] Default value is "debug"
+
+**evaluated_period**: The number of days for which the simulation is to be run.
+
+**oemof_file_name**: The name of the OEMOF file in which the simulation results are stored. 
+
+**output_lp_file**: Acceptable values are either True or False. Entering True would result in the generation of a file with the linear equation system describing the simulation, ie., with the objective function and all the constraints. This lp file enables the user to peer ‘under the hood’ to understand how the program optimizes for the solution.
+
+**restore_from_oemof_file**: [Developer setting] Allows the developer to check the OEMOF file where the results are stored and edit the simulation parameters in it. (not integrated yet!)
+
+**start_date**: The data and time on which the simulation starts at the first step. Acceptable format is YYYY-MM-DD HH:MM:SS. E.g.: 2018-01-01 00:00:00
+
+**store_oemof_results**: [Developer setting] Acceptable values are either True or False. Assigning True would enable the results to be stored in a OEMOF file. 
+
+**timestep**: Length of the timesteps. Acceptable values in minutes. This is currently only tested for 60-minute intervals.
+
+Common Parameters in the CSV/JSON files and in energyConversion.csv:
+--------------------------------------------------------------------
+
+**First row of the csv (C1, E1, D1...)**: Input the names of the conversion components in a computer readable format, ie. with underscores instead of spaces, no special characters (eg. pv_plant_01)
+
+**age_installed**: The number of years the asset has already been in operation
+
+**capex_fix**: A fixed cost to implement the asset, eg. planning costs which do not depend on the (optimized) asset capacity (€)
+
+**capex_var**: Actual CAPEX of the asset (€/kW), ie. specific investment costs
+
+**efficiency**: Ratio of energy output/energy input
+
+**Inflow_direction**: The bus/component from which the energyVector is arriving into the asset
+
+**installedCap**: The already existing installed capacity in-place, which will also be replaced after its lifetime (kW)
+
+**label**: Name of the asset
+
+**lifetime**: Number of operational years of the asset until it has to be replaced
+
+**opex_fix**: Specific annual OPEX of the asset (€/kW/year)
+
+**opex_var**: Variable cost associated with a flow through/from the asset (€/kWh)
+
+**optimizeCap**: Permissible values are either True or False; ‘True’ if the user wants to perform capacity optimization for various components
+
+**outflow_direction**: The bus/component to which the energyVector is leaving, from the asset
+
+**energyVector**: Energy commodity. E.g.: Electricity, heat, bio-gas, etc. 
+
+**type_oemof**: Input the type of OEMOF component. For example, a PV plant would be a source, a solar inverter would be a transformer, etc.  The “type_oemof” will later on be determined through the EPA.
+
+**unit**: Unit associated with the capacity of the component. For example, storage could have units like kW or kWh, transformer station could have kVA, and so on. 
+
+
+energyProduction.csv
+--------------------
+
+**First row of the csv (C1, E1, D1...)**: Input the names of the production components in a computer readable format, ie. with underscores instead of spaces, no special characters (eg. pv_plant_01)
+
+**file_name**: Name of the csv file containing the input PV generation time-series. E.g.: filename.csv 
+
+
+energyProviders.csv
+-------------------
+
+**energy_price**: Price of electricity sourced from the utility grid (€/kWh)
+
+**feedin_tariff**: Price received for feeding electricity into the grid (€/kWh)
+
+**peak_demand_pricing**: Price to be paid additionally for energy-consumption based on the peak demand of a period (€/kW)
+
+**Peak_demand_pricing_period**: Number of reference periods in one year for the peak demand pricing. Only one of the following are acceptable values: 1 (yearly), 2, 3 ,4, 6, 12 (monthly).
+
+
+energyConsumption.csv
+---------------------
+
+**First row of the csv (C1, E1, D1...)**: Input the names of the consumption components in a computer readable format, ie. with underscores instead of spaces, no special characters (eg. pv_plant_01)
+
+**dsm**: Demand Side Management. Acceptable values are either True or False. Currently, not implemented. 
+
+**type_asset**: [Depreciated in the current version of MVS E-Lands]
+
+
+energyStorage.csv
+-----------------
+
+**First row of the csv (C1, E1, D1...)**: Input the names of the storage components in a computer readable format, ie. with underscores instead of spaces, no special characters (eg. pv_plant_01)
+
+**storage_filename**: Corresponding to the values in C1, D1, E1… cells, enter the correct CSV filename which hosts the parameters of the corresponding storage component.
+
+storage_xx.csv
+--------------
+
+**crate**: C-rate is the rate at which the storage can charge or discharge relative to the nominal capacity of the storage.
+A c-rate of 1 implies that the battery can discharge or charge completely in a single timestep. 
+
+**soc_initial**: The level of charge (as a factor of the actual capacity)  in the storage in the zeroth timestep. Acceptable values are either None or the factor. 
+
+**soc_max**: The maximum permissible level of charge in the battery (generally, it is when the battery is filled to its nominal capacity), represented by the value 1.0. Users can  also specify a certain value as a factor of the actual capacity. 
+
+**soc_min**: The minimum permissible level of charge in the battery as a factor of the nominal capacity of the battery. 

docs/index.rst

@@ -13,6 +13,7 @@ Welcome to Multi-Vector Simulator (MVS)'s documentation!
    Installation
    Developing
    Code
+   MVS_parameters
 
 ==================
 Indices and tables