# LightSim2Grid
Provide a fast backend for grid2op using c++ KLU and Eigen librairies. Its primary goal is to serve as a fast
backend for the grid2op platform, used primarily as a testbed platform for sequential decision making in
the world of power system.
See the [Disclaimer](DISCLAIMER.md) to have a more detailed view on what is and what is not this package. For example
this package should not be used for detailed power system computations or simulations.
* [1 Usage](#Usage)
* [1.1. As a grid2op backend (preferred method)](#1-as-a-grid2op-backend-preferred-method)
* [1.2. replacement of pandapower "newtonpf" method (advanced method)](#2-replacement-of-pandapower-newtonpf-method-advanced-method)
* [2 Installation (from pypi official repository, recommended)](#Installation-from-pypi-official-repository-recommended)
* [3 Installation (from source, for more advanced user)](#Installation-from-source-for-more-advanced-user)
* [3.0 Important note](#Important-note)
* [3.1. Retrieve the sources](#1-Retrieve-the-sources)
* [(optional, recommended) Compilation of SuiteSparse](#optional-recommended-Compilation-of-SuiteSparse)
* [option A. Compilation of SuiteSparse using "make"](#optional-option-a-Compilation-of-SuiteSparse-using-make)
* [option B. Compilation of SuiteSparse using "cmake"](#optional-option-b-Compilation-of-SuiteSparse-using-cmake)
* [(optional) Include NICSLU linear solver (experimental)](#optional-Include-NICSLU-linear-solver-experimental)
* [(optional) customization of the installation](#optional-customization-of-the-installation)
* [3.2 Installation of the python package](#2-Installation-of-the-python-package)
* [4. Benchmarks](#Benchmarks)
* [5. Philosophy](#Philosophy)
* [6. Miscellaneous](#Miscellaneous)
* [6.1 Customization of the compilation](#Customization-of-the-compilation)
* [6.2 Profile the code](#Profile-the-code)
* [6.3 Local testing](#Local-testing)
* [6.4 Tests performed automatically](#Tests-performed-automatically)
* [5.5 Known issues](#Known-issues)
## Usage
Once installed (don't forget, if you used the optional virtual env
above you need to load it with `source venv/bin/activate`) you can
use it as any python package.
### 1. As a grid2op backend (preferred method)
This functionality requires you to have grid2op installed, with at least version 0.7.0. You can install it with
```commandline
pip install grid2op>=1.6.4
```
Then you can use a LightSimBackend instead of the default PandapowerBackend this way:
```python3
import grid2op
from lightsim2grid import LightSimBackend
backend = LightSimBackend()
env = grid2op.make(backend=backend)
# do regular computation as you would with grid2op
```
And you are good to go.
### 2. replacement of pandapower "newtonpf" method (advanced method)
It is also possible to use directly the "solver" part of lightsim2grid.
Suppose you somehow get:
- `Ybus` the admittance matrix of your powersystem, for example given by pandapower
(will be converted to a scipy `sparse.csc_matrix` )
- `V0` the (complex) voltage vector at each bus, for example given by pandapower
- `Sbus` the (complex) power absorb at each bus, for example as given by pandapower
- `ref` Ids of the slack buses (added in version 0.5.6 to match recent pandapower changes)
- `pv` list of PV buses
- `pq` list of PQ buses
- `ppci` a ppc internal pandapower test case (or dictionary, is used to retrieve the coefficients associated to each slack bus)
- `options` list of pandapower "options" (or dictionary with keys `max_iteration` and `tolerance_mva`)
You can define replace the `newtonpf` function of `pandapower.pandapower.newtonpf` function with the following
piece of code:
```python
from lightsim2grid.newtonpf import newtonpf
V, converged, iterations, J = newtonpf(Ybus, V, Sbus, ref, pv, pq, ppci, options)
```
This function uses the KLU algorithm and a c++ implementation of a Newton solver for speed.
## Installation (from pypi official repository, recommended)
Since version 0.5.3, lightsim2grid is can be installed like most python packages, with a call to:
`python -m pip install lightsim2grid`
It includes faster grid2op backend and the `SuiteSparse` faster `KLU` solver, even on windows. This is definitely the
easiest method to install lightsim2grid on your system and have it running without too much issues.
Note though that these packages have been compiled on a different platform that the one you are using. You might still
get some benefit (in terms of performances) to install it from your on your machine.
## Installation (from source, for more advanced user)
You need to:
- clone this repository and get the code of Eigen (mandatory for compilation) and SparseSuite (optional, but recommended)
- (optional, but recommended) compile a piece of SparseSuite
- (optional) [experimental] retrieve and get a proper license for the NICSLU linear solver (see https://github.com/chenxm1986/nicslu)
- (optional) specify some compilation flags to make the package run faster on your machine
- install the package
### Important note
This package relies on the excellent `pybind11` package to integrate c++ code into python easily.
So to install lightsim2grid you need `pybind11` and its requirement, which include a working compiler: for example
(as of writing)
gcc (default on ubuntu, version >= 4.8), clang (default on MacOS, version >= 5.0.0) or
Microsoft visual studio (Microsoft Visual Studio 2015 Update 3 or newer).
This readme does not cover the install of such compilers. Please refer to the documentation of
[pybind11](https://pybind11.readthedocs.io/en/latest/) for more information. Do not hesitate to write github issues
if you encounter a problem in installing such compiler (**nb** on windows you have to install
visual studio, on linux of MacOs you might already have a working compiler installed).
### 1. Retrieve the sources
First, you can download it with git with:
```commandline
git clone https://github.com/BDonnot/lightsim2grid.git
cd lightsim2grid
# it is recommended to do a python virtual environment
python -m virtualenv venv # optional
source venv/bin/activate # optional
# retrieve the code of SparseSuite and Eigen (dependencies, mandatory)
git submodule init
git submodule update
```
### (optional, recommended) Compilation of SuiteSparse
SuiteSparse comes with the faster KLU linear solver.
Since version 0.3.0 this requirement has been removed. This entails
that on linux / macos you can still benefit from the faster KLU solver. You can still benefit from the
speed up of lightsim (versus the default PandaPowerBackend) but this speed up will be less than if you manage
to compile SuiteSparse (see the subsection [Benchmark](#benchmark) for more information).
**NB** in both cases the algorithm to compute the powerflow is exactly the same. It is a
Newton-Raphson based method. But to carry out this algorithm, one need to solver some linear equations. The only
difference in the two version (with KLU and without) is that the linear equation solver is different. Up to the
double float precision, both results (with and without KLU) should match.
There are 2 ways to install this package. Either you use "make" (preferred method on linux / unix -- including MacOS) or you use "cmake", which works on all platforms but takes more time and is less automatic (mainly because SuiteSparse
cannot be directly built with "cmake" so we need extra steps to make it possible.)
#### (optional) option A. Compilation of SuiteSparse using "make"
This is the easiest method to compile SuiteSparse on your system but unfortunately it only works on OS where "make" is
available (*eg* Linux or MacOS) but this will not work on Windows... The compilation on windows is covered in the next
paragraph
[(optional) option B. Compilation of SuiteSparse using "cmake"](#\(optional\)-option-B.-Compilation-of-SuiteSparse-using-"cmake")
Anyway, in this case, it's su