pommes 0.3.3
Planning and Operation Model for Multi-Energy Systems
Requires Python: <4.0.0,>=3.10

# POMMES - Planning and Operation Model for Multi-Energy Systems

POMMES is an open source framework to model investment pathways in multi-energy systems.
The framework enables to minimise the system costs to meet the energy services demand by modelling the investment
and operating costs of energy conversion, storage and transport technologies.

**Documentation**:
The complete documentation for POMMES (methodology, examples and API) is available at [DOCS](https://pages.persee.minesparis.psl.eu/energy-alternatives/pommes/)

## Installation

### Prerequisites

- Install [Miniconda3 distribution](https://docs.conda.io/en/latest/miniconda.html)

Choose the installation depending on your platform.

To integrate conda in PowerShell, run in the `Anaconda Prompt`:
- On Windows
    ```bash
    $ conda init powershell
    ```

- On Linux
    ```bash
    $ conda init bash
    ```

### Python environment creation
Ensure Conda is initiated in your shell: see [prerequisites](#prerequisites) if needed.

Download the file
[`environment.yaml`](https://git.persee.mines-paristech.fr/energy-alternatives/pommes/-/blob/main/environment.yaml).

To create the environment, run in the file directory:

```bash
$ conda env create -f environment-all.yaml
```


### Pycharm (optional, recommended)

Using python [Pycharm](https://www.jetbrains.com/pycharm/) IDE
which can be downloaded from this [webpage](https://www.jetbrains.com/pycharm/download/?section=windows)
facilitates the interaction with the tool.


#### Setting the interpreter in Pycharm

You can set this environment as python interpreter in Pycharm using:

Settings > Project: pommes > Python interpreter > Add interpreter > Add local interpreter ...
![add_interpreter.png](docs/source/_static/add_interpreter.png)

Then:

Conda Environment > Load Environments > Use existing environment > pommes-env
If needed, update the conda executable path:

`[your installation directory]\miniconda3\condabin\conda.bat`.

![pommes-env.png](docs/source/_static/pommes-env.png)


### Contributing

All contributions are welcome with merge requests. Use pre-commit for code formatting.

```bash
$ pre-commit install
```

### Solver installation

Solving optimisation model with linopy allows to interact easily with multiple solvers.
Check [linopy documentation](https://linopy.readthedocs.io/en/latest/prerequisites.html)
to get all compatible solvers.

[HiGHS](https://www.maths.ed.ac.uk/hall/HiGHS/) solver is installed in the virtual environment
with the `highspy` package.
However, for the sake of performance, here is a short tutorial to get the commercial solver
[Gurobi](https://www.gurobi.com/) which presents much better resolution speed, and which is free for academic use.

#### Gurobi

Gurobi is already installed in the python virtual environment with the `gurobipy` package.
To generate a named academic license, visit the [gurobi license webpage](https://portal.gurobi.com/iam/licenses/list)
and sign in with your academic e-mail address.

You will get a license token.

Then go to the [download page of the license tool packages](https://support.gurobi.com/hc/en-us/articles/360059842732)
You can then run the `grbgetkey` script and copy-paste your token in the console.

If you want to change the default directory of the `gurobi.lic` file,
make sure that the corresponding environment variable is modified.

## Getting started

The example study is stored in `study\test_case`. Data stored in `study\test_case\data`
and the import is described in the `study\test_case\config.yaml` file.

Try to run the `run_study.py` first to get some results.

Explore the results in the `study\test_case\output` directory structured as follow:

```
output
   |-- ref_(suffix?)
         |-- constraints
            |-- annualised_totex_def.csv
            |-- ...
         |-- plots
            |-- energy_balance
               |-- 2020_electricity.html
            |-- energybalance.html
         |-- variables
            |-- annualised_totex.csv
            |-- ...
         |-- dual.nc
         |-- input.nc
         |-- model.nc
         |-- objective.csv
         |-- solution.nc
```
Explore it!

- `constraints/` gathers the lagrangians of the constraints
- `variables/` the solution
- and some visualisations are available in `plots/`.

## Run your own scenario

### Inputs
To run your own study, copy-paste the `test_case/` study, rename it with your study name.
Let's take **study_name** for the example.
```
study
   |-- test_case
         |-- data
            |-- availability.csv
            |-- ...
         |-- config.yaml
   |-- study_name
         |-- data
            |-- availability.csv
            |-- ...
         |-- config.yaml
```
You can now change the inputs value of your scenario.

Waiting for an exhaustive description of the inputs, here are some guidelines:
- all power units are in MW
- all energy units in MWh
- storage assets are considered as energy storage (not power or methane or hydrogen storage)
  - **in** (**keep**) represents the resource needed to charge (keep) 1 MWh of energy
  - **out** represents the resource produced by the storage when discharging 1 MWh of energy

### Run the optimisation

Follow the workflow of the `study\test_case\run_study.py` script with the right study_name (and potentially change the solver)

Enjoy !