.. _pumps:

Pumps in the LtmApi
===================

The modelling of pumps in the LtmApi is defined by the :ref:`pump_object`.

Pumps example
-------------

This example shows how to use pumps in a simulation. A sketch of the system is shown below.
The simulation period is from week 20 in 2023 to week 1 2026 and the historical period is 8 years from 2000 - 2007.

The system contains two areas, **TEV** and **pumpekraft**. The interconnection between them has a capacity of 200 MW in both directions.
The hydropower is located in the pumpekraft area. It contains two pumps, one pump and one pumped power plant, four reservoirs and one hydropower plants.

Pump **pump1_upper** pumps from **rsv_pump_1** to **upper_main**. The pumps average power is 150 MW.

The pumped hydropower plant **extra_plant** is a hybrid hydropower plant and a pump. It can reverse the turbines to pump water from **lower_main** to **extra_rsv**.
The average power is 150 MW at mean pumping head. The pump head is in the range [100, 110] m with corresponding pumping discharge [50, 47] m3/s.

Pumping from the lower reservoir is allowed when the reservoir volume is greater than 5 Mm3 and pumping to the upper reservoir is allowed when the reservoir volume is below 450 Mm3.
The upper_reservoir_reference_curve is at 450 Mm3 from week 17-40-50 2023 and the lower_reservoir_reference_curve 5 Mm3 from week 17-40-50 2023.

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

pump_capacity:
   - x -> [maximum pump head, minimum pump head] (m)
   - y -> [pump discharge at highest pumped head, pump discharge at lowest pumped head] (m3/s)


.. image:: pumpekraft.excalidraw.png
   :alt: Detailed topology with pumps
   :align: center

.. code-block:: json

   "pumps": [
      {
            "name": "pump1_upper",
            "ownership": 100,
            "average_power": 150,
            "pump_capacity": {
               "x": [
                  100,
                  110
               ],
               "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",
                  "2023-04-02T00:00:00Z",
                  "2024-12-01T00:00:00Z"
               ],
               "scenarios": [
                  [
                        0,
                        130,
                        130
                  ]
               ]
            }
      },
      {
            "name": "extra_pump",
            "ownership": 100,
            "average_power": 150,
            "pump_capacity": {
               "x": [
                  100,
                  110
               ],
               "y": [
                  47,
                  50
               ]
            },
            "upper_reservoir_reference_curve": {
               "timestamps": [
                  "2023-W17",
                  "2023-W40",
                  "2023-W50"
               ],
               "scenarios": [
                  [
                        1450,
                        1400,
                        1000
                  ]
               ]
            },
            "lower_reservoir_reference_curve": {
               "timestamps": [
                  "2023-W17",
                  "2023-W40",
                  "2023-W50"
               ],
               "scenarios": [
                  [
                        5,
                        5,
                        5
                  ]
               ]
            },
            "unavailable_capacity_": {
               "timestamps": [
                  "2023-01-02T00:00:00Z",
                  "2023-04-02T00:00:00Z",
                  "2023-06-02T00:00:00Z",
                  "2024-06-01T00:00:00Z",
                  "2024-12-01T00:00:00Z"
               ],
               "scenarios": [
                  [
                        0,
                        25,
                        0,
                        50,
                        75
                  ]
               ]
            }
      }
   ],


The link below takes you to a (static) notebook where LTM-API have been run with a simple topology with pumps.

.. toctree::
   :maxdepth: 1
   :glob:

   pumps-notebook.ipynb

* :download:`pumps.json <pumps.json>`.

.. collapse:: Expand to see full JSON listings.

   .. literalinclude:: pumps.json
      :language: JSON
      :linenos: