cleaning the readmes for next release and pypi release

README.md

@@ -49,16 +49,27 @@ V, converged, iterations, J = newtonpf(Ybus, V, Sbus, pv, pq, ppci, options)
 
 This function uses the KLU algorithm and a c++ implementation of a Newton solver for speed.
 
-## Installation (from source, recommended)
+## 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)
 - (optional) compile a piece of SparseSuite
 - install the package
 
 ### Important note
-This package relies on the excellent pybind11 package to integrate c++ code into python easily. 
+This package relies on the excellent `pybind11` package to integrate c++ code into python easily. 
 
-So to install lightsim2grid you need pybind and its requirement, which include a working compiler: for example 
+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). 
@@ -83,25 +94,52 @@ git submodule update
 ```
 
 ### (optional) 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. On windows you will still benefit from the
+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
+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.
 
-We only detail the compilation on a system using "make" (so most likely GNU-Linux and MacOS). If you manage to
-do this step on Windows, you can continue (and let us know!). If you don't feel comfortable with this, we
+We only detail the compilation on a system using "make" (so most likely GNU-Linux and MacOS). If you don't feel 
+comfortable with this, either you can ignore it, or you have also the possibility to use the
 provided a docker version. See the next section [Installation Using Docker](#installation-using-docker) 
 for more information.
 
+#### (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 super easy. Just do:
+
 ```commandline
 # compile static libraries of SparseSuite
 make
 ```
+And you are good to go. Nothing more.
+
+#### (optional) option B. Compilation of SuiteSparse using "cmake"
+This works on most platform including MacOS, Linux and Windows.
+
+It requires to install the free `cmake` program and to do a bit more works than for other system. This is why we
+only recommend to use it on Windows.
+
+The main steps (for windows, somme commands needs to be adapted on linux / macos) are:
+1) `cd build_cmake`
+2) `py generate_c_files.py`
+3) `mkdir build` and cd there: `cd build`
+4) `cmake -DCMAKE_INSTALL_PREFIX=..\built -DCMAKE_BUILD_TYPE=Release ..`
+5) `cmake --build . --config Release`
+6) `cmake --build . --config Release --target install`
+
+For more information, feel free to read the dedicated [README](build_cmake/README.md).
 
 ### 2. Installation of the python package
 Now you simply need to install the lightsim2grid package this way, like any python package:

build_cmake/README.md

@@ -1,38 +1,73 @@
 # Information
 First, and most importantly, this project has been largely inspired from: 
-https://github.com/jlblancoc/suitesparse-metis-for-windows
+[suitesparse-metis-for-windows](https://github.com/jlblancoc/suitesparse-metis-for-windows) (we do not include the
+compilation of "metis" because we don't need it for this project).
 
-The goal of the file in this subdirectory is to be able to build suitesparse with cmake. 
-Doing this allows to use the faster KLU solver even on windows based platform.
+The goal of the files in this subdirectory is to be able to build some of the `SuiteSparse` modules with cmake 
+(as opposed to the recommended compilation tool "make" used by this code). This allows to further speed up
+`lightsim2grid` code with the use of the `KLU` linear solver (part of SuiteSparse) which is faster than the default
+linear solver in `Eigen`.
+
+Being able to compile SuiteSparse with cmake allows to benefit the faster `KLU` solver even on windows based platform, 
+where "make" is not a viable option.
 
 # How to build with cmake ?
 
 ## Requirements
 This only works if you have a working `cmake` on your system. `cmake` is a free
-software that you can download and install.
+software that you can download and install. We do not cover this (have a look at https://cmake.org/ 
+for more information)
 
-Of course, you also need to have a working compiler.
+Of course, you also need to have a working compiler (for example microsoft visual studio on windows: 
+https://visualstudio.microsoft.com/vs/features/cplusplus/ )
 
 ## Building SuiteSparse
 You need to `cd` into the correct directory, which is the `build_cmake` subdirectory 
 of this repo (`lightsim2grid/build_cmake`). Then:
 
 1) you need to make sure to have clone the submodule, and in particular the
-  "SuiteSparse" submodule, otherwise this will not work
+  "SuiteSparse" submodule, otherwise this will not work (`git submodule init; git submodule update`)
 2) generate the right sources (small hack to get cmake to work correctly):
-   `python3 generate_c_files.py`
+   `python3 generate_c_files.py` [might require admin rights for now...]
 3) create a "build" subdirectory, and cd there: `mkdir build; cd build`
-4) prepare the compilation with cmake: (on windows) 
+4) prepare the compilation with cmake: (on windows, adapt the command the other platforms) 
   `cmake -DCMAKE_INSTALL_PREFIX=..\built -DCMAKE_BUILD_TYPE=Release ..` 
-   **NB** It is mandatory to install the libraries there, otherwise they will not be detected
-   by the installation script of lightsim2grid
+   **NB** It is mandatory to install the libraries in `..\built`, otherwise they will not be detected
+   by the installation script of `lightsim2grid` and this will be useless
 5) compile the SuiteSparse package: `cmake --build . --config Release`
 6) "install" it (which means: "move the libraries and the header at the right place): 
    `cmake --build . --config Release --target install`
-
-**NB** Some of these files relies on symbolic links "symlink" and you might need root privilege on windows to
+
+## Install lightsim2grid
+
+Now you can install lightsim2grid as usual (see the standard readme for more details):
+1) `cd ..` (to go to the source tree of lightsim2grid)
+2) `py -m pip install .`
+
+## Test the installation is working
+
+To assess whether this works or not you can now, from a python "shell" (really called "repl")
+
+```python
+from lightsim2grid.solver import KLUSolver
+```
+
+If you don't have any **errors** you are good to go.
+
+**NB** you might encounter some **warnings** like 
+"*Numba cannot be loaded. You will gain possibly massive speed if installing it*". To silence this warning, just install
+the python package `numba`. This does not come from lightsim2grid, but is used by pandapower.
+
+## Troubleshoot
+
+Compiling on windows might be tricky. Here are some errors we encounter. Feel free to post a github issue if you
+encounter some not listed there.
+
+### Permission issue (read / write)
+Some of these files relies on symbolic links "symlink" and you might need root privilege on windows to
 build them. We will try to have a workaround for that at some point.
 
-**NB** On windows, the anti virus program (*eg* Avast, Windows Defender, MacAffee, etc.) might cause trouble during
+### Impossible to execute visual c++
+On windows, the anti virus program (*eg* Avast, Windows Defender, MacAffee, etc.) might cause trouble during
 the compilation. You might need to disable it temporarily during the compilation, or to add the proper exception 
 to visual c++, cmake and possibly other programs.