# Introduction

## Overview

This document describes core architecture concepts and APIs required to operate Trident through its Python API.

The Trident model is a simulator that repeatedly solves optimization problems in the form of linear programming (LP) problems. The LP problems cover a decision period, of user-defined length, typically being a week or a day. We refer to this LP problem as the stage decision problem. 

Users must provide a data set, a representation of the physical system and specify for which period one wishes to simulate. In addition, Trident is designed to be highly flexible in terms of what is simulated. It uses a modular architecture, where modules can be swapped in and out depending on what functionality the user requires. During the set up of each decision problem, each module will add its own contribution to the LP problem, and after it is solved retrieve its respective results.

## System organization

Trident consists of the following components:

- **ngltm-timeseries** - Time series data structures
- **trident** - Core modules and algorithms.
- **trident-extras** - Execution context, state management, paralellization, etc.
- **ngltm-shyft** - Shyft integration of Trident.
- **trident-doc** - Source code for this document.
- **trident-conan-recipes** - Conan recipes for third party libraries used by trident.

The following figure shows the dependencies between the components:

[![components](./components.drawio.png)](./components.drawio.svg)

### Python packages

The following python packages are created, including python extensions:

- **trident**
- **trident-extras**
- **ngltm-shyft**

### C++ packages

The C++ packages containing libraries and headers are created:

- **ngltm-timeseries**
- **trident**
- **trident-extras**

Header files exported in Trident are found under `trident/`, and belong to the C++
namespace `trident::`.

### Unit tests

Unit tests are found in two forms; Python and C++ based unit tests. Python unit
tests are found under `./<pymodule name>/test`, and C++ unit tests are found under `./test`.

## Getting started

### Installation

The Trident system is distributed as a set of Python packages (wheels), containing the C++ binary files and Python code. The wheels are available at [ngltm.no/software](https://www.ngltm.no/software/).

#### Prerequisits

* Python with pip or Anaconda (version 3.11)
* cplex binaries (Optional)
* tqdm (Optional for displaying progress bars)
* ipywidgets (Optional for displaying progress bars in a Jupyter Notebook)

#### Procedure

To install, download the files and install them using the `pip install` command.

> *Note*: It is recommended to create and activate a virtual environment first. See [here](https://docs.python.org/3/library/venv.html).

```Shell
pip install trident-<version>-<platform>-<architecture>.whl
pip install trident-extras-<version>-<platform>-<architecture>.whl
```

#### Installing with Cplex

To use Trident with Cplex, the Cplex binary file (cplex.dll on windows or libcplex.so on linux) must be available.

##### Windows

If Cplex studio 2010 is installed, make sure the environment variable "CPLEX_STUDIO_DIR201" is set. Otherwise, you can set the `CPLEX_DLL_PATH` environment variable to the directory containing the dll.

A third option is to add the location of `cplex2010.dll` in the user script, before including Trident using:
```python
import os

os.add_dll_directory(path_to_cplex_dll)

# import trident afterwards

```
##### Linux

To use Cplex on Linux, make sure that the `LD_LIBRARY_PATH` environment variable includes the location of `libcplex2010.so`.

#### Test the installation

To test the installation, run:

```Shell
python -m trident.test
```

### Jupyter notebook

A Jupyter Notebook is a web-based interface for processing and presenting live code.

![interface](./jupyter_interface.png)

In the Trident project, notebooks are used for documentation, in the form of example code, and as a platform to present demos.

A full guide on how to install and run the notebook can be found [here](https://jupyter.org/install). In order to run the notebook, the Trident python package must also be installed, as described above.

(example_notebooks)=
## Example code

Practical examples for how to use Trident can be found here: [ngltm.no/documentation/notebooks](https://www.ngltm.no/documentation/notebooks/).

> *Note*: If you are a first time user, we highly recommend you to look through the `basic_run_trident.ipynb` and `domain_example.ipynb`.