Pumps
=====

.. _pump_object:

Pump object
-----------

The modelling of pumps in the LtmApi is defined by a list of **pumps** objects. The parameters in **bold** are required and the rest are optional.
Each object must have:

.. list-table:: Pump parameters
   :header-rows: 1

   * - Parameter
     - Datatype
     - Description
   * - **name**
     - string
     - name of pump object
   * - :ref:`ownership <ownership>`
     - float (optional)
     - Ownership of the station/pump in percent (%)
   * - **average_power**
     - float
     - Average supplied power at mean pumping head and capacity
   * - **pump_capacity**
     - attribute-value pair
     - x: [max, min] pumping head [m]; y: [min, max] discharge [m³/s]. Note the reverse head - discharge relation.
   * - **upper_reservoir_reference_curve**
     - :ref:`txy-label`
     - Reference curve for maximum volume [Mm³]. See :ref:`time_dependent_constraints` and :ref:`ltm_reservoir`.
   * - **lower_reservoir_reference_curve**
     - :ref:`txy-label`
     - Reference curve for minimum volume [Mm³]. See :ref:`time_dependent_constraints` and :ref:`ltm_reservoir`.
   * - unavailable_capacity
     - :ref:`txy-label` (optional)
     - Planned capacity outage for a pump (revision) [MW]
   * - breakdown_unavailable_capacity
     - :ref:`txy-label` (optional)
     - Unforeseen downtimes capacity outage for a pump (havari) [MW]
   * - comment
     - string
     - optional comment

Notes to the pumps objects (see also :ref:`pq_curve_head_variation`):

    - The highest head is the difference between HR of the reservoir where water is pumped into and the inlet of the draft tube. HR is the highest regulated level of water (masl).
    - The smallest head is the difference between LR of the reservoir water is pumped to and the HR of the reservoir where water is pumped from.
    - The pumped discharge for a given head is calculated using linear interpolation.
    - The attribute **average_spill_energy_equivalent** on the object :ref:`api_reservoir` needs to be set with a resonable value to get resonable pumping results. Be sure to compare it to the **discharge_energy_equivalent** on the object :ref:`api_plant`.


.. collapse:: Minimal example for pumps

    .. code-block:: json
        :linenos:

        {
            "name": "pump1_upper",
            "ownership": 100,
            "average_power": 150,
            "pump_capacity": {
                "x": [110, 100],
                "y": [47, 50]
            },
            "upper_reservoir_reference_curve": {
                "timestamps": ["2023-W17", "2023-W40", "2023-W50"],
                "scenarios": [[450, 450, 450]]
            },
            "lower_reservoir_reference_curve": {
                "timestamps": ["2023-W17", "2023-W40", "2023-W50"],
                "scenarios": [[5, 5, 5]]
            }
        }


Below is a minimal example on how to use pumps with revisions (unavailable capacity) on pumps and plants.
Unavailable capacity can be set by attribute **unavailable_capacity** on :ref:`api_plant` or :ref:`pump_object`.
Breakdown unavailable capacity can also be set in a similar manner by the **breakdown_unavailable_capacity** on :ref:`api_plant` or :ref:`pump_object`.

.. collapse:: Minimal example for pumps with unavailable_capacity

    .. code-block:: json
        :linenos:

        {
            "name": "pump1_upper",
            "ownership": 100,
            "average_power": 150,
            "pump_capacity": {
                "x": [110, 100],
                "y": [47, 50]
            },
            "upper_reservoir_reference_curve": {
                "timestamps": ["2023-W17", "2023-W40", "2023-W50"],
                "scenarios": [[450, 450, 450]]
            },
            "lower_reservoir_reference_curve": {
                "timestamps": ["2023-W17", "2023-W40", "2023-W50"],
                "scenarios": [[5, 5, 5]]
            }
            "unavailable_capacity": {
                "timestamps": [
                    "2023-01-02T00:00:00Z",
                    "2024-06-01T00:00:00Z",
                    "2024-12-01T00:00:00Z"
                ],
                "scenarios": [
                    [
                        170,
                        150,
                        0
                    ]
                ]
            }
        }


Pump modelling variants
-----------------------

There two types of pumps, standalone and as a part of the power plant.

Power plant with pumps
~~~~~~~~~~~~~~~~~~~~~~

.. image:: topology.resv-plant-pump.excalidraw.png
    :alt: Upper - Plant w/pump - Lower
    :scale: 50%
    :align: center

When the power plant has a pump, the pump is connected to the plant/bottom resevoir.
The pumped hydropower plant can reverse the turbines and pumps hydro in the reverse direction.

Standalone pump
~~~~~~~~~~~~~~~

.. image:: topology.resv-pump.excalidraw.png
    :alt: Upper - Pump - Lower
    :scale: 50%
    :align: center

With a standalone pump, the pump is connected to the top reservoir.


Example
~~~~~~~

An example is provided here: :ref:`pumps`