##################################################
MVS - Multi-Vector Simulator of the E-LAND toolbox
##################################################
|badge_docs| |badge_CI| |badge_coverage| |badge_zenodo| |badge_pypi| |badge_gpl2| |badge_black|
Rights: `Reiner Lemoine Institut (Berlin) <https://reiner-lemoine-institut.de/>`__
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:
- Analysis of an energy system model, which can be defined from csv or json files, including its costs and performance parameters.
- Near-future investments into power generation and storage assets can be optimized aiming at least-cost supply of electricity and heat.
- Future energy supply scenarios that integrate emerging technologies helping to meet sustainability goals and decrease adverse climate effects can be evaluated, e.g. through high renewable energy shares or sector-coupling technologies.
The tool is being developed within the scope of the H2020 project E-LAND (Integrated multi-vector management system for
Energy isLANDs, `project homepage <https://elandh2020.eu/>`__).
A graphical user interface for the MVS will be integrated.
*Latest release*: Check the `latest release <https://github.com/rl-institut/multi-vector-simulator/releases/latest>`__.
Please check the `CHANGELOG.md <https://github.com/rl-institut/multi-vector-simulator/blob/master/CHANGELOG.md>`__ for past updates and changes.
You find advanced documentation of the MVS on `readthedocs <https://multi-vector-simulator.readthedocs.io/en/stable/>`__
(stable version, latest developments `here <https://multi-vector-simulator.readthedocs.io/en/latest/>`__).
*Disclaimer*: As the MVS is still under development, changes might 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.
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 creating a github issue.
Maybe you have ideas that can help the MVS move forward? Maybe you noticed a bug that we can resolve?
For advanced programmers: You can also use the ``dev`` branch that includes the latest updates and changes.
You find the changelog `HERE <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CHANGELOG.md>`__.
.. |badge_docs| image:: https://readthedocs.org/projects/multi-vector-simulator/badge/?version=latest
:target: https://multi-vector-simulator.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |badge_CI| image:: https://github.com/rl-institut/multi-vector-simulator/workflows/CI/badge.svg
:alt: Build status
.. |badge_coverage| image:: https://coveralls.io/repos/github/rl-institut/multi-vector-simulator/badge.svg
:target: https://coveralls.io/github/rl-institut/multi-vector-simulator
:alt: Test coverage
.. |badge_zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4610237.svg
:target: https://doi.org/10.5281/zenodo.4610237
:alt: Zenodo DOI
.. |badge_gpl2| image:: https://img.shields.io/badge/License-GPL%20v2-blue.svg
:target: https://img.shields.io/badge/License-GPL%20v2-blue.svg
:alt: License gpl2
.. |badge_pypi| image:: https://badge.fury.io/py/multi-vector-simulator.svg
:target: https://pypi.org/project/multi-vector-simulator/
:alt: Pypi version
.. |badge_black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: black linter
========================
Getting started with MVS
========================
Setup
=====
To set up the MVS, follow the steps below:
- If python3 is not pre-installed: Install miniconda (for python 3.7: https://docs.conda.io/en/latest/miniconda.html)
- WINDOWS USERS: Using an Anaconda virtual environment is highly recommended for being able to fully utilize the tool. Venv
environtments works only for running the optimization tool (mvs_tool). For this, updating Pandas to at least version 1.3.5
and installing the package pygraphviz as indicated in this link https://pygraphviz.github.io/documentation/stable/install.html
is necessary. However, it is not possible to run the interactive report (mvs_report) with venv, as it gives an error.
Therefore, it is best to use conda environments.
- Open Anaconda prompt (or other software as Pycharm) to create and activate a virtual environment
``conda create -n [your_env_name] python=3.6 activate [your env_name]``
- Install the latest `MVS release <https://github.com/rl-institut/multi-vector-simulator/releases>`__:
``pip install multi-vector-simulator``
- Download the `cbc-solver <https://projects.coin-or.org/Cbc>`__ into your system from https://ampl.com/dl/open/cbc/
and integrate it in your system, ie. unzip, place into chosen path, add path to your system variables
(Windows: “System Properties” -->”Advanced”--> “Environment Variables”, requires admin-rights).
You can also follow the `steps <https://oemof-solph.readthedocs.io/en/latest/readme.html#installing-a-solver>`__
from the oemof setup instructions
- Test if that the cbc solver is properly installed by typing
``oemof_installation_test``
You should at least get a confirmation that the cbc solver is working
::
*****************************
Solver installed with oemof:
cbc: working
glpk: not working
gurobi: not working
cplex: not working
*****************************
oemof successfully installed.
*****************************
- Test if the MVS installation was successful by executing
``mvs_tool``
This should create a folder ``MVS_outputs`` with the example simulation's results
You can always check which version you installed with the following command
``mvs_tool --version``
Using the MVS
=============
To run the MVS with custom inputs you have several options:
Use the command line
--------------------
Edit the json input file (or csv files) and run
::
mvs_tool -i path_input_folder -ext json -o path_output_folder
With ``path_input_folder``: path to folder with input data,
``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 options
::
mvs_tool -h
Use the ``main()`` function
---------------------------
You can also execute the mvs within a script, for this you need to import
::
from multi_vector_simulator.cli import main
The possible arguments to this functions are:
- ``overwrite`` (bool): Determines whether to replace existing results in ``path_output_folder`` with the results of the current simulation (True) or not (False) (Command line "-f"). 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 /csv\_elements/ (Command line "-ext"). Default: ``json``.
- ``path_input_folder`` (str): The path to the directory where the input CSVs/JSON files are located. Default: ``inputs/`` (Command line "-i").
- ``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 (Command line "-o"). Default: ``MVS_outputs/``.
- ``display_output`` (str): Sets the level of displayed logging messages. Options: "debug", "info", "warning", "error". Default: "info".
- ``lp_file_output`` (bool): Specifies whether linear equation system generated is saved as lp file. Default: False.
- ``pdf_report`` (bool): Specify whether pdf report of the simulation's results is generated or not (Command line "-pdf"). Default: False.
- ``save_png`` (bool): Specify whether png figures with the simulation's results are generated or not (Command line "-png"). Default: False.
Edit the csv files (or, for devs, the json file) and run the ``main()`` function. The following ``kwargs`` are possible:
Default settings
----------------
If you execute the ``mvs_tool`` command in a path where there is a folder named ``inputs`` (you can use the
folder ``input_template`` for inspiration) this folder will be taken as default input folder and you can simply run
::
mvs_tool
A default output folder will be created, if you run the same simulation
several time you would have to either overwrite the existing output file
with
::
mvs_tool -f
Or provide another output folder's path
::
mvs_tool -o <path_to_other_output_folder>
.. _pdf-report-commands:
Generate pdf report or an app in your browser to visualise the results of the simulation
----------------------------------------------------------------------------------------
To use the report feature you need to install extra dependencies first
::
pip install multi-vector-simulator[report]
If you are using zsh terminals and recieve the error message "no matches found", you might need to run
::
pip install 'multi-vector-simulator[report]'
Use the option ``-pdf`` in the command line ``mvs_tool`` to generate a pdf report in a simulation's output folder
(by default in ``MVS_outputs/report/simulation_report.pdf``):
::
mvs_tool -pdf
Use the option ``-png`` in the command line ``mvs_tool`` to generate png figures of the results in the simulation's
output folder (by default in ``MVS_outputs/``):
::
mvs_tool -png
To generate a report of the simulation's results, run the following command **after** a simulation generated an output folder:
::
mvs_report -i path_simulation_output_folder -o path_pdf_report
where ``path_simulation_output_folder`` should link to the folder of your simulation's output, or directly to a
json file (default ``MVS_outputs/json_input_processed.json``) and ``path_pdf_report`` is the path where the report should be saved as a pdf file.
The report should appear in your browser (at http://127.0.0.1:8050) as an interactive Plotly Dash app.
You can then print the report via your browser print functionality (ctrl+p), however the layout of the pdf report is
only well optimized for chrome or chromium browser.
It is also possible to automatically save the report as pdf by using the option ``-pdf``
::
mvs_report -i path_simulation_output_folder -pdf
By default, it will save the report in a ``report`` folder within your simulation's output folder
default (``MVS_outputs/report/``). See ``mvs_report -h`` for more information about possible options.
The css and images used to make the report pretty should be located under ``report/assets``.
Contributing and additional information for developers
======================================================
If you want to contribute to this project, please read
`CONTRIBUTING.md <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CONTRIBUTING.md>`__. For less experienced
github users, we propose a `workflow <https://github.com/rl-institut/multi-vector-simulator/wiki/Examplary-Workflow>`__.
For advanced programmers: please checkout the `dev` branch that includes the latest updates and changes. You can find out about the latest changes in the `CHANGELOG.md file <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CHANGELOG.md>`__.
Raw data
{
"_id": null,
"home_page": "https://github.com/rl-institut/multi-vector-simulator",
"name": "multi-vector-simulator",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "multi-vector local-energy-systems",
"author": "Reiner Lemoine Institut",
"author_email": "pypi@rl-institut.de",
"download_url": "https://files.pythonhosted.org/packages/f3/71/b3696e0ca94b9539c812ceadf3255229d48a78e20e36b7ef39c9f02cf2df/multi_vector_simulator-1.1.1.tar.gz",
"platform": null,
"description": "##################################################\nMVS - Multi-Vector Simulator of the E-LAND toolbox\n##################################################\n\n|badge_docs| |badge_CI| |badge_coverage| |badge_zenodo| |badge_pypi| |badge_gpl2| |badge_black|\n\nRights: `Reiner Lemoine Institut (Berlin) <https://reiner-lemoine-institut.de/>`__\n\nThe 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:\n\n- Analysis of an energy system model, which can be defined from csv or json files, including its costs and performance parameters.\n- Near-future investments into power generation and storage assets can be optimized aiming at least-cost supply of electricity and heat.\n- Future energy supply scenarios that integrate emerging technologies helping to meet sustainability goals and decrease adverse climate effects can be evaluated, e.g. through high renewable energy shares or sector-coupling technologies.\n\nThe tool is being developed within the scope of the H2020 project E-LAND (Integrated multi-vector management system for\nEnergy isLANDs, `project homepage <https://elandh2020.eu/>`__).\nA graphical user interface for the MVS will be integrated.\n\n*Latest release*: Check the `latest release <https://github.com/rl-institut/multi-vector-simulator/releases/latest>`__.\nPlease check the `CHANGELOG.md <https://github.com/rl-institut/multi-vector-simulator/blob/master/CHANGELOG.md>`__ for past updates and changes.\n\nYou find advanced documentation of the MVS on `readthedocs <https://multi-vector-simulator.readthedocs.io/en/stable/>`__\n(stable version, latest developments `here <https://multi-vector-simulator.readthedocs.io/en/latest/>`__).\n\n*Disclaimer*: As the MVS is still under development, changes might still occur in the code as well as code structure.\nIf you want to try the MVS, please make sure to check this project regularly.\n\nIf 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\nproject, we would be very happy if you would get in contact with us, eg. via creating a github issue.\nMaybe you have ideas that can help the MVS move forward? Maybe you noticed a bug that we can resolve?\n\nFor advanced programmers: You can also use the ``dev`` branch that includes the latest updates and changes.\nYou find the changelog `HERE <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CHANGELOG.md>`__.\n\n.. |badge_docs| image:: https://readthedocs.org/projects/multi-vector-simulator/badge/?version=latest\n :target: https://multi-vector-simulator.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. |badge_CI| image:: https://github.com/rl-institut/multi-vector-simulator/workflows/CI/badge.svg\n :alt: Build status\n\n.. |badge_coverage| image:: https://coveralls.io/repos/github/rl-institut/multi-vector-simulator/badge.svg\n :target: https://coveralls.io/github/rl-institut/multi-vector-simulator\n :alt: Test coverage\n\n.. |badge_zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.4610237.svg\n :target: https://doi.org/10.5281/zenodo.4610237\n :alt: Zenodo DOI\n\n.. |badge_gpl2| image:: https://img.shields.io/badge/License-GPL%20v2-blue.svg\n :target: https://img.shields.io/badge/License-GPL%20v2-blue.svg\n :alt: License gpl2\n\n.. |badge_pypi| image:: https://badge.fury.io/py/multi-vector-simulator.svg\n :target: https://pypi.org/project/multi-vector-simulator/\n :alt: Pypi version\n\n.. |badge_black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: black linter\n\n========================\nGetting started with MVS\n========================\n\nSetup\n=====\n\nTo set up the MVS, follow the steps below:\n\n- If python3 is not pre-installed: Install miniconda (for python 3.7: https://docs.conda.io/en/latest/miniconda.html)\n\n- WINDOWS USERS: Using an Anaconda virtual environment is highly recommended for being able to fully utilize the tool. Venv \n environtments works only for running the optimization tool (mvs_tool). For this, updating Pandas to at least version 1.3.5 \n and installing the package pygraphviz as indicated in this link https://pygraphviz.github.io/documentation/stable/install.html\n is necessary. However, it is not possible to run the interactive report (mvs_report) with venv, as it gives an error. \n Therefore, it is best to use conda environments.\n\n- Open Anaconda prompt (or other software as Pycharm) to create and activate a virtual environment\n\n ``conda create -n [your_env_name] python=3.6 activate [your env_name]``\n\n- Install the latest `MVS release <https://github.com/rl-institut/multi-vector-simulator/releases>`__:\n\n ``pip install multi-vector-simulator``\n\n- Download the `cbc-solver <https://projects.coin-or.org/Cbc>`__ into your system from https://ampl.com/dl/open/cbc/\n and integrate it in your system, ie. unzip, place into chosen path, add path to your system variables\n (Windows: \u201cSystem Properties\u201d -->\u201dAdvanced\u201d--> \u201cEnvironment Variables\u201d, requires admin-rights).\n\n You can also follow the `steps <https://oemof-solph.readthedocs.io/en/latest/readme.html#installing-a-solver>`__\n from the oemof setup instructions\n\n- Test if that the cbc solver is properly installed by typing\n\n ``oemof_installation_test``\n\n You should at least get a confirmation that the cbc solver is working\n\n ::\n\n *****************************\n Solver installed with oemof:\n\n cbc: working\n glpk: not working\n gurobi: not working\n cplex: not working\n\n *****************************\n oemof successfully installed.\n *****************************\n\n- Test if the MVS installation was successful by executing\n\n ``mvs_tool``\n\nThis should create a folder ``MVS_outputs`` with the example simulation's results\n\nYou can always check which version you installed with the following command\n\n ``mvs_tool --version``\n\n\nUsing the MVS\n=============\n\nTo run the MVS with custom inputs you have several options:\n\nUse the command line\n--------------------\n\nEdit the json input file (or csv files) and run\n\n::\n\n mvs_tool -i path_input_folder -ext json -o path_output_folder\n\nWith ``path_input_folder``: path to folder with input data,\n\n``ext``: json for using a json file and csv for using csv files\n\nand ``path_output_folder``: path of the folder where simulation results should be stored.\n\nFor more information about the possible command lines options\n\n::\n\n mvs_tool -h\n\nUse the ``main()`` function\n---------------------------\n\nYou can also execute the mvs within a script, for this you need to import\n\n::\n\n from multi_vector_simulator.cli import main\n\nThe possible arguments to this functions are:\n\n- ``overwrite`` (bool): Determines whether to replace existing results in ``path_output_folder`` with the results of the current simulation (True) or not (False) (Command line \"-f\"). Default: ``False``.\n\n- ``input_type`` (str): Defines whether the input is taken from the ``mvs_config.json`` file (\"json\") or from csv files ('csv') located within /csv\\_elements/ (Command line \"-ext\"). Default: ``json``.\n\n- ``path_input_folder`` (str): The path to the directory where the input CSVs/JSON files are located. Default: ``inputs/`` (Command line \"-i\").\n\n- ``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 (Command line \"-o\"). Default: ``MVS_outputs/``.\n\n- ``display_output`` (str): Sets the level of displayed logging messages. Options: \"debug\", \"info\", \"warning\", \"error\". Default: \"info\".\n\n- ``lp_file_output`` (bool): Specifies whether linear equation system generated is saved as lp file. Default: False.\n\n- ``pdf_report`` (bool): Specify whether pdf report of the simulation's results is generated or not (Command line \"-pdf\"). Default: False.\n\n- ``save_png`` (bool): Specify whether png figures with the simulation's results are generated or not (Command line \"-png\"). Default: False.\n\nEdit the csv files (or, for devs, the json file) and run the ``main()`` function. The following ``kwargs`` are possible:\n\nDefault settings\n----------------\n\nIf you execute the ``mvs_tool`` command in a path where there is a folder named ``inputs`` (you can use the\nfolder ``input_template`` for inspiration) this folder will be taken as default input folder and you can simply run\n\n::\n\n mvs_tool\n\nA default output folder will be created, if you run the same simulation\nseveral time you would have to either overwrite the existing output file\nwith\n\n::\n\n mvs_tool -f\n\nOr provide another output folder's path\n\n::\n\n mvs_tool -o <path_to_other_output_folder>\n\n.. _pdf-report-commands:\n\nGenerate pdf report or an app in your browser to visualise the results of the simulation\n----------------------------------------------------------------------------------------\n\nTo use the report feature you need to install extra dependencies first\n\n::\n\n pip install multi-vector-simulator[report]\n\nIf you are using zsh terminals and recieve the error message \"no matches found\", you might need to run \n\n::\n\n pip install 'multi-vector-simulator[report]'\n\n \nUse the option ``-pdf`` in the command line ``mvs_tool`` to generate a pdf report in a simulation's output folder\n(by default in ``MVS_outputs/report/simulation_report.pdf``):\n\n::\n\n mvs_tool -pdf\n\nUse the option ``-png`` in the command line ``mvs_tool`` to generate png figures of the results in the simulation's\noutput folder (by default in ``MVS_outputs/``):\n\n::\n\n mvs_tool -png\n\n\nTo generate a report of the simulation's results, run the following command **after** a simulation generated an output folder:\n\n::\n\n mvs_report -i path_simulation_output_folder -o path_pdf_report\n\nwhere ``path_simulation_output_folder`` should link to the folder of your simulation's output, or directly to a\njson file (default ``MVS_outputs/json_input_processed.json``) and ``path_pdf_report`` is the path where the report should be saved as a pdf file.\n\nThe report should appear in your browser (at http://127.0.0.1:8050) as an interactive Plotly Dash app.\n\nYou can then print the report via your browser print functionality (ctrl+p), however the layout of the pdf report is\nonly well optimized for chrome or chromium browser.\n\nIt is also possible to automatically save the report as pdf by using the option ``-pdf``\n\n::\n\n mvs_report -i path_simulation_output_folder -pdf\n\nBy default, it will save the report in a ``report`` folder within your simulation's output folder\ndefault (``MVS_outputs/report/``). See ``mvs_report -h`` for more information about possible options.\nThe css and images used to make the report pretty should be located under ``report/assets``.\n\nContributing and additional information for developers\n======================================================\n\nIf you want to contribute to this project, please read\n`CONTRIBUTING.md <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CONTRIBUTING.md>`__. For less experienced\ngithub users, we propose a `workflow <https://github.com/rl-institut/multi-vector-simulator/wiki/Examplary-Workflow>`__.\n\nFor advanced programmers: please checkout the `dev` branch that includes the latest updates and changes. You can find out about the latest changes in the `CHANGELOG.md file <https://github.com/rl-institut/multi-vector-simulator/blob/dev/CHANGELOG.md>`__.\n",
"bugtrack_url": null,
"license": null,
"summary": "Multi-vector Simulation Tool assessing and optimizing Local Energy Systems (LES) for the E-LAND project",
"version": "1.1.1",
"project_urls": {
"Bug Reports": "https://github.com/rl-institut/multi-vector-simulator/issues",
"Homepage": "https://github.com/rl-institut/multi-vector-simulator",
"Source": "https://github.com/rl-institut/multi-vector-simulator"
},
"split_keywords": [
"multi-vector",
"local-energy-systems"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af242acaa22e5e9bf54ae5956418d340e1713cf6d8640d43b71b98a161ad9f9a",
"md5": "5a2a6d6cbd97acf66464e27a14af82f9",
"sha256": "f906464af5300f68cef4ce652f6b5b84e427dd5a121fbf3e83b65110462b673f"
},
"downloads": -1,
"filename": "multi_vector_simulator-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a2a6d6cbd97acf66464e27a14af82f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 276461,
"upload_time": "2024-05-03T10:11:00",
"upload_time_iso_8601": "2024-05-03T10:11:00.428875Z",
"url": "https://files.pythonhosted.org/packages/af/24/2acaa22e5e9bf54ae5956418d340e1713cf6d8640d43b71b98a161ad9f9a/multi_vector_simulator-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f371b3696e0ca94b9539c812ceadf3255229d48a78e20e36b7ef39c9f02cf2df",
"md5": "a9869b1c3a78a605c72c28f3f71520bb",
"sha256": "dc01212804ed070a877929ecd58f02c38cad365820de31df925c555e5337e656"
},
"downloads": -1,
"filename": "multi_vector_simulator-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "a9869b1c3a78a605c72c28f3f71520bb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 326557,
"upload_time": "2024-05-03T10:11:04",
"upload_time_iso_8601": "2024-05-03T10:11:04.649973Z",
"url": "https://files.pythonhosted.org/packages/f3/71/b3696e0ca94b9539c812ceadf3255229d48a78e20e36b7ef39c9f02cf2df/multi_vector_simulator-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 10:11:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rl-institut",
"github_project": "multi-vector-simulator",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "multi-vector-simulator"
}
JSON
