From 198768153e96ef2d9ebcdc93c2460cc0343d9d17 Mon Sep 17 00:00:00 2001 From: amandamalk0601 Date: Tue, 10 Oct 2023 16:25:17 +0200 Subject: [PATCH] adjusted structure of navigation bar --- .readthedocs.yml | 7 +- docs/custom/custom.css | 4 + docs/custom/module.html.jinja2 | 157 ++++++++++++++++++ docs/extra/About Vessim.py | 11 ++ docs/extra/Concept.py | 26 +++ docs/extra/Getting Started.py | 16 ++ docs/extra/Installation.py | 17 ++ .../pics/CarbonAware_vessim_Aspects.png | Bin .../pics/Experiment_SiL_Design.png | Bin vessim/__init__.py | 70 +------- 10 files changed, 237 insertions(+), 71 deletions(-) create mode 100644 docs/custom/custom.css create mode 100644 docs/custom/module.html.jinja2 create mode 100644 docs/extra/About Vessim.py create mode 100644 docs/extra/Concept.py create mode 100644 docs/extra/Getting Started.py create mode 100644 docs/extra/Installation.py rename docs/{ => output}/pics/CarbonAware_vessim_Aspects.png (100%) rename docs/{ => output}/pics/Experiment_SiL_Design.png (100%) diff --git a/.readthedocs.yml b/.readthedocs.yml index f876d9d6..8b0dbd3c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -9,10 +9,9 @@ build: tools: python: "3.8" commands: - - pip install poetry + - pip install poetry pdoc - poetry config virtualenvs.create false - poetry install --extras "sil analysis" - - pip install pdoc - - pdoc --docformat google -o docs/ vessim/ examples/cosim_example.py examples/sil_example.py + - pdoc --docformat google --template-dir docs/custom/ -o docs/output/ vessim/ examples/cosim_example.py examples/sil_example.py docs/extra/About\ Vessim.py docs/extra/Concept.py docs/extra/Getting\ Started docs/extra/Installation.py - mkdir --parents $READTHEDOCS_OUTPUT/html/ - - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/ \ No newline at end of file + - cp --recursive docs/output/* $READTHEDOCS_OUTPUT/html/ \ No newline at end of file diff --git a/docs/custom/custom.css b/docs/custom/custom.css new file mode 100644 index 00000000..48a444ac --- /dev/null +++ b/docs/custom/custom.css @@ -0,0 +1,4 @@ +/* +This file is empty by default. +Override it in your custom template to provide additional CSS rules. +*/ diff --git a/docs/custom/module.html.jinja2 b/docs/custom/module.html.jinja2 new file mode 100644 index 00000000..512cf6b7 --- /dev/null +++ b/docs/custom/module.html.jinja2 @@ -0,0 +1,157 @@ +{% extends "default/module.html.jinja2" %} +{% block title %}{{ module.modulename }} API documentation{% endblock %} +{% block nav %} + {% block module_list_link %} + {% set parentmodule = ".".join(module.modulename.split(".")[:-1]) %} + {% if parentmodule and parentmodule in all_modules %} + + {% include "resources/box-arrow-in-left.svg" %} +   + {{- parentmodule -}} + + {% elif not root_module_name %} + + {% include "resources/box-arrow-in-left.svg" %} +   + Overview + + {% endif %} + {% endblock %} + + {% block nav_title %} + {% if logo %} + {% if logo_link %}{% endif %} + + {% if logo_link %}{% endif %} + {% endif %} + {% endblock %} + + {% block search_box %} + {% if search and all_modules|length > 1 %} + {# we set a pattern here so that we can use the :valid CSS selector #} + + {% endif %} + {% endblock %} + + {% block nav_index %} + {% set index = module.docstring | to_markdown | to_html | attr("toc_html") %} + {% if index %} +

Overview

+ {{ index | safe }} + {% endif %} + {% endblock %} + + {% block nav_submodules %} + {% if module.submodules %} +

Intro to Vessim

+ + {% endif %} + {% for submodule in module.submodules if is_public(submodule) | trim%} + {% if submodule.name == "analysis" %} +

Utility Modules

+ + {% elif submodule.name == "cosim" %} +

Co-simulation

+ {% elif submodule.name == "sil" %} +

Software-in-the-loop

+ {% endif %} + {% endfor %} + {% if module.submodules %} +

API Documentation

+ +

About Vessim

+ {% endif %} + {% endblock %} + + {% block nav_members %} + {% if module.members %} +

API Documentation

+ {{ nav_members(module.members.values()) }} + {% endif %} + {% endblock %} + + {% block nav_footer %} + {% if footer_text %} + + {% endif %} + {% endblock %} + + {% block attribution %} + + built with pdoc logo + + {% endblock %} +{% endblock nav %} +{% block content %} +
+ {% block module_info %} +
+ {% block edit_button %} + {% if edit_url %} + {% if "github.com" in edit_url %} + {% set edit_text = "Edit on GitHub" %} + {% elif "gitlab" in edit_url %} + {% set edit_text = "Edit on GitLab" %} + {% else %} + {% set edit_text = "Edit Source" %} + {% endif %} + {{ edit_text }} + {% endif %} + {% endblock %} + {{ module_name() }} + {{ docstring(module) }} + {{ view_source_state(module) }} + {{ view_source_button(module) }} + {{ view_source_code(module) }} +
+ {% endblock %} + {% block module_contents %} + {% for m in module.flattened_own_members if is_public(m) | trim %} +
+ {{ member(m) }} + {% if m.kind == "class" %} + {% for m in m.own_members if m.kind != "class" and is_public(m) | trim %} +
+ {{ member(m) }} +
+ {% endfor %} + {% set inherited_members = inherited(m) | trim %} + {% if inherited_members %} +
+
Inherited Members
+
+ {{ inherited_members }} +
+
+ {% endif %} + {% endif %} +
+ {% endfor %} + {% endblock %} +
+ {% if mtime %} + {% include "livereload.html.jinja2" %} + {% endif %} + {% block search_js %} + {% if search and all_modules|length > 1 %} + {% include "search.html.jinja2" %} + {% endif %} + {% endblock %} +{% endblock content %} diff --git a/docs/extra/About Vessim.py b/docs/extra/About Vessim.py new file mode 100644 index 00000000..532b09b6 --- /dev/null +++ b/docs/extra/About Vessim.py @@ -0,0 +1,11 @@ +""" +## Publications + +- Philipp Wiesner, Ilja Behnke, and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)". arXiv:2302.08681 [cs.DC]. 2023. + +## Contact + +Vessim was developed at the research group for [Distributed and Operating Systems (DOS)](https://www.dos.tu-berlin.de), at TU Berlin. + +In case of questions, please reach out to [Philipp Wiesner](https://www.dos.tu-berlin.de/menue/people/wiesner_philipp/). +""" \ No newline at end of file diff --git a/docs/extra/Concept.py b/docs/extra/Concept.py new file mode 100644 index 00000000..930cdf96 --- /dev/null +++ b/docs/extra/Concept.py @@ -0,0 +1,26 @@ +""" +## What can I do with it? + +Vessim allows users to test real applications within a co-simulation testbed composed of domain-specific simulators on energy system components. +The following Figure shows the different aspects of carbon-aware systems that can be investigated through Vessim. + +
+ Carbon Aware Vessim Aspects +
+As depicted in the above Figure, Vessim enables research on various aspects related to the interplay of energy and computing systems. + +- **Energy system composition**: Examine how integrating components like solar panels affects computing systems. Evaluate requirements for energy-autonomous data centers and potential impacts of future technologies. +- **Energy system abstractions**: Vessim simplifies microgrid complexities through simulation, focusing on safety and carbon-aware applications while virtualizing energy systems. +- **Energy system interfaces**: Investigate integration of new components, handling external data, and ensuring secure, controlled access across geo-distributed systems. +- **Carbon-aware applications**: Vessim allows rapid prototyping of carbon-aware computing ideas, offering access to current standards and promoting common dataset use. + +Besides facilitating research, Vessim can support the development and quality assurance of carbon-aware applications and systems. +For example, it can be applied in continuous integration testing, or used to validate software roll-outs in a controlled environment. +Additionally, using Vessim as a digital twin, carbon-aware datacenters can predict future system states, aid decision-making, and assess risks during extreme events like power outages. + + +## How does it work? +
+ Experiment SiL Design +
+""" \ No newline at end of file diff --git a/docs/extra/Getting Started.py b/docs/extra/Getting Started.py new file mode 100644 index 00000000..18f7ae8c --- /dev/null +++ b/docs/extra/Getting Started.py @@ -0,0 +1,16 @@ +""" +## 🚀 + +To ease your start with Vessim, we provide two examples: + +### cosim_example + +The [cosim_example](https://github.com/dos-group/vessim/blob/main/examples/cosim_example.py) runs a fully simulated example scenario over the course of two days. +See `cosim_example` for more details. + +### sil_example + +The [sil_example](https://github.com/dos-group/vessim/blob/main/examples/sil_example.py) is a co-simulation example with software-in-the-loop. +This scenario builds on cosim_example.py but connects to a real computing system through software-in-the-loop integration. This example is experimental and documentation is still in progress. +See `sil_example` for more details. +""" \ No newline at end of file diff --git a/docs/extra/Installation.py b/docs/extra/Installation.py new file mode 100644 index 00000000..e8fd2638 --- /dev/null +++ b/docs/extra/Installation.py @@ -0,0 +1,17 @@ +""" +## ⚙️ + +If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all code and examples at hand: + +``` +$ pip install -e . +``` + + +Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/) +via [pip](https://pip.pypa.io/en/stable/quickstart/): + +``` +$ pip install vessim +``` +""" \ No newline at end of file diff --git a/docs/pics/CarbonAware_vessim_Aspects.png b/docs/output/pics/CarbonAware_vessim_Aspects.png similarity index 100% rename from docs/pics/CarbonAware_vessim_Aspects.png rename to docs/output/pics/CarbonAware_vessim_Aspects.png diff --git a/docs/pics/Experiment_SiL_Design.png b/docs/output/pics/Experiment_SiL_Design.png similarity index 100% rename from docs/pics/Experiment_SiL_Design.png rename to docs/output/pics/Experiment_SiL_Design.png diff --git a/vessim/__init__.py b/vessim/__init__.py index 445b23c8..b365c0f5 100644 --- a/vessim/__init__.py +++ b/vessim/__init__.py @@ -1,6 +1,4 @@ """ -## What is vessim? - Vessim is a versatile **co-simulation testbed for carbon-aware applications and systems**. It lets users connect domain-specific simulators for energy system components such as renewable power generation, energy storage, and power flow analysis with real software and hardware. It is based on [mosaik](https://mosaik.offis.de/), a general-purpose co-simulation framework. @@ -8,70 +6,8 @@ Vessim is in alpha stage and under active development. Functionality and documentation will improve in the next weeks and months. -## What can I do with it? - -Vessim allows users to test real applications within a co-simulation testbed composed of domain-specific simulators on energy system components. -The following Figure shows the different aspects of carbon-aware systems that can be investigated through Vessim. - -
- Carbon Aware Vessim Aspects -
-As depicted in the above Figure, Vessim enables research on various aspects related to the interplay of energy and computing systems. - -- **Energy system composition**: Examine how integrating components like solar panels affects computing systems. Evaluate requirements for energy-autonomous data centers and potential impacts of future technologies. -- **Energy system abstractions**: Vessim simplifies microgrid complexities through simulation, focusing on safety and carbon-aware applications while virtualizing energy systems. -- **Energy system interfaces**: Investigate integration of new components, handling external data, and ensuring secure, controlled access across geo-distributed systems. -- **Carbon-aware applications**: Vessim allows rapid prototyping of carbon-aware computing ideas, offering access to current standards and promoting common dataset use. - -Besides facilitating research, Vessim can support the development and quality assurance of carbon-aware applications and systems. -For example, it can be applied in continuous integration testing, or used to validate software roll-outs in a controlled environment. -Additionally, using Vessim as a digital twin, carbon-aware datacenters can predict future system states, aid decision-making, and assess risks during extreme events like power outages. - -## How does it work? -
- Experiment SiL Design -
- -## ⚙️ Installation - -If you are using Vessim for the first time, we recommend to clone and install this repository, so you have all code and examples at hand: - -``` -$ pip install -e . -``` - - -Alternatively, you can also install our [latest release](https://pypi.org/project/vessim/) -via [pip](https://pip.pypa.io/en/stable/quickstart/): - -``` -$ pip install vessim -``` - - -## 🚀 Getting started - -To ease your start with Vessim, we provide two examples: - -### cosim_example - -The [cosim_example](https://github.com/dos-group/vessim/blob/main/examples/cosim_example.py) runs a fully simulated example scenario over the course of two days. -See `cosim_example` for more details. - -### sil_example - -The [sil_example](https://github.com/dos-group/vessim/blob/main/examples/sil_example.py) is a co-simulation example with software-in-the-loop. -This scenario builds on cosim_example.py but connects to a real computing system through software-in-the-loop integration. This example is experimental and documentation is still in progress. -See `sil_example` for more details. - - -## Publications - -- Philipp Wiesner, Ilja Behnke, and Odej Kao. "[A Testbed for Carbon-Aware Applications and Systems](https://arxiv.org/pdf/2306.09774.pdf)". arXiv:2302.08681 [cs.DC]. 2023. - -## Contact - -Vessim was developed at the research group for [Distributed and Operating Systems (DOS)](https://www.dos.tu-berlin.de), at TU Berlin. +**Getting started with Vessim** + - + - -In case of questions, please reach out to [Philipp Wiesner](https://www.dos.tu-berlin.de/menue/people/wiesner_philipp/). """