.. 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.

##################################
Implementing an Operating Strategy
##################################

Energy Management Strategies are handled by the Energy Management Systems (EMS).
To implement a new strategy, additions in multiple places are necessary.

Add your strategy to the :mod:`hems_model <eelib.core.control.hems.hems_model>` package
---------------------------------------------------------------------------------------
The convention is to use **one file** and **one class** per strategy, named in the following way.
``hems_<strategy name>.py`` contains the class ``HEMS_<strategy name>``.
E.g. the Operating Strategy for user-based multi-use is abbreviated as "mu_user" from which follows
that the file ``hems_mu_user.py`` contains only the class ``HEMS_mu_user(HEMS)``.

You also have to list your strategy in the package to expose it to the simulator, by adding

.. code-block::

    from .hems_<strategy name> import HEMS_<strategy name>

to the ``hems_model/__init__.py``.

Inherit existing methods and add your behaviour
-----------------------------------------------

Let your class inherit from the base class :class:`~eelib.core.control.hems.hems_model.hems.HEMS`.
You can also inherit from subclasses of the :class:`~eelib.core.control.hems.hems_model.hems.HEMS`
class like :class:`~eelib.core.control.hems.hems_model.hems_default.HEMS_default` to gain access
to their methods and properties.

.. code-block::
   :lineno-start: 13
   :caption: eelib/core/control/hems/hems_model/hems_default.py (12/24)

    class HEMS_default(HEMS):
        """Default strategy for Energy Management System.
        Should be copied and adapted for the use of a specific HEMS concept.
        """

        @classmethod
        def get_valid_parameters(cls):
            """Returns dictionary containing valid parameter types and values.

            Returns:
                dict: valid parameters for this model
            """

            # use parent's parameter list and modify them for this class
            result = HEMS.get_valid_parameters().copy()
            result.update({})
            return result

        def __init__(self, eid: str, step_size: int = 900, **kwargs):
            """Initializes the eELib HEMS default model.

            Args:
                eid (str): name of the entity to create
                step_size (int): length of a simulation step in seconds
                **kwargs: initial values for the HEMS entity
            """

            # call init function of super HEMS class
            super().__init__(eid=eid, step_size=step_size, **kwargs)


Add a ``step()`` function that first calls the :meth:`HEMS.step() <eelib.core.control.hems.hems_model.hems.HEMS.step()>`
and afterwards implement the functionalities of your operating strategy.

.. code-block::
   :lineno-start: 43
   :caption: eelib/core/control/hems/hems_model/hems_default.py (12/24)
   :emphasize-lines: 9

        def step(self, timestep: int):
            """Calculates power set values for each connected component according to the strategy.

            Args:
                timestep (int): Current simulation time
            """

            # execute general processes (aggregation of power values etc.)
            super().step(timestep)

            # from here on: execute strategy-specific processes
            ...

-------------------------

Add the strategy and its input to the ``model_data`` of the scenarios
---------------------------------------------------------------------
If you want to use your strategy in an (example) scenario, add a HEMS in the following way.

.. code-block::
   :lineno-start: 1
   :caption: examples/data_input/model_data_scenario/model_data_building.json (12/24)
   :emphasize-lines: 2-7

    {
        "HEMS_default": {
            "HEMS_default_0": {
                "cs_strategy": "max_p",
                "bss_strategy": "surplus"
            }
        },
        "HouseholdCSV": {
            "HouseholdCSV_0": {
        ...

-------------------------

Add your connections to the ``eelib/model_connections/model_connect_config.json``
---------------------------------------------------------------------------------

Add the data that is **sent out**...

.. code-block::
    :lineno-start: 40
    :caption: eelib/model_connections/model_connect_config.json (12/24)

        "HEMS_default": {
            "PVLib": [
                [
                    "p_set_pv",
                    "p_set"
                ]
            ],
            "PVLibExact": [
                [
                    "p_set_pv",
                    "p_set"
                ]
            ],
            "BSS": [
                [
                    "p_set_storage",
                    "p_set"
                ]
            ],
            ...

... but also to every model, which **data is sent to your HEMS!**

.. code-block::
    :lineno-start: 111
    :caption: e.g. but **not only** the BSS
    :emphasize-lines: 2-15

    "BSS": {
        "HEMS_default": [
            [
                "p_discharge_max",
                "p_min"
            ],
            [
                "p_charge_max",
                "p_max"
            ],
            [
                "p",
                "p"
            ]
        ],
        ...
    },

.. hint::

    Check all entries of ``"HEMS_default":``. You likely need all these connections for your
    strategy as well, extended by your specific additions.

-------------------------

Add the model with its name and (input/output) attributes to the ``META`` of the ``hems_simulator``
---------------------------------------------------------------------------------------------------

.. code-block::
   :lineno-start: 20
   :caption: eelib/core/control/hems/hems_simulator.py (12/24)

    META = {
        "type": "hybrid",
        "models": {

.. code-block::
   :lineno-start: 28

            "HEMS_default": {
                "public": True,
                "params": ["init_vals"],
                "attrs": [
                    "q",
                    "p",
                    "p_max",
                    "p_min",
                    "p_set_storage",
                    ...