.. _loads:

======================
Loads
======================

A **load** in the LTM represents a contract granting the right to buy or sell power. Multiple such contracts can be defined for each busbar in the model.

1D vs 2D Load
-------------

The `capacity` of a load can be defined as either:

- **1D**: A single time series with one scenario.
- **2D**: Multiple time series with several scenarios, one per historical year.

For 2D data, the number of scenarios must exactly match the number of historical years in the model. The time series must start at the beginning of the dataperiod and fully cover the period.

In EMPS, all loads must use the same format—either all 1D or all 2D. However, the API supports mixed input. If at least one load uses a 2D format, any 1D loads will be automatically converted to an equivalent 2D structure internally.

Output Files
------------

The API generates `.enmd` files for each busbar, each containing a load entry (group 16). The content and format of the capacity data depend on its resolution:

- If the capacity is constant or has at most **weekly resolution**, and all loads in the area are 1D, the capacity series will be written directly in the `.enmd` file.
- If any load has **higher resolution** (e.g., daily or hourly) or is **2D**, the `.enmd` will contain references, and the actual time series data will be stored in `tidsserieData.h5`.

Input Parameters
----------------

To define a `Load` in the API, the following fields may be provided:

**Common fields**:

- **name** (*string*): The name of the load. Case-insensitive.
- **id** (*string*): A unique identifier.
- **comment** (*string*): Optional descriptive text.

**Attributes**:

- **capacity** (*Txy*): A time series of load capacity. This field determines the enmd category which is calculated internally in the API.

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

Each load must be connected to a **busbar**.

Example Usage
-------------

Below is an example of a 2D load with three scenarios and weekly resolution:

.. code-block:: json

    {
        "#comment": "ENMD group 16",
        "name": "load1",
        "capacity": {
            "timestamps": [
                "2024-01-00T00:00:00Z",
                "2024-01-08T00:00:00Z",
                "2024-01-15T00:00:00Z"
            ],
            "scenarios": [
                [100.0, 101.1, 102.2],
                [200.0, 201.1, 202.2],
                [300.0, 301.1, 302.2]
            ]
        }
    }

Notebook Example
----------------

For a complete, runnable example of how to define a load in the model using pyltmapi, see the following Jupyter notebook:

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

   ../guides/loads/load-2d-run.ipynb

Downloads
---------

You can download the full input model file used in the example here:

* :download:`load-2d.json <../guides/loads/load-2d.json>`

Notes
-----

- The `capacity` field can be either 1D or 2D. If 2D, it must match the number of historical years.
- All time series must fully align with the dataperiod.