.. _dc-lines:

DC Lines
========

A DC line describes a connection for transferring energy between two areas.

.. mermaid::

   flowchart LR
     inext(External json input)
     inth5(Cap_file.h5)
     model(Model / API)
     inext --> model
     model --> MASKENETT.DATA
     model -- "optional" --> inth5
     inth5 --> LTM
     MASKENETT.DATA --> LTM

**Figure 1:** *Dataflow for a DC line, staring from external data, ending in the LTM Core*

Input
-----
The API expects input data to be given as a list of "dclines" objects. Each object must have:

* `name`: string, must match the name given in the `connection` object
* `forward_capacity`: object, described in the :ref:`Capacity chapter <subchapter-capacity>`
* `backward_capacity`, object, described in the :ref:`Capacity chapter <subchapter-capacity>`
* `loss_percentage`: float, given as percentage
* `forward_cost`: float, cost of exchange in forward direction given in percent
* `backward_cost`: float, cost of exchange in backward direction given in percent


Example input:

.. code-block:: json
    :linenos:

    {
        "model":
            {
            "dclines": [
                {
                    "name": "DC_A",
                    "forward_capacity": {
                        "timestamps": [
                            "2024-01-01T00:00:00Z",
                            "2024-01-01T10:00:00Z"
                        ],
                        "values": [[2], [3]]
                    },
                    "backward_capacity": {
                        "timestamps": [
                            "2024-01-01T00:00:00Z"
                        ],
                        "values": [[4]]
                    },
                    "loss_percentage": 2.1,
                    "forward_cost": 2.2,
                    "backward_cost": 2.3
                }
            ],
            "connections": [
                {
                    "from": "numedal",
                    "to": "DC_A"
                },
                {
                    "from": "DC_A",
                    "to": "tev"
                },
            ],
        }
    }

**Figure 2**: Example input for a DC Line. The first object "dclines" describes the line itself, and the second object "connections" describes how the line is connected to the busbars. Note on *line 9 - 10*, a ten hours timestep is defined. This will be converted by the API to an *hourly* resolution in the Cap_file.h5.


Output
~~~~~~~~~~~~~~~~~~~~
The output of the `dcline`` object is written to `MASKENETT.DATA` and optionally `Cap_file.h5`` if the capacity is given as a timeseries. This will be described in the capacity chapter.

Loss and Cost
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The input contains three parameters describing the transmission loss: `loss_percentage` and costs: `forward_cost`` and `backward_cost`. These parameters will be written to "MASKENETT.DATA".

.. _subchapter-capacity:

Capacity
~~~~~~~~~~~~~~~~~~
The `forward_capacity` and `backward_capacity` for a given line is defined by a timeseries with either a constant or several values.
If both `forward_capacity` and `backward_capacity` are given as constants (timeseries with one value), the resulting capacity data will be written to `MASKENETT.DATA`. Else if either one of the capacity timeseries contains two or more values, both time series will be written to `Cap_file.h5` as timeSeries data, with a reference flag in the `MASKENETT.DATA`: ">Capfile".

The API supports any time resolution larger than one hour. The LTM Core however, only supports weekly, daily or hourly time resolution.
The API therefore calculates the time resolution needed, based on the input.
E.g. if the input series has a timestep of 3 days, then a daily resolution will be used.
If a smaller timestep than an hour is provided, a warning will be produced, but the validation will not fail.
If one of the input capacity timeseries is constant, a weekly resolution will be used for that timeseries.