Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
tZE authored and tZE committed Mar 26, 2023
1 parent ffdbed1 commit 2c49529
Show file tree
Hide file tree
Showing 5 changed files with 79 additions and 112 deletions.
14 changes: 7 additions & 7 deletions docs/source/getting_started/energy_supply_systems.rst
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -17,7 +17,7 @@ In the context of tessif, an energy supply system is seen as a `graph <https://e

A 6-Node, 7-Edge Graph; Taken from `Wikipedia <https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)>`__

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 <SupportedModels>` 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) <SupportedModels>` 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
Expand All @@ -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 <AutoCompare_HH>`

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.

Expand All @@ -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 <https://en.wikipedia.org/wiki/Generation_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 <Introduction_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 <Comparison>` 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 <Introduction_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 <Comparison>` 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).
111 changes: 29 additions & 82 deletions docs/source/getting_started/installation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -24,17 +24,11 @@ Linux
mkdir /path/to/dir
cd /path/to/dir
3. Go to the `tuhh's gitlab <https://collaborating.tuhh.de/users/sign_in>`_, sign in and generate
a `ssh key <https://collaborating.tuhh.de/help/ssh/README>`_ 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:

Expand All @@ -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:
Expand All @@ -73,10 +64,6 @@ Windows

Windows installation tutorial goes here

MacOS
=====

Mac installation tutorial goes here

Development
***********
Expand All @@ -92,45 +79,34 @@ Linux
mkdir /path/to/dir
cd /path/to/dir
3. Go to the `tuhh's gitlab <https://collaborating.tuhh.de/users/sign_in>`_, sign in and generate
a `ssh key <https://collaborating.tuhh.de/help/ssh/README>`_ 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
Expand All @@ -147,15 +123,15 @@ 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
by opening

.. code:: shell
tessif/docs/build/html/index.html
tessif-phd/docs/build/html/index.html
.. note::
Expand Down Expand Up @@ -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 <https://collaborating.tuhh.de/users/sign_in>`_
b) Sign in and generate a
`ssh key <https://collaborating.tuhh.de/help/ssh/README>`_ for your account.
(See a more `step-by-step
<https://danielhuesken.de/git-fur-windows-installieren-und-ssh-keys-nutzen/>`_
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:

Expand All @@ -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
Expand Down Expand Up @@ -308,60 +265,50 @@ 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
by opening

.. code:: powershell
tessif/docs/build/html/index.html
tessif-phd/docs/build/html/index.html
.. note::
Sphinx supports a variety of different `builders
<https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ such as Latex or ePub.

MacOS
=====

Mac installation tutorial goes here

<https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ such as Latex or ePub.
Loading

0 comments on commit 2c49529

Please sign in to comment.