.. eELib documentation master file, created by
   sphinx-quickstart on Fri Feb 10 16:19:56 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.
   Author: elenia@TUBS
   Copyright 2024 elenia
   This file is part of eELib, which is free software under the terms of the GNU GPL Version 3.

Welcome to eELib's documentation!
=================================

The **eELib** (**e**\lenia **E**\nergy **L**\ibrary) is the software tool for simulations concerning
**future power systems for prosumers**. The library with its functionalities and models can be used
for various simulative investigations regarding research or current challenges in the field of a
distributed electrical power system.

The goal of the eELib is creating a model library that is suitable for solving energy-related questions
around prosumers (consumers that are now also producing energy). This includes, among
other things, the …

- … creation and consideration of different **energy supply scenarios** (on building, district and grid
  level, among others with different penetration levels of distributed facilities like PV).
- … comparison of different **operating strategies for energy management systems**, including e.g.
  variable tariffs, multi-use concepts, operator models or schedule-based flexibility.
- … investigation of the **impacts and interactions** of prosumer households (e.g., sector coupling and
  electrification) **with the power grid** to identify violations of grid limits.
- … calculating the **economic values of different use cases and strategies** for components and systems.
- … investigation of innovative marketing strategies of market players in the spot and balancing **power
  markets**.


Getting Started for Using the eELib
===================================

The eELib will soon be made available to install via `PyPI - the Python Package Index <https://pypi.org/>`_.
Until then, you need to use the installation via its `Gitlab Page <https://gitlab.com/elenia1/elenia-energy-library>`__.
The procedure for this is explained in the following subsection.


Getting Started for Contributing to the eELib
=============================================

When working with the eELib, you should consider this documentation pages and the
`Gitlab Repository <https://gitlab.com/elenia1/elenia-energy-library>`_. The documentation gives a
short overview of what the eELib is, how it is set up and how it can be used.
The short introduction is provided by this start page and the :doc:`About eELib <about_eelib>` section.
Afterwards you should have a look at the :doc:`Wiki <wiki/index>` part of the documentation. It
provides info about how to

  - Set up your environment to work with the eELib via an
    :doc:`Installation Guide <wiki/installation_setup>`,
  - Work with :doc:`Git <wiki/git_workflow>` (version management control) and its different operations
  - :doc:`Set up a scenario <wiki/conf_scenario_with_excel>` and
    :doc:`run a simulation <wiki/setup_run_sim>`
  - Add new implementations like :doc:`models <wiki/config_model>`

Additionally, the section :doc:`API reference <autoapi/index>` provides an overview of the setup of
the eELib and its models and gives explanations to the classes and their methods, which are provided
by the docstrings in the source code.

One major thing to know for working with and using the eELib is that we are **using a co-simulation
tool** (`mosaik <https://mosaik.offis.de/>`_) to run simulations, as the eELib itself just provides
the implementation of models and no configuration to run a simulation. The sense of this is further
explained in the :doc:`About eELib <about_eelib>` section on *Coupling With mosaik*. Additionally,
there is a short :doc:`mosaik introduction <wiki/mosaik>` and the linking of tutorials using mosaik
given in the Wiki.

For contributing to the eELib, it is useful to follow these steps:
------------------------------------------------------------------

#. :doc:`Create a local copy of the Git repository <wiki/installation_setup>` on your computer.
   Afterwards, make sure the eELib folder exists on your local hardware and the test scenarios can
   be executed without any error.
#. Get familiar on how you can :doc:`use Git for version control <wiki/git_workflow>`.
#. Read the :doc:`About eELib <about_eelib>` section to get a sense of the structure of the eELib
   and how simulations are carried out.
#. Familiarize with the test scenarios (for one single building and a small 8-bus low-voltage grid):

   - For running a simulation, we need four files: A **scenario script** and the scenario data, which is
     divided into a **model data** file, the **model connections** and a **grid file**. Additionally,
     corresponding input data like files for the input of pv generation or a household baseload need
     to be provided. The setup of these files and their combination is more deeply explained in the
     Wiki page on :doc:`Running a simulation <wiki/setup_run_sim>`.

#. You should additionally have a look at a simulator and model for an exemplary model type. The
   idea of using simulators and models separately is explained in the
   *Coupling With mosaik and Architecture of a Simulation*``* part of the
   :doc:`About eELib section <about_eelib>`. You can find further information on
   :doc:`Simulators <wiki/config_simulator>` and :doc:`Models <wiki/config_model>` and how they are
   set up in the Wiki pages. This should give you the relevant information to implement your own or
   advance existing models.
#. If you are interested in setting up (implementing) a new operating strategy for energy management
   systems (EMS), you should have a look at the explanations on
   :doc:`Implementing a new EMS strategy <wiki/implement_strategy>`. Following the steps mentioned
   there you should be able to set up your operating strategy and integrate it into your simulation.


.. toctree::
   :maxdepth: 1
   :caption: Contents
   :hidden:

   about_eelib
   wiki/index
   autoapi/index
   disclaimer_authors

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`