From 2c49529545bc701856368985bc9fdde7fcc466b4 Mon Sep 17 00:00:00 2001 From: tZE Date: Sun, 26 Mar 2023 10:01:33 +0200 Subject: [PATCH] Improve documentation --- .../getting_started/energy_supply_systems.rst | 14 +-- docs/source/getting_started/installation.rst | 111 +++++------------- docs/source/getting_started/introduction.rst | 34 +++--- docs/source/usage/supported_models.rst | 6 +- .../usage/supported_models/terminology.rst | 26 +++- 5 files changed, 79 insertions(+), 112 deletions(-) diff --git a/docs/source/getting_started/energy_supply_systems.rst b/docs/source/getting_started/energy_supply_systems.rst index d543953..f9d622c 100644 --- a/docs/source/getting_started/energy_supply_systems.rst +++ b/docs/source/getting_started/energy_supply_systems.rst @@ -1,8 +1,8 @@ .. _Energy_Supply_Systems: -******************************** -Energy Supply Systems Simulation -******************************** +******************************* +Modelling Energy Supply Systems +******************************* .. note:: This section was copied from the :ref:`Introduction`, to make it easy to address the question @@ -17,7 +17,7 @@ In the context of tessif, an energy supply system is seen as a `graph `__ -This general approach implies, that tessif is suited best for modelling medium to large scale energy systems on a flow based description. Which is also what tessif's currently underlying :ref:`simulation models ` are suited best for. Possible applications would range from optimizing a singular house hold's energy system up to something like the integrated European network. +This general approach implies, that tessif is suited best for modelling medium to large scale energy systems on a flow based description. Which is also what tessif's currently underlying :ref:`Energy Supply System Modelling and Optimisation Software Tools (ESSMOS tools) ` are suited best for. Possible applications would range from optimizing a singular house hold's energy system up to something like the integrated European network. .. figure:: ../usage/images/hhes_graph.png :align: center @@ -26,7 +26,7 @@ This general approach implies, that tessif is suited best for modelling medium t The visualized energy system, taken from the :ref:`Hamburg Energy System Example ` -On the most (sensible) level of detail, singular participants are represented by an individual node, like a power plant, a solar panel, a battery electric vehicle, etc. On the other end of scale it is also possible aggregating multiple individual participants into a single component, like for example the aggrgation of all german hard coal fired power plants into a single component (node). Which is a common technique in energy supply system simulations. +On the most (sensible) level of detail, singular participants are represented by an individual node, like a power plant, a solar panel, a battery electric vehicle, etc. On the other end of scale it is also possible aggregating multiple individual participants into a single component, like for example the aggrgation of all german hard coal fired power plants into a single component (node). Which is a common technique in energy supply system modelling. Although possible, it does not really make sense, to model complex electromechanical systems, like i.e. a micro-chp. Because the currently :ref:`SupportedModels` (which are actually conducting the optimization) are not made for this. @@ -36,6 +36,6 @@ Optimization in this context usually means trying to anwer one or both of the fo 2. Which of the available or new components have to be expanded to reach certain secondary objectives like an emission goal, whil minimizing the costs to do so, as well as respecting given component and transportation constraints, while still meeting all the energy demands? These kind of problems can described as `expansion planning `_ or ``expansion problem``. -For additional information on typical use cases of energy supply system simulations see the guide on :ref:`Visualization`. The use cases are discussed there, showing the python code (using tessif) with which they were created as well as how their results can be visualized (again using tessif). A brief exaplanation on how and why those topics are of interest preceeds each of the use cases. +For additional information on typical use cases of energy supply system optimisations see the guide on :ref:`Visualization`. The use cases are discussed there, showing the python code (using tessif) with which they were created as well as how their results can be visualized (again using tessif). A brief exaplanation on how and why those topics are of interest preceeds each of the use cases. -As mentioned in :ref:`the section describing tessif's purpose `, tessif itself actually focuses on creating a framework (much like a common ground), rather than on energy supply system simulations themselves. It's main focus lies on data in- and output unifications as well as data transformation, to provide a unifrom, powerfull and engineer's friendly interface to conduct energy supply system simulation and :ref:`compare ` popular free open source models addressing this task. For more details, on data handling, please refer to the user guide (see navigation bar to the left). +As mentioned in :ref:`the section describing tessif's purpose `, tessif itself actually focuses on creating a framework (much like a common ground), rather than on energy supply system optimisation model. It's main focus lies on data in- and output unifications as well as data transformation, to provide a unifrom, powerfull and engineer's friendly interface to conduct energy supply system simulation and :ref:`compare ` popular free open source models addressing this task. For more details, on data handling, please refer to the user guide (see navigation bar to the left). diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst index f67d528..21e20cc 100644 --- a/docs/source/getting_started/installation.rst +++ b/docs/source/getting_started/installation.rst @@ -4,7 +4,7 @@ Installation ************ -Following Sections provide overview on how to install Tessif. +Following Sections provide overview on how to install Tessif-phd. .. contents:: Contents :backlinks: top @@ -24,17 +24,11 @@ Linux mkdir /path/to/dir cd /path/to/dir -3. Go to the `tuhh's gitlab `_, sign in and generate - a `ssh key `_ for your account. - - .. note:: - This step will be unneccesary as soon as tessif becomes a public repository - -4. Clone the git repository for **tessif** +3. Clone the git repository for **tessif-phd** .. code:: shell - git clone https://collaborating.tuhh.de/ietma/tessif/ + git clone https://collaborating.tuhh.de/ietma/tessif-phd/ 5. Create a new virtual environment and activate it: @@ -50,15 +44,12 @@ Linux pip install -U pip setuptools wheel -7. Install **tessif** and it's requirements: +7. Install **tessif-phd** and it's requirements: .. code:: shell - pip install tessif/ + pip install tessif-phd/ - .. note:: - During the process you will be asked to enter your private ssh-key password up to 3 times - if you've chosen to use one. 8. After installation is done you can check if everything went according to plan by executing tessif's tests. Do so by entering: @@ -73,10 +64,6 @@ Windows Windows installation tutorial goes here -MacOS -===== - -Mac installation tutorial goes here Development *********** @@ -92,45 +79,34 @@ Linux mkdir /path/to/dir cd /path/to/dir -3. Go to the `tuhh's gitlab `_, sign in and generate - a `ssh key `_ for your account. - - .. note:: - This step will be unneccesary as soon as tessif becomes a public repository - -4. Clone the git repository for **tessif** +3. Clone the git repository for **tessif-phd** .. code:: shell - git clone https://collaborating.tuhh.de/ietma/tessif/ + git clone https://collaborating.tuhh.de/ietma/tessif-phd/ -5. Create a new virtual environment and activate it: +4. Create a new virtual environment and activate it: .. code:: shell python3 -m venv your_env_name source your_env_name/bin/activate -6. Make sure **pip**, **setuptools** and **wheel** are up to date: +5. Make sure **pip**, **setuptools** and **wheel** are up to date: .. code:: shell pip install -U pip setuptools wheel -7. Install **tessif** and it's requirements: +6. Install **tessif-phd** and it's requirements: .. code:: shell - pip install -e tessif/[dev] - - .. note:: - During the process you will be asked to enter your private ssh-key password up to 4 times - if you've chosen to use one. + pip install -e tessif-phd/[dev] -7b. Currently there is a minor version conflict, which will get solved in the -future. After installation, update dash and ignore the warning, since tessif is -not plotting via calliope: +7. Currently there is a minor version conflict. After installation, update dash + and ignore the error, since tessif-phd is not plotting via calliope: .. code:: shell @@ -147,7 +123,7 @@ not plotting via calliope: .. code:: shell - cd tessif/docs/ + cd tessif-phd/docs/ make html If the build was succesfull you can browse the documentation using your favorite browser @@ -155,7 +131,7 @@ not plotting via calliope: .. code:: shell - tessif/docs/build/html/index.html + tessif-phd/docs/build/html/index.html .. note:: @@ -236,30 +212,11 @@ Windows mkdir \path\to\dir cd \path\to\dir -3. Enable SSH access to gitlab: - - .. note:: - - This step will be unneccesary as soon as tessif becomes a public repository - - a) Visit the `tuhh's gitlab `_ - b) Sign in and generate a - `ssh key `_ for your account. - (See a more `step-by-step - `_ - explanation in german) - c) Add gitlab to the known hosts: - - .. code:: powershell - - ssh -T git@collaborating.tuhh.de - - -4. Clone the git repository for **tessif** +3. Clone the git repository for **tessif-phd** .. code:: shell - git clone https://collaborating.tuhh.de/ietma/tessif/ + git clone https://collaborating.tuhh.de/ietma/tessif-phd/ 5. Create a new virtual environment and activate it: @@ -272,7 +229,7 @@ Windows b) If you have multiple versions of python installed - (where 3.x would mean 3.8 at this point in time (2020-11-06)): + (where 3.x would mean 3.8 at this point in time (2023-03-)): .. code:: powershell @@ -308,44 +265,40 @@ Windows pip install path\to\whl such as 'Downloads\pygraphviz‑1.6‑cp38‑cp38‑win_amd64.whl' -9. Install **tessif** and it's requirements: +9. Install **tessif-phd** and it's requirements: - a) Change into the tessif top folder (somhow on windows this is necessary) + a) Change into the tessif-phd top folder (somhow on windows this is necessary) .. code:: powershell - cd tessif + cd tessif-phd - b) Install tessif in development mode: + b) Install tessif-phd in development mode: .. code:: powershell pip install -e ./[dev] - .. note:: - During the process you will be asked to enter your private ssh-key password up to 4 times - if you've chosen to use one. - c) Currently there is a minor version conflict, which will get solved in the - future. After installation, update dash and ignore the warning, since - tessif is not plotting via calliope: + c) Currently there is a minor version conflict. After installation, update + dash and ignore the warning, since tessif is not plotting via Calliope: .. code:: shell pip install -U dash 10. After installation is done you can check if everything went according to plan by executing - tessif's tests. Do so by entering (assuming you're still outside of where you cloned tessif to): + tessif's tests. Do so by entering (assuming you're still inside of where you cloned tessif-phd to): .. code:: powershell - python tessif/tests/nose_testing.py + python tests/nose_testing.py 11. (Optional) Build your own (html) documentation using Sphinx: .. code:: powershell - cd tessif/docs/ + cd tessif-phd/docs/ .\make html If the build was succesfull you can browse the documentation using your favorite browser @@ -353,15 +306,9 @@ Windows .. code:: powershell - tessif/docs/build/html/index.html + tessif-phd/docs/build/html/index.html .. note:: Sphinx supports a variety of different `builders - `_ such as Latex or ePub. - -MacOS -===== - -Mac installation tutorial goes here - + `_ such as Latex or ePub. diff --git a/docs/source/getting_started/introduction.rst b/docs/source/getting_started/introduction.rst index 4dd070f..5caf613 100644 --- a/docs/source/getting_started/introduction.rst +++ b/docs/source/getting_started/introduction.rst @@ -4,7 +4,7 @@ Introduction ************ -Tessif can be comprehended much like a toolbox designed for handling :ref:`energy system simulation ` tasks. Each tool (corresponding to tessif's :ref:`toplevel submodules and subpackages `) serves a specific task. While these tasks may vary a lot between tools (e.g. like they do for a saw and a pencil) it still makes sense to understand both: how each tool works on its own and to how they synergize with each other. Reusing the toolbox example this transtales to understanding how different saws and pencils work on their own, but also how to draw lines on workpieces you want to cut to length. +Tessif can be comprehended much like a toolbox designed for handling :ref:`energy system modelling ` tasks. Each tool (corresponding to tessif's :ref:`toplevel submodules and subpackages `) serves a specific task. While these tasks may vary a lot between tools (e.g. like they do for a saw and a pencil) it still makes sense to understand both: how each tool works on its own and to how they synergize with each other. Reusing the toolbox example this transtales to understanding how different saws and pencils work on their own, but also how to draw lines on workpieces you want to cut to length. Following sections give a detailed guide line on how to approach tessif as a project. @@ -16,7 +16,7 @@ Following sections give a detailed guide line on how to approach tessif as a pro Goals ***** -Tessif aims to be an easy to use energy system simulations handling tool. It tries to present a consice and uniform interface to numerous free open source energy system simulation tools. This serves two main purposes: +Tessif aims to be an easy to use energy supply system modelling tool. It tries to present a consice and uniform interface to various free and open-source energy supply system modelling tools. This serves two main purposes: 1. Lowering the threshold for engineers to use free and open source energy system simulation tools, by using multiple tools through one interface. @@ -27,19 +27,19 @@ Tessif aims to be an easy to use energy system simulations handling tool. It tri Purpose ******* -There are numerous free open source energy supply system simulation frameworks available today that are written in python: +There are numerous free and open-source energy supply system modelling frameworks available today that are written in python: - pypsa (`homepage `_ , `code_repository `_, `paper `_) - oemof (`homepage `__, `code_repositories `_, `paper `__) - | urbs (`reference page `_, `code_repository `__, `paper `__) | rivus (`code_repository `__, `presentation `_) -These modeling frameworks allow the virtual simulation and modeling of energy supply systems. Each framework is or was under development by different organisations or groups of people. During the major concept phase of these tools there was little to no coordination between developers. Leading to various potentially redundant functionalities as well as data parsing overhead when trying to solve the same problem using different tools. To counteract this the `open_MODEX `_ project was initiated with the goal to find and utilize potential `synergies `_. +These modeling frameworks allow virtually modelling energy supply systems. Each framework is or was under development by different organisations or groups of people. During the major concept phase of these tools there was little to no coordination between developers. Leading to various potentially redundant functionalities as well as data parsing overhead when trying to solve the same problem using different tools. To counteract this the `open_MODEX `_ project was initiated with the goal to find and utilize potential `synergies `_. While this will help researchers to find out which tool or even which set of tools might be best for which task it somewhat fails to address the core issues when trying to use more than just one of these tools: 1. No common data input: - Each framework uses its own model(s) expecting specifically tailored datasets. This of course stems from the fact that each model specialises in different aspects of energy supply system simulation. + Each framework uses its own energy system model(s) expecting specifically tailored datasets. This of course stems from the fact that each software tool specialises in different aspects of energy supply system modelling. 2. No common data output: @@ -51,7 +51,14 @@ While this will help researchers to find out which tool or even which set of too Making the comparision between models so difficult an entire research project (`open_MODEX `_) had to be deployed. -Tessif tries to help the free open source energy supply system simulation community by addressing the beforenamed issues in order to advance open research and thus accumulating easy accessible knowledge for ultimately managing the "Energiewende" succesfully. +Tessif tries to help the free open source energy supply system modelling community by addressing the beforenamed issues in order to advance open research and thus accumulating easy accessible knowledge for ultimately managing the "Energiewende" succesfully. + +.. note:: + + Currently Tessif only supports energy supply system modelling and + **optimisation** software tols (ESSMOS tools), written in python. + Conceptually, however, Tessif can be used for any energy supply + system modeling tool. .. _Introduction_Questions: @@ -59,9 +66,9 @@ Question Tessif Helps to Answer ******************************* As laid out in :ref:`Introduction_Goals` and :ref:`Models_Tessif_Purpose` :mod:`tessif` aims to provide a simple yet powerful interface for analysing -energy supply systems using different models. +energy supply system models using different software tools. -Hence one of Tessif's primary use cases is to compare energy system simulation models +Hence one of Tessif's primary use cases is to compare energy supply system modelling software on a given energy system to answer two major questions: 1. Given an expansion and/or commitment problem, what could be a range of possible solutions using different approaches and underlying models? @@ -118,8 +125,8 @@ As well as following support structures: - 5. :mod:`Examples ` - An example hub to quickly tryout, debug and reuse simulation cases. - - 6. :mod:`Model ` - It's own data structure and solver - interface for quickly transforming data between energy system simulation tools + - 6. :mod:`Model ` - It's own data structure + for quickly transforming data between energy system modelling tools as well as providing an interface engineered for engineers. - 7. :mod:`Frused ` - All of tessif's presets as well as @@ -132,10 +139,9 @@ Following sections provide a recommended approach to familiarize oneself with te .. _Introduction_FirstSteps_EnergySupplySystemsSimulation: -Energy Supply Systems Simulations ---------------------------------- - -Understanding the topic of simulating energy supply systems is the most logical first step. +Energy Supply Systems Optimizations +----------------------------------- +Understanding the topic of optimizing energy supply systems is the most logical first step. There are a lot of kinds of energy systems. Hence there are also many different energy system simulation tools. Those mostly vary in detail, scope and focus of application. To understand the concept of tessif it helps to understand tessif's approach on energy supply systems. .. _Introduction_FirstSteps_EnergySupplySystemsSimulation_TessifsInterpretation: diff --git a/docs/source/usage/supported_models.rst b/docs/source/usage/supported_models.rst index ffd9797..8849f08 100644 --- a/docs/source/usage/supported_models.rst +++ b/docs/source/usage/supported_models.rst @@ -1,10 +1,10 @@ .. _SupportedModels: -Supported Models -**************** +Supported Software Tools +************************ Following sections provide detailed instructions on how to start using tessif's -supported energy system models. +supported ``Energy Supply System Modelling and Optimisation Software Tools (ESSMOS tools)``. .. note:: The current support of the various energy system simulation models can be gauged and expanded using the respective modules of :mod:`tessif.transform.mapping2es` and :mod:`tessif.transform.es2mapping`. diff --git a/docs/source/usage/supported_models/terminology.rst b/docs/source/usage/supported_models/terminology.rst index ac1d313..3e0684e 100644 --- a/docs/source/usage/supported_models/terminology.rst +++ b/docs/source/usage/supported_models/terminology.rst @@ -6,7 +6,9 @@ Model Terminology Goal of this section is to disambiguate the term ``Model``. In the context of :mod:`Tessif `, the term ``Model`` is used to -describe a set of distinct lines of code aiming to calculate the amount of +describe an ``Energy Supply System Model`` or ``System Model``. +In the context of :mod:`Tessif `, this describes a set of distinct +lines of code aiming to calculate the amount of energy transferred between components of an energy supply system for each timestep of a predetermined amount of timesteps. Thus, the results of these calculation must be interpretable by tessif as energy flows between energy @@ -14,20 +16,32 @@ system components for each of these timesteps. The beformentioned definition implies the following: - 1. It must be possible to display the model's simulation results as a network + 1. It must be possible to display the system model's optimisation results as a network comprised of nodes respresenting the energy system compnents and edges representing the amount of energy flowing as well as their flow direction for each timestep. - 2. The model's code language is of secondary meaning as long as it is possible - to control and access model data flow using a python interface. + 2. The programming language with which the system model was created is of secondary meaning as long as it is possible + to control and access the system model's data flow using a python interface. - 3. Tessif works independently of a model's set of equation used to obtain + 3. Tessif works independently of a system model's underlying set of equation used to obtain the results. Hence all sorts of energy supply system simulation methods can be used. Meaning tessif does not know whether the results were obtained using differntial equations, solving a linear optimization problem or a mixed integer linear optimization problem. As long as point ``2`` holds, a set of lines of code can be utilized as one of tessif's - models + supported software tools. Currently, however, Tessif only + comprises of energy supply system modelling and optimisation software tols + (ESSMOS tools), written in python. + + + +.. note:: + + Currently Tessif only supports energy supply system modelling and + **optimisation** software tols (ESSMOS tools), written in python. + Conceptually, however, Tessif can be used for any energy supply + system modeling tool. +