Commit 7e7c3be8 authored by christian.foerster's avatar christian.foerster

changed some sphinx documentation details; made html

parent 36e65922
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 02619cf8be9c04b3079e07909c100f42
tags: 645f666f9bcd5a90fca523b33c5a78b7
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Overview: module code &mdash; tanks 1.0 documentation</title>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> tanks
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../source/description.html">Description</a></li>
<li class="toctree-l1"><a class="reference internal" href="../source/installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../source/example.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../source/issues.html">Issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../source/tanks.html">tanks package</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tanks</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li>Overview: module code</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>All modules for which code is available</h1>
<ul><li><a href="tanks/tanks.html">tanks.tanks</a></li>
</ul>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2019, Christian Foerster
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
\ No newline at end of file
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>tanks.tanks &mdash; tanks 1.0 documentation</title>
<script type="text/javascript" src="../../_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<script type="text/javascript" src="../../_static/language_data.js"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home"> tanks
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../source/description.html">Description</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../source/installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../source/example.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../source/issues.html">Issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../source/tanks.html">tanks package</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">tanks</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> &raquo;</li>
<li><a href="../index.html">Module code</a> &raquo;</li>
<li>tanks.tanks</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1>Source code for tanks.tanks</h1><div class="highlight"><pre>
<span></span><span class="c1"># A tank is a object (-&gt; class) we can touch,</span>
<span class="c1"># it has attributes like level and id and so on,</span>
<span class="c1"># discharge is property of a tank, furthermore it does have the capability to fill up (a function or method)</span>
<div class="viewcode-block" id="Tank"><a class="viewcode-back" href="../../source/tanks.html#tanks.tanks.Tank">[docs]</a><span class="k">class</span> <span class="nc">Tank</span><span class="p">:</span>
<span class="sd">&quot;&quot;&quot;Representation of a water tank with a footprint of 1 m².&quot;&quot;&quot;</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tank_id</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">rate</span><span class="p">,</span> <span class="n">upstream_tanks</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> tank_id : str</span>
<span class="sd"> Uniquely identifies tanks in your system.</span>
<span class="sd"> level : float</span>
<span class="sd"> Water level of a tank in meters [m].</span>
<span class="sd"> rate : float</span>
<span class="sd"> Specifies the changes in water level over time [1/s]. </span>
<span class="sd"> Positive values denote a decrease in water level, negative values an increase.</span>
<span class="sd"> Used to calculate the discharge (level*rate).</span>
<span class="sd"> upstream_tanks : list</span>
<span class="sd"> Defines connections between tanks. </span>
<span class="sd"> The provided list must contain entries of type Tank!</span>
<span class="sd"> </span>
<span class="sd"> Example</span>
<span class="sd"> -------</span>
<span class="sd"> # create a Tanke instance</span>
<span class="sd"> &gt;&gt;&gt; Tank(&quot;id_1&quot;,1,0.1)</span>
<span class="sd"> &lt;type Tank&gt;</span>
<span class="sd"> tank_id: id_1</span>
<span class="sd"> level: 1</span>
<span class="sd"> rate: 0.1</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">tank_id</span> <span class="o">=</span> <span class="n">tank_id</span>
<span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">=</span> <span class="n">level</span>
<span class="bp">self</span><span class="o">.</span><span class="n">rate</span> <span class="o">=</span> <span class="n">rate</span>
<span class="bp">self</span><span class="o">.</span><span class="n">upstream_tanks</span> <span class="o">=</span> <span class="n">upstream_tanks</span>
<span class="c1"># the method Q calculates the flow of a given tank every time it&#39;s called</span>
<span class="nd">@property</span> <span class="c1"># allows use of the method without brackets </span>
<span class="k">def</span> <span class="nf">Q</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Discharge of a tank. Product of level and rate.</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">*</span> <span class="bp">self</span><span class="o">.</span><span class="n">rate</span>
<span class="c1"># filling a tank from all its upstream tanks</span>
<div class="viewcode-block" id="Tank.fill_tank"><a class="viewcode-back" href="../../source/tanks.html#tanks.tanks.Tank.fill_tank">[docs]</a> <span class="k">def</span> <span class="nf">fill_tank</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> Propagates the water through the system from the downstream to upstream. </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">-=</span> <span class="bp">self</span><span class="o">.</span><span class="n">Q</span>
<span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">upstream_tanks</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
<span class="k">for</span> <span class="n">uptank</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">upstream_tanks</span><span class="p">:</span>
<span class="c1"># recursion (sort of)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">level</span> <span class="o">+=</span> <span class="n">uptank</span><span class="o">.</span><span class="n">Q</span>
<span class="n">uptank</span><span class="o">.</span><span class="n">fill_tank</span><span class="p">()</span></div>
<span class="c1"># our joice of representation for a tank!</span>
<span class="c1"># so that the user knows whats happening</span>
<span class="k">def</span> <span class="nf">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">return</span> <span class="s2">&quot;&lt;type Tank&gt;</span><span class="se">\n</span><span class="s2">tank_id: </span><span class="si">{}</span><span class="se">\n</span><span class="s2">level: </span><span class="si">{}</span><span class="se">\n</span><span class="s2">rate: </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">tank_id</span><span class="p">,</span><span class="bp">self</span><span class="o">.</span><span class="n">level</span><span class="p">,</span><span class="bp">self</span><span class="o">.</span><span class="n">rate</span><span class="p">)</span></div>
<span class="c1"># in order to automatically init our tanks we will have to </span>
<span class="c1"># provide the network structure and attributes of all tanks.</span>
<span class="c1"># a graph would be a good way to go. But we want to keep thinks nice and simple!</span>
<span class="c1"># lets go with some dictionaries, we could write adapters for graphs later...</span>
<span class="c1"># network_structure = {tank_down_i:[tank_up_i,tank_up_(i+1),...],} eg.: {6:[4,5],4:[1,2],5:[3]}</span>
<span class="c1"># attributes = {tank_id:(tank_level, tank_rate),...}</span>
<div class="viewcode-block" id="initiate_tanks"><a class="viewcode-back" href="../../source/tanks.html#tanks.tanks.initiate_tanks">[docs]</a><span class="k">def</span> <span class="nf">initiate_tanks</span><span class="p">(</span><span class="n">network_structure</span><span class="p">,</span> <span class="n">attributes</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;Creates all tanks in a network.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> network_structure : dict</span>
<span class="sd"> Each entry describes the connection from one or more upstream tanks to one downstream tank.</span>
<span class="sd"> Entries must be in this shape:</span>
<span class="sd"> {..., tank_id_downstream: [..., tank_id_upstream_n, tank_id_upstream_np1, ...], ...}</span>
<span class="sd"> attributes : dict</span>
<span class="sd"> Each tank mentioned in the network_structure must have an entry here, specifying its level and rate.</span>
<span class="sd"> Entries must be in this shape:</span>
<span class="sd"> {..., tank_id: (level, rate), ...}</span>
<span class="sd"> </span>
<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> dict</span>
<span class="sd"> Containing all tanks. Dictionary keys are equal to tank_ids.</span>
<span class="sd"> </span>
<span class="sd"> Example</span>
<span class="sd"> -------</span>
<span class="sd"> </span>
<span class="sd"> # define network structure</span>
<span class="sd"> # tank4 &amp; tank5 flow into tank6, tank1 &amp; tank2 flow into tank4, ... </span>
<span class="sd"> &gt;&gt;&gt; network_structure = {&quot;tank_6&quot;:[&quot;tank_4&quot;,&quot;tank_5&quot;],</span>
<span class="sd"> &quot;tank_4&quot;:[&quot;tank_1&quot;,&quot;tank_2&quot;],</span>
<span class="sd"> &quot;tank_5&quot;:[&quot;tank_3&quot;]}</span>
<span class="sd"> # define attributes </span>
<span class="sd"> # tank_3 has a level on 15m and a rate of 0.9/s.</span>
<span class="sd"> &gt;&gt;&gt; attributes = {&quot;tank_1&quot;:(10, 0.0),</span>
<span class="sd"> &quot;tank_2&quot;:(20, 0.06),</span>
<span class="sd"> &quot;tank_3&quot;:(15, 0.9),</span>
<span class="sd"> &quot;tank_4&quot;:(8, 0.3),</span>
<span class="sd"> &quot;tank_5&quot;:(44, 0.5),</span>
<span class="sd"> &quot;tank_6&quot;:(2.5, 0.0)}</span>
<span class="sd"> # generate the network</span>
<span class="sd"> &gt;&gt;&gt; all_tanks = initiate_tanks(network_structure,attributes)</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="c1"># init all tanks without upstream tanks</span>
<span class="n">tanks</span> <span class="o">=</span> <span class="p">{}</span>
<span class="k">for</span> <span class="n">tank_id</span> <span class="ow">in</span> <span class="n">attributes</span><span class="p">:</span>
<span class="n">level</span> <span class="o">=</span> <span class="n">attributes</span><span class="p">[</span><span class="n">tank_id</span><span class="p">][</span><span class="mi">0</span><span class="p">]</span>
<span class="n">rate</span> <span class="o">=</span> <span class="n">attributes</span><span class="p">[</span><span class="n">tank_id</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span>
<span class="n">tanks</span><span class="p">[</span><span class="n">tank_id</span><span class="p">]</span> <span class="o">=</span> <span class="n">Tank</span><span class="p">(</span><span class="n">tank_id</span><span class="p">,</span> <span class="n">level</span><span class="p">,</span> <span class="n">rate</span><span class="p">,</span> <span class="n">upstream_tanks</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span>
<span class="c1"># add upstream tanks</span>
<span class="k">for</span> <span class="n">tank_id</span> <span class="ow">in</span> <span class="n">network_structure</span><span class="p">:</span>
<span class="n">tanks</span><span class="p">[</span><span class="n">tank_id</span><span class="p">]</span><span class="o">.</span><span class="n">upstream_tanks</span> <span class="o">=</span> <span class="p">[</span><span class="n">tanks</span><span class="p">[</span><span class="n">tank_id_up</span><span class="p">]</span> <span class="k">for</span> <span class="n">tank_id_up</span> <span class="ow">in</span> <span class="n">network_structure</span><span class="p">[</span><span class="n">tank_id</span><span class="p">]]</span>
<span class="k">return</span> <span class="n">tanks</span></div>
<span class="c1"># iterate over all tanks and retrieve these levels with id</span>
<div class="viewcode-block" id="get_levels"><a class="viewcode-back" href="../../source/tanks.html#tanks.tanks.get_levels">[docs]</a><span class="k">def</span> <span class="nf">get_levels</span><span class="p">(</span><span class="n">tanks</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;Extracts levels of provided tanks.</span>
<span class="sd"> </span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> tanks : dict</span>
<span class="sd"> Containing tanks you want to extract levels of. Shape {..., tank_id: &lt;tank instance&gt;, ...}</span>
<span class="sd"> </span>
<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> dict</span>
<span class="sd"> Containing levels of all the tanks.</span>
<span class="sd"> </span>
<span class="sd"> Example</span>
<span class="sd"> -------</span>
<span class="sd"> </span>
<span class="sd"> # define tanks or generate networt with the &#39;initiate_tanks&#39; function</span>
<span class="sd"> &gt;&gt;&gt; tanks = {&quot;id_0&quot;: Tank(&quot;id_0&quot;,10,0.1), &quot;id_1&quot;: Tank(&quot;id_1&quot;,1,0.1)}</span>
<span class="sd"> </span>
<span class="sd"> # extract levels</span>
<span class="sd"> &gt;&gt;&gt; levels = get_levels(tanks)</span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">fill_dict</span><span class="o">=</span><span class="p">{}</span>
<span class="k">for</span> <span class="n">tank_id</span><span class="p">,</span> <span class="n">tank</span> <span class="ow">in</span> <span class="n">tanks</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
<span class="n">fill_dict</span><span class="p">[</span><span class="n">tank_id</span><span class="p">]</span> <span class="o">=</span> <span class="n">tank</span><span class="o">.</span><span class="n">level</span>
<span class="k">return</span> <span class="n">fill_dict</span></div>
</pre></div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2019, Christian Foerster
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
\ No newline at end of file
.. tanks documentation master file, created by
sphinx-quickstart on Thu Nov 7 15:49:27 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to tanks's documentation!
=================================
Welcome to this minimal example on how to create your own python package.
.. note:: This is how you can format a note.
.. toctree::
:maxdepth: 2
:caption: Contents:
./source/description
./source/installation
./source/example
./source/issues
./source/tanks
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Description
===========
This is the dream package for all of you water management nerds! You can simulaten water tanks and basic interaction with this!
Examples
========
Leave some example code like ...
**Basic Example**
.. code-block:: python
import matplotlib.pyplot as plt
from tanks.tanks import Tank, initiate_tanks, get_levels
## define network and attributes
network_structure = {"tank_6":["tank_4","tank_5"],"tank_4":["tank_1","tank_2"],"tank_5":["tank_3"]}
attributes = {"tank_1":(10, 0.0),
"tank_2":(20, 0.06),
"tank_3":(15, 0.9),
"tank_4":(8, 0.3),
"tank_5":(44, 0.5),
"tank_6":(2.5, 0.0)}
## generate the network
all_tanks = initiate_tanks(network_structure,attributes)
final_tank = all_tanks["tank_6"] # only the last tank is necessary to run the entire simulation
## simulate
levels = {"tank_{}".format(k):[] for k in range(7)[1:]} # init dict for our level values
for dt in range(100):
tank_levels = get_levels(all_tanks) # retrieve levels for every iteration
for tank_id, level in tank_levels.items(): # save the levels!
levels[tank_id].append(level) #
final_tank.fill_tank() # open valves and let the water through to our last tank!
# checking results
fig, axis = plt.subplots(6,1,figsize = (12,8))
for idx, ax in enumerate(axis):
ax.plot(levels["tank_{}".format(idx+1)])
ax.set_title("tank_{}".format(idx+1))
plt.tight_layout()
plt.show()
.. _installation:
Installation
============
Get the latest version directly from GitLab using pip!
.. code-block:: bash
$ pip3 install git+https://gitlab.switch.ch/sww/tanks.git
Issues
======
**Any trouble with the package?**
Leave me an issue on GitLab_
.. _GitLab: https://gitlab.switch.ch/sww/tanks
tanks
=====
.. toctree::
:maxdepth: 4
tanks
tanks package
=============
tanks.tanks module
------------------