Spatial modeling using machine learning concepts

📖 Documentation — the API reference and the design records, published with each release.

Geoscientific data is becoming increasingly larger and more complex. Multiple variables, structural constraints, etc. are becoming the norm rather than the exception.

Conventional modelling approaches are very labour-intensive, subjective, and hard to reproduce. CAD-drawn orebodies, variograms, pre- and post-processing steps can result in workflows so complicated that even professionals can become lost within their own work. geoML is being designed to simplify geomodelling and empower the user with advanced machine larning tools that respect geology.

This package contains machine learning models specialized in spatial interpolation and smoothing with calibrated confidence intervals. Current functionality includes:

• Gaussian process modeling in 1D, 2D, and 3D, with anisotropy ellipsoid;
• Variational Gaussian process for classification and multivariate modeling;
• Support for compositional data;
• Support for directional data (structural geology measurements, scalar field gradients, etc.);
• Support for implicit modelling with boundary data (points lying in the boundary between two rock types);
• Deep learning for non-stationary modeling;
• Exports results to PyVista format;
• Back-end powered by TensorFlow.

Installation

pip install git+https://github.com/italo-goncalves/geoML

Python 3.10 or newer. The dependencies — NumPy, SciPy, pandas, scikit-learn, scikit-image, TensorFlow, TensorFlow Probability, Zarr, xarray, dask, PyVista, VTK, Matplotlib, Plotly, ezdxf and openpyxl — are declared with their lower bounds in pyproject.toml and installed with the package. pip install -e .[dev] adds what the documentation and the type check need.

Examples

The following notebooks demonstrate the capabilities of the package (if one of them seems broken, it is probably going through an update).

• Sunspot cycle prediction
• 3D classification
• Potential field modeling using only directional data
• Gold modeling with auxiliary variables
• Dealing with faults (experimental)

Learning materials

• geoML short course presentation
• Notebook 01 - covariance functions
• Notebook 02 - Gaussian process
• Notebook 03 - 2D modelling with warping
• Notebook 04 - multivariate modelling
• Notebook 05 - implicit modelling
• Notebook 06 - gradients
• Notebook 07 - deep Gaussian process
• Notebook 08 - multivariate non-stationary modelling
• Notebook 09 - compositional data

Using geoML with Claude Code

This repository ships a Claude Code plugin carrying the package's own working knowledge: the object model, the module layout, the modelling workflow, and the notebook conventions the examples above follow. It means Claude writes geoML code the way geoML is meant to be written, rather than guessing an API from its name.

Install it from within Claude Code:

/plugin marketplace add italo-goncalves/geoML

/plugin install geoml@geoml

Claude then loads it by itself whenever a task involves geoML, or you can invoke it directly with /geoml:geoml. It costs about 200 tokens per session until it is used.

References

• 2020 - Sunspot Cycle Prediction Using Warped Gaussian Process Regression
• 2021 - A machine learning model for structural trend fields
• 2022 - Learning spatial patterns with variational Gaussian processes: Regression
• 2023 - Variational Gaussian processes for implicit geological modeling
• 2024 - Moho depth model of South America from a machine learning approach
• 2025 - Uncertainty Propagation in Deep Gaussian Process Networks (open access)
• 2026 - Scalable variational Gaussian process framework for implicit geological modelling and compositional grade interpolation (open access)

External links

• Gaussian process book
• A Visual Exploration of Gaussian Processes
• Interactive Gaussian Process Visualization

Licensing

geoML is available under a dual license model:

Open-Source License (GPL v3)

geoML is free and open-source software licensed under the GNU General Public License v3.0. Under this license, you may use, study, modify, and distribute geoML at no cost, provided that any software incorporating geoML is also distributed under the GPL v3. This applies to academic research, personal projects, and any open-source work.

Commercial License

If you wish to integrate geoML into a proprietary or closed-source product — such as commercial geostatistical software, consulting workflows, or any application whose source code will not be made publicly available under the GPL — a separate commercial license is required. The commercial license grants you the right to use geoML without the copyleft obligations of the GPL. Typical use cases for a commercial license include:

• Embedding geoML in commercial mining, oil & gas, or environmental software
• Using geoML in paid consulting deliverables distributed as closed-source tools
• Integrating geoML into a SaaS platform

To inquire about commercial licensing terms and pricing, please fill this contact form.