.. _objects:

Frequently used objects
=======================

.. _connections:

Connections
-----------

The **connections** object is one of the main objects of the LtmApi. It is used to connect objects. For example:
    - :ref:`busbar` to :ref:`dc-lines`, :ref:`api_hydropower`, :ref:`loads`
    - topology of detailed hydropower modules in :ref:`water-ways`

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

   * - Parameter
     - Datatype
     - Description
   * - **from**
     - string
     - name of object from connection point
   * - **to**
     - string
     - name of object to connection point
   * - comment
     - string
     - optional comment

Click arrow-head to see connections examples below.

.. collapse:: Connections examples

    .. code-block:: json

        "connections": [
            {
                "from": "pumpekraft", // busbar
                "to": "PUMPE_TEV_DC"  // dc_line
            },
            {
                "from": "market_step", // market step
                "to": "pumpekraft"     // busbar
            },
            {
                "from": "PUMPE_TEV_DC", // dc_line
                "to": "tev"             // busbar
            },
            {
                "from": "FLAT",         // load
                "to": "pumpekraft"      // busbar
            },
            {
                "from": "upper_main",   // reservoir
                "to": "pumpekraft"      // busbar
            },
            {
                "from": "upper_main",   // reservoir
                "to": "plant"           // hydropower plant
            }
        ]

.. _busbar:

Busbars
-------

The **busbar** object is a key object used to define the areas of the LTM. The busbar parameters are listed below. The parameters in **bold** are required and the others are optional.

.. list-table:: Busbar Parameters
   :header-rows: 1
   :widths: 30 30 60

   * - Parameter
     - Datatype
     - Unit
   * - **name**
     - string
     - Object/Busbar name
   * - id
     - int
     - Output
   * - water_value_weights
     - :ref:`water_value_weights`
     - Used to change the default scenario weights in the :ref:`water_value_method`.
   * - spill_cost
     - double_optional
     - Spill cost price. **Default value = 0.01**. This value must be the system's lowest price.
   * - load_penalty
     - double_optional
     - Load penalty price. **Default value = 3000**. The value must be the system's highest price.
   * - max_iterations
     - int_optional
     - Max number of iterations for the water value calculation. **Default value = 40**. :ref:`water_value_method`.
   * - precision
     - double_optional
     - Convergence criterion for the water value calculation. **Default value = 0.001**. :ref:`water_value_method`.
   * - feedback_factors
     - :ref:`feedback_factors`
     - Used in the :ref:`calibration`. Default feedback factors are generated automatically by the EMPS. **Feedback factors are very important for the results!**
   * - has_detailed_grid
     - bool
     - Use in Samnett to sort the list of areas with detailed grid.
   * - #comment
     - string_optional
     - Optional comment
   * - metadata
     - json
     - Output

A minimal example is show below (collapsed).

.. collapse:: Burbars examples

    .. code-block:: json

        "busbars": [
            {
                "name": "numedal",
                "spill_cost": 0.001,    // optional
                "max_iterations": 500,  // optional
                "precision": 0.0001     // optional
            },
            {
                "name": "tev"
            },
            {
                "name": "otra"
            }
        ]

.. _common_attributes:

Common attributes
=================

This section gives short descriptions of common attributes not described elsewhere in the LtmApi documentation.

.. _ownership:

ownership
---------

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

   * - Parameter
     - Datatype
     - Description
   * - **ownership**
     - float
     - Optional, the ownership share of the system element in percent. Default value is 100 %.

The production in the power plants is scaled relative to the ownership, only the energy equivalent (discharge curve) is scaled.
However, it is possible to extract the results for the specified ownership of the system or the total system.

.. _inflow_series:

inflow_series
-------------

The **inflow_series** parameters are listed in the table below.

.. list-table:: Inflow time series parameters
   :header-rows: 1

   * - Parameter
     - Datatype
     - Description
   * - **name**
     - string
     - Object name
   * - **series**
     - :ref:`txy-label`
     - An inflow series can be defined and used as a reference on :ref:`api_plant` or :ref:`api_reservoir`. Unit is [m3/s]. See also :ref:`ltm_inflow`.

Examples
^^^^^^^^

Minimal example is provided below (click arrow-head to uncollapse).

.. collapse:: inflow_series

    .. code-block:: json

        "inflow_series": [
            {
                "name": "yearly_inflow_profile",
                "series": {
                    "timestamps": [
                        "1981-01-01T00:00:00Z",
                        "1982-01-01T00:00:00Z",
                        "1983-01-01T00:00:00Z",
                        "1984-01-01T00:00:00Z",
                        "1985-01-01T00:00:00Z",
                        "1986-01-01T00:00:00Z",
                        "1987-01-01T00:00:00Z",
                        "1988-01-01T00:00:00Z",
                    ],
                    "scenarios": [
                        [
                            0.47,
                            0.49,
                            0.40,
                            0.43,
                            0.39,
                            0.46,
                            0.44,
                            0.43
                        ]
                    ]
                }
            }
        ]

Usage example for **plant** is below (click arrow-head to uncollapse).

.. collapse:: plant_inflow_series

    .. code-block:: json

      "plants": [
        {
            "name": "plant",
            "discharge_energy_equivalent": {
                "scenarios": [
                    [
                        0.12
                    ]
                ]
            },
            "pq_curves": {
                "2024-01-01T00:00:00Z": {
                    "y": [
                        0.0,
                        9.89
                    ],
                    "x": [
                        0.0,
                        24.6
                    ]
                }
            },
            "average_unregulated_inflow": 0.6,
            "gross_head": 40.0,
            "tailrace_elevation": 1030,
            "unregulated_inflow_name": "yearly_inflow_profile"
        }
      ]

Similarly, using an **inflow_series** on a **reservoir** object is performed by the **regulated_inflow_name** attribute.