Package: gstlearn
OverviewThegstlearnPython package is a cross-platform Python package wrapping thegstlearn C++ Library. It offers to Python usersall famous Geostatistical methodologiesdeveloped and/or invented by the Geostatistic Team of theGeosciences Research Center!More details forgstlearnare available here:https://gstlearn.orgIf you need to plotgstlearnoutputs, you can importgstlearn.plotmodule which is based onmatplotlib.ReferencesThegstlearnPython package is a Python wrapper of thegstlearn C++ Library.This package contains a copy ofdoxy2swigpython script (see LICENSE.doxy2swig indocfolder).ThegstlearnPython package is a derivative work based on theswigex0project:https://github.com/fabien-ors/swigex0How to citeWhen using thegstlearnPython Package, please, use this to cite us in any publication or results for whichgstlearnhas been used:--------------------------------------------------
gstlearn
Geostatistics and Machine Learning toolbox
Copyright © MINES Paris - PSL University
Free download from https://gstlearn.org
--------------------------------------------------You may be interested in the citation file [gstlearn.bib](https://soft.mines-paristech.fr/gstlearn/gstlearn.bibInstallationFor using this Python package you only need Python 3.8 (or higher) (with numpy, pandas and matplotlib) and execute the following command:pip install gstlearnUsageWe refer the reader to thiscourse pagefor an introduction and important information about Python gstlearn.Simply import thegstlearnPython 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 thedemodirectoryhere.Some tests (Python scripts) are available in thetestsdirectory of thegstlearngithub repository.Known caveatsIf you experience the following error while importinggstlearnpackage 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 numpyDocumentationThe classes and functions documentation is provided with thegstlearnC++ library as html files generated by Doxygen. Please, refer togstlearnC++ library APISee herefor more details. Only thepublicmethods are exported by SWIG and must be considered in the Python package.ChangelogPlease, look atCHANGES file.DevelopmentRequirementsFor building thegstlearnPython package, the requirements for compilinggstlearnC++ library must be installed beforehand. Then, the following additional tools must be also available:SWIG 4 or higherPython 3 or higher withpip,numpy,pandas,scipy,pybind11[global]andmatplotlibmodules installedpypandoc,scikit-sparse,plotlyandjupyterPython 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, seeImportant Notes below.Linux (Ubuntu)InstallgstlearnC++ library requirements for LinuxhereThen, 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 matplotlibFinally, execute the following commands (optional):sudo apt install pandoc jupyter libsuitesparse-dev
python3 -m pip install pypandoc plotly jupyter scikit-sparseMacOSInstallgstlearnC++ library requirements for MacOShereThen, execute the following commands (Not tested):brew install python3
brew install swig
python3 -m pip install "pybind11[global]" numpy pandas scipy matplotlibFinally, execute the following commands (optional):brew install pandoc jupyter libsuitesparse-dev
python3 -m pip install pypandoc plotly jupyter scikit-sparseNotes:These instructions for MacOS are currently not tested - above packages may not existWindowsInstall all toolsInstallgstlearnC++ library requirements for Windows (Microsoft Visual Studio)hereThen, 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 thegstlearnsource folder - remind the installation folder, assume it isC:\swigwin-4.1.0))Pandocfrom here(msi installer[msi] - simply execute the program)Then, install additional Python modules by running following instructions in a command prompt:python -m pip install "pybind11[global]" numpy pandas scipy matplotlibFinally, install optional Python modules by running following instructions in a command prompt:python -m pip install pypandoc plotly jupyter scikit-sparseUpdate the Path environment variableThePathenvironment variable (System variables) must be updated to makeswig.exeavailable in the batch command line:Followthis guideto addSWIGinstallation folders in thePathSystem variable (i.e:C:\swigwin-4.1.0)Restart WindowsInstallation from SourceFor getting thegstlearnPython package sources files, just clone the github repository:git clone https://github.com/gstlearn/gstlearn.git
cd gstlearnNext 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 executegit reset):cd gstlearn
git reset --hard
git pullThen, these instructions will compile and install thegstlearnPython package in your usual Pythonsite-packagesdirectory.GCC, Clang, ......or any other single configuration compilers:cmake -Bbuild -S. -DBUILD_PYTHON=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --target python_installor for those who prefer a single command line:mkdir -p build & cd build & cmake .. -DBUILD_PYTHON=ON & make python_installor even faster:make python_installMicrosoft Visual Studio, ......or any other multiple configurations compilers:cmake -Bbuild -S. -DBUILD_PYTHON=ON
cmake --build build --target python_install --config ReleaseExecute Non-regression TestsThecheck*targets bring some required runtime customization, so do not use the standardctestcommand 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_ipynbor even faster:make check_py
make check_ipynbMicrosoft Visual Studio, ......or any other multiple configurations compiler:cmake --build build --target check_py --config Release
cmake --build build --target check_ipynb --config ReleaseImportant NotesIf 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 containingpybind11-configexecutable to the PATH environment variableIf you plan to generate the documentation, add-DBUILD_DOXYGEN=ONto the first cmake command above.If you don't know how to execute github commands, you mayread 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 theDebugversion, you must replaceReleasebyDebugaboveYou 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 PackageTo uninstall thegstlearnPython package, execute following command:python3 -m pip uninstall gstlearnNote : You may need to directly modify yoursite-packagesfolder by:Removing the reference to the old gstlearn package version (seethis topic)Removing a line which contains gstlearn in the ./easy-install.pth file of the site-packages folderRemoving all directories starting with'~stlearnfrom the site-packages folderLicenseBSD 3-clause
2023 Team gstlearn