.. _inflow-ltm:

======
Inflow
======

Inflow (and forecast) series are stored in ``historical.h5``. They are standard EMPS-type timeseries. Due to normalization, the unit of the inflow series is not important. The shape is the important part. This makes it possible to use any unit for inflow series. Normalization allows for sharing the inflow series between different DETD modules without requiring any extra storage on disk for the input model.

As a convention, LTM-API expects the inflow series to be in m3/s. However, for the CLI version, it can be anything.

.. figure:: inflow.excalidraw.png
    :alt: Inflow graph
    :align: center

    Fig. 1: Visualization of an arbitrary inflow series

Normalization
=============

A practical example. Given an inflow series with the following shape:

* 10 m3/s for 2 weeks
* 1 m3/s for 8 years, minus the 2 weeks

Over 8 EFI-years, the total number of days is 8 * 52 * 7 = 2912 days.

Total volume is (14 d * 10 m3/s) + (2898 d * 1 m3/s) = 3038 d * m3/s.

The inflow graph will be scaled to:

* (2912/3038) * 10 m3/s = 9.5853 m3/s
* (2912/3038) * 1 m3/s = 0.9585 m3/s

.. note::

    The same calculation can be done with any other unit. Here is the same example using ``m3`` as the unit. The important bit is to have a consistent time unit.

    8-EFI years is (2912 days * 86400 seconds per day) = 251 596 800 seconds

    Volume is (14 d * 86400 s * 10 m3/s) + (2898 d * 86400 s * 1 m3/s) = 262 483 200 m3

    * (251 596 800 s / 262 483 200 m3) * 10 m3/s = 9.5853 m3/s
    * (251 596 800 s / 262 483 200 m3) * 1 m3/s = 0.9585 m3/s



.. figure:: 1m3s-10m3s-example.excalidraw.png
    :alt: Inflow graph
    :align: center

    Fig. 2: Visualization of an inflow series with 2 weeks with 10 m3/s inflow, while the remaining period has 1 m3/s of inflow.


Scaling
=======

Scaling is done by multiplying the normalized inflow series with a scaling factor. A DETD module have 2 scaling factors, one for regulated inflow and one for unregulated inflow. For the API, reservoirs have the scalar ``regulated_inflow_scalar`` and plants have ``unregulated_inflow``.

Utility-methods
===============

``pyltm`` has a submodule ``util``. It contains methods to normalize, scale, and recalculate inflow series.