# EMPS water value intergation with Trident

The Trident to LTM-API intergration enables the conversion of a Trident dataset into a LTM-API dataset for the purpose of running a water value calculation with
the `emps` program.

## Requirements

The CLI requires that the module `pyltm` is available in your Python path. Make
sure that the `pyltm.so` file is available in your `PYTHONPATH`. The file is
available from LTM-API releases.

Also, `emps` must be available within your `PATH`. This program is available
from LTM Core releases.

A LTM license file must be available, and the path to the file must be provided
as a parameter to the CLI.

## CLI usage

### Get usage help

To get usage info for the CLI:

```sh
python -m trident.ltmapi --help
```

### Run a water-value calculation using EMPS

```sh
python -m trident.ltmapi --wv -V \
    --run-config base4partner.trident_run_config.json \
    --logical-model trident_model.json \
    --dataset trident_data.h5 \
    --output-dataset water_values.h5 \
    --ltm-license-file-path licenses/LTM_License.dat
```

## Parameters

| Name                    | Description                                                     |
| :---------------------- | :-------------------------------------------------------------- |
| --wv                    | Do water value calculation.                                     |
| --run-config            | The path to a Trident run config JSON file.                     |
| --logical-model         | The path to a Trident logical model JSON file.                  |
| --dataset               | The path to a Trident dataset h5 file.                          |
| --output-dataset        | The path to a Trident dataset h5 file to store water values in. |
| --ltm-license-file-path | The path to LTM license file.                                   |

## Input data

The provided input must be a complete Trident dataset and run config, provided
as JSON and H5. The dataset will be converted to a LTM-API dataset before the
water calculation is run.

## Output data

The water values are stored in a separate H5 file containing NDArrayTS objects.
The data from the file can be used as input to a Trident run that uses EMPS
water values.

## Conversion details

The simulation period for the EMPS run is chosen to cover the entire Trident
simulation period.

## Current limitations

It is important to note that some features of the water value tool is still lacking. In particular, some details regarding 
the detailed modelling of hydro power, such as hydraulic couplings, are missing. The degree to which these limitations will affect the resulting water values depends on details of the hydro modelling, especially the presence of hydraulic couplings in watercourses.

Also, in this version, a couple of new EMPS features will not be supported. These include the flow based market coupling (FBMC) functionality and the battery functionality. FBMC will however not be used in the water value calculation of LTM (only the simulation phase), but can nevertheless be useful for generating complete LTM datasets from Trident datasets. Batteries, on the other hand, will have an effect on water values if present, so the user is encouraged to remove any batteries from the dataset. Both of these features will be implemented in a future release.

A useful test of the functionality is to load an LTM dataset into Trident and subsequently run the water value calculation. In the generated dataset, one can compare the water value files "VVERD_AREAINDEX.SAMK" with those of the original dataset. Apart from the above mentioned limitations of the tool, it is important to note that differences may also arise from limitations on the LTMV10Loader, which will also be improved upon. In particular, a main price series for an area is not loaded into the Trident dataset, but for the relevant EMPS areas, a default constant price series is produced. Also, the concept of market calibration areas ("grupper" or "samkjoringsomraader" in EMPS) is not considered, which in practice means that all EMPS areas will be assigned the same market calibration area. This is easy to modify in the LTM meny for the generated dataset if need be. If market steps of category 14 exist in the LTM dataset ("gjenkjoepstrinn"), they will be ignored by the LTMV10Loader.