gstlearn 0.3.3

Geostatistics & Machine Learning toolbox

Overview

The gstlearn Python package is a cross-platform Python package wrapping the gstlearn C++ Library. It offers to Python users all famous Geostatistical methodologies developed and/or invented by the Geostatistic Team of the Geosciences Research Center!

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.

When using the gstlearn Python Package, please use the citation from doc/gstlearn.bib

This package contains a copy of 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

How to cite

Please, use this to cite us in any publication or results for which gstlearn has been used:

--------------------------------------------------
gstlearn
Geostatistics and Machine Learning toolbox
Copyright © MINES Paris - PSL University
Free download from https://gstlearn.org
--------------------------------------------------

Installation

For using this Python package you only need Python 3 (or higher) (with numpy, pandas and matplotlib) and execute the following command:

pip install -i https://test.pypi.org/simple/ gstlearn

Note: In a close future, gstlearn will be available directly on pypi repository (not the test version)

Usage

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
ax = gp.grid(mygrid)
ax.decoration(title="Gaussian random field")
plt.show()

Some tutorials (Jupyter Notebooks) are provided in the demo directory here.

Some tests (Python scripts) are available in the tests 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 (optional). Please refer to gstlearn C++ library README file for more details.

Changelog

Please, look at CHANGES file.

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 pip, numpy, pandas, scipy, pybind11[global] and matplotlib modules installed
• pypandoc, scikit-sparse, geopandas, plotly and jupyter Python modules [Optional]

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.

Linux (Ubuntu)

1. Install gstlearn C++ library requirements for Linux here

2. Then, execute the following commands:

sudo apt install python3
sudo apt install python3-pip
sudo apt install swig
python3 -m pip install "pybind11[global]" numpy pandas scipy matplotlib

3. Finally, execute the following commands (optional):

sudo apt install pandoc jupyter libsuitesparse-dev
python3 -m pip install pypandoc geopandas plotly jupyter scikit-sparse

MacOS

1. Install gstlearn C++ library requirements for MacOS here

2. Then, execute the following commands (Not tested):

brew install python3
brew install swig
python3 -m pip install "pybind11[global]" numpy pandas scipy matplotlib

3. Finally, execute the following commands (optional):

brew install pandoc jupyter libsuitesparse-dev
python3 -m pip install pypandoc geopandas plotly jupyter scikit-sparse

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 (Windows installer [exe] - check 'Add python.exe to PATH' in the first panel)
• SWIG 4+ from here (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))
• Pandoc from here (msi installer [msi] - simply execute the program)

3. Then, install additional Python modules by running following instructions in a command prompt:

python -m pip install "pybind11[global]" numpy pandas scipy matplotlib

4. Finally, install optional Python modules by running following instructions in a command prompt:

python -m pip install pypandoc geopandas plotly jupyter scikit-sparse

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 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 -H. -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 -H. -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 have to add the directory containing pybind11-config executable to the PATH environment variable
• If you plan to generate the documentation, add -DBUILD_DOXYGEN=ON to the first cmake command above.
• If you don't know how to execute github commands, you may read this.
• 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, SWIG, Doxygen or HDF5 installation directory. In that case, add the following variables in the first cmake command above:
  • -DBoost_ROOT="path/to/boost"
  • -DSWIG_ROOT="path/to/swig"
  • -DDoxygen_ROOT="path/to/doxygen"
  • -DHDF5_ROOT="path/to/hdf5"

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)
• 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 2023 Team gstlearn