gstlearn 1.10.1
Geostatistics & Machine Learning toolbox
Requires Python: >=3.8

## gstlearn: The Geostatistics &amp; Machine Learning Python Package
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13343742.svg)](https://doi.org/10.5281/zenodo.13343742)

The **gstlearn** Python package is a cross-platform Python package wrapping the [gstlearn C++ Library](https://gstlearn.org). It offers to Python users **all famous Geostatistical methodologies** developed and/or invented by the Geostatistic Team of the [Geosciences Research Center](https://www.geosciences.minesparis.psl.eu/)!

More details for **gstlearn** are available here: https://gstlearn.org

If you need to plot *gstlearn* outputs, you can import *gstlearn.plot* module which is based on *matplotlib*.
  
## References

The *gstlearn* Python package is a Python wrapper of the [gstlearn C++ Library](https://gstlearn.org).

This package contains a copy of [doxy2swig](https://github.com/m7thon/doxy2swig) python script (see LICENSE.doxy2swig in *doc* folder).

The *gstlearn* Python package is a derivative work based on the *swigex0* project: [https://github.com/fabien-ors/swigex0](https://github.com/fabien-ors/swigex0)

## How to cite

When using the *gstlearn* Python Package, please, use this to cite us in any publication or results for which **gstlearn** has been used:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13343742.svg)](https://doi.org/10.5281/zenodo.13343742)

You may be interested in the citation file [gstlearn.bib](https://soft.mines-paristech.fr/gstlearn/gstlearn.bib)

## Installation

For using this Python package you only need Python 3.8 (or higher) (with numpy, pandas and matplotlib) and execute the following command:

```
pip install gstlearn
```

For installing a prerelease version:

```
pip install --pre --force-reinstall gstlearn
```

The `gstlearn.plot` Python module requires additional dependencies,
those can be installed alongside gstlearn with the following command:

``` python
pip install gstlearn[plot]
```

Converting several gstlearn C++ types through `toTL` methods to, e.g.,
Pandas DataFrames also require additional dependencies. These are
available through the `conv` optional dependency group:

``` python
pip install gstlearn[conv]
```

All optional dependencies can be installed with the following command:

``` python
pip install gstlearn[all]
```

## Usage

We refer the reader to this [course page](https://soft.mines-paristech.fr/gstlearn/courses-latest/python/01_gstlearn_start.html) for an introduction and important information about Python gstlearn package.

Simply import the *gstlearn* Python package and its plot module, then enjoy:

```
# Import packages
import numpy as np
import matplotlib.pyplot as plt
import gstlearn as gl
import gstlearn.plot as gp
# Grid size
nx = 60
ny = 30
mygrid = gl.DbGrid.create([nx,ny],[1,1])
# Add a gaussian random field
var = np.random.randn(nx * ny)
mygrid.addColumns(var, "var1", gl.ELoc.Z)
# Display the field
gp.raster(mygrid)
gp.decoration(title="Gaussian random field")
plt.show()
```

Some tutorials (Jupyter Notebooks) are provided in the *demo* directory [here](https://github.com/gstlearn/gstlearn/tree/main/doc/demo/python) and their HTML rendering is provided [here](https://soft.mines-paristech.fr/gstlearn/demos-latest/python/).

Some tests (Python scripts) are available in the [tests](https://github.com/gstlearn/gstlearn/tree/main/tests/py) directory of the *gstlearn* github repository.

**Known caveats**

If you experience the following error while importing *gstlearn* package under Python:

 ```
RuntimeError: module compiled against API version 0x10 but this version of numpy is 0xe
```

... you may need to upgrade numpy:

```
python -m pip install --upgrade numpy
```

## Documentation

The classes and functions documentation is provided with the *gstlearn* C++ library as html files generated by Doxygen. Please, refer to *gstlearn* C++ library API [See here](https://gstlearn.org/) for more details. Only the *public* methods are exported by SWIG and must be considered in the Python package.

## Changelog

Please, look at [CHANGES file](https://github.com/gstlearn/gstlearn/blob/main/CHANGES).

## Development

### Requirements

For building the *gstlearn* Python package, the requirements for compiling *gstlearn* C++ library must be installed beforehand. Then, the following additional tools must be also available:

* SWIG 4 or higher
* Python 3 or higher with *uv* and *numpy* modules installed

If you modified your system, you must reinstall the requirements from scratch following next instructions. You must delete 'gstlearn' existing source folders (if so).

Note :

* In case of issues, see [Important Notes below](#important-notes).

#### Linux (Ubuntu)

1. Install *gstlearn* C++ library requirements for Linux [here](https://github.com/gstlearn/gstlearn#linux-ubuntu)

2. Then, execute the following commands:

````
sudo apt install python3
sudo apt install python3-pip
sudo apt install swig
python3 -m pip install numpy uv
````

#### MacOS

1. Install *gstlearn* C++ library requirements for MacOS [here](https://github.com/gstlearn/gstlearn#macos)

2. Then, execute the following commands (Not tested):

````
brew install python3
brew install swig
python3 -m pip install numpy uv
````

Notes:

* These instructions for MacOS are currently not tested - above packages may not exist

#### Windows

##### Install all tools

1. Install *gstlearn* C++ library requirements for Windows (Microsoft Visual Studio) [here](https://github.com/gstlearn/gstlearn#windows---microsoft-visual-studio)

2. Then, download and install the following tools using default options during installation:

  * Python 3+ [from here](https://www.python.org/downloads) (*Windows installer* [exe] - check 'Add python.exe to PATH' in the first panel)
  * SWIG 4+ [from here](http://www.swig.org/download.html) (*swigwin archive* [zip], archive file to be extracted in a folder of your choice, but not in the *gstlearn* source folder - remind the installation folder, assume it is `C:\swigwin-4.1.0`))

3. Then, install additional Python modules by running following instructions in a command prompt:

````
python -m pip install numpy uv
````

##### Update the Path environment variable

The *Path* environment variable (*System variables*) must be updated to make *swig.exe* available in the batch command line:

1. Follow [this guide](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10) to add *SWIG* installation folders in the *Path* System variable (i.e: `C:\swigwin-4.1.0`)
2. Restart Windows

### Installation from Source

1. For getting the *gstlearn* Python package sources files, just clone the github repository:

````
git clone https://github.com/gstlearn/gstlearn.git
cd gstlearn
````

Next time, you will only need to pull the repository (If you have some local undesirable modifications, you have to revert them and execute the pull, otherwise do not execute `git reset`):

````
cd gstlearn
git reset --hard
git pull
````


2. Then, these instructions will compile and install the *gstlearn* Python package in your usual Python *site-packages* directory. 


#### GCC, Clang, ...

...or any other single configuration compilers:

```
cmake -Bbuild -S. -DBUILD_PYTHON=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --target python_install
```

or for those who prefer a single command line:

```
mkdir -p build & cd build & cmake .. -DBUILD_PYTHON=ON & make python_install
```

or even faster:

```
make python_install
```

#### Microsoft Visual Studio, ...

...or any other multiple configurations compilers:

```
cmake -Bbuild -S. -DBUILD_PYTHON=ON
cmake --build build --target python_install --config Release
```

### Execute Non-regression Tests

The `check*` targets bring some required runtime customization, so do not use the standard *ctest* command for triggering the non-regression tests.

To build and launch non-regression Python tests, you need to execute the following command:

#### GCC, Clang, MinGW, ...

...or any other single configuration compiler:

```
cmake --build build --target check_py
cmake --build build --target check_ipynb
```
    
or even faster:

```
make check_py
make check_ipynb
```

#### Microsoft Visual Studio, ...

...or any other multiple configurations compiler:

```
cmake --build build --target check_py --config Release
cmake --build build --target check_ipynb --config Release
```

### Important Notes

* If your system distribution repository doesn't provide minimum required versions, please install the tools manually (see provider website)
* You may need to reconnect to your session after installing some requirements
* If you plan to generate the documentation, add `-DBUILD_DOC=ON` to the first cmake command above.
* If you don't know how to execute github commands, you may [read this](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
* Using Visual Studio on a Windows where MinGW is also installed may need to add `-G "Visual Studio 16 2019"` in the first command (adapt version).
* The Windows C++ Compiler used must be the same that the one used for compiling Python (Visual C++). Using another compiler than Visual C++ is not supported.
* If you want to build and install the *Debug* version, you must replace `Release` by `Debug` above
* You may need to precise the location of Boost, Eigen3, SWIG, Doxygen, HDF5 or NLopt installation directory. In that case, add the following variables in the first cmake command above:
  * `-DBoost_ROOT="path/to/boost"`
  * `-DEigen3_ROOT="path/to/eigen3"`
  * `-DSWIG_ROOT="path/to/swig"`
  * `-DDoxygen_ROOT="path/to/doxygen"`
  * `-DHDF5_ROOT="path/to/hdf5"`
  * `-DNLopt_ROOT="path/to/nlopt"`


### Remove Installed Package

To uninstall the *gstlearn* Python package, execute following command:

```
python3 -m pip uninstall gstlearn
```

Note : You may need to directly modify your *site-packages* folder by:

* Removing the reference to the old gstlearn package version (see [this topic](https://stackoverflow.com/questions/43177200/assertionerror-egg-link-does-not-match-installed-location-of-reviewboard-at))
* Removing a line which contains gstlearn in the ./easy-install.pth file of the site-packages folder
* Removing all directories starting with *'~stlearn* from the site-packages folder

---

## License

BSD 3-clause

2025 Team gstlearn