:orphan:

Probabilistic Modeling Examples
================================

This gallery contains advanced examples of probabilistic geological modeling and Bayesian
geophysical inversion using GemPy with Pyro probabilistic programming.

Gallery Overview
----------------

These examples demonstrate uncertainty quantification and probabilistic inference methods
for geological and geophysical problems. They leverage PyTorch and Pyro to perform:

* Uncertainty propagation through geological models
* Bayesian inversion of geophysical data
* Joint inversion of multiple data types
* Posterior sampling and credible interval estimation

Why Probabilistic Modeling?
----------------------------

Traditional deterministic geological models provide a single "best guess" interpretation.
Probabilistic modeling offers several advantages:

* **Quantifies uncertainty**: Provides probability distributions over model parameters
* **Incorporates prior knowledge**: Combines geological expertise with data
* **Rigorous inference**: Uses Bayesian statistics for optimal parameter estimation
* **Risk assessment**: Enables decision-making under uncertainty for resource exploration


Prerequisites
-------------

* Completion of Basic Examples gallery
* Understanding of probability and statistics
* Familiarity with Bayesian inference concepts (helpful but not required)
* Installed packages: ``gempy``, ``gempy-probability``, ``pyro-ppl``, ``torch``, ``arviz``

Example Descriptions
--------------------

* **02_error_propagation.py**: Propagate uncertainty in surface point locations through
  a geological model to understand how data uncertainty affects predictions

* **03_error_propagation_dips.py**: Extend uncertainty analysis to orientation data,
  demonstrating the impact of dip and azimuth uncertainties

* **04_gravity_inversion.py**: Full Bayesian inversion of gravity data to infer
  subsurface density distributions and geological parameters

* **05_magnetics_inversion.py**: Magnetic data inversion demonstrating joint
  geophysical-geological inference

* **06_enmap_inversion.py**: Surface lithology inversion using EnMap satellite 
  classifications with Categorical likelihood and ordinal probabilities

* **07_joint_inversion.py**: Joint Bayesian inversion of gravity and EnMap data, 
  demonstrating multi-grid setup and likelihood balance diagnostics

Inference Methods
-----------------

These examples use two main inference approaches:

1. **Variational Inference (VI)**:

   * Fast approximate inference using gradient descent
   * Suitable for large-scale problems
   * Provides mean-field or structured approximations

2. **Markov Chain Monte Carlo (MCMC)**:

   * Accurate sampling from posterior distributions
   * Slower but more robust
   * Uses Hamiltonian Monte Carlo (HMC) and NUTS algorithms

Computational Requirements
--------------------------

Probabilistic modeling is computationally intensive:

* Expect runtime of minutes to hours depending on problem size
* GPU acceleration recommended for large inversions
* Some examples save pre-computed results (``arviz_data_*.nc`` files)

Visualization and Diagnostics
-----------------------------

All examples use ArviZ for posterior analysis:

* Trace plots to check convergence
* Posterior distributions and credible intervals
* Effective sample size and :math:`\\hat{R}` diagnostics
* Posterior predictive checks

.. seealso::
   * `Pyro Documentation <https://pyro.ai>`_ - Probabilistic programming framework
   * `ArviZ <https://arviz-devs.github.io>`_ - Exploratory analysis of Bayesian models
   * `GemPy-Probability <https://github.com/cgre-aachen/gempy_probability>`_ - Integration layer

.. note::
   Some examples may take significant time to run. Pre-computed results are provided
   where possible to enable quick visualization without re-running full inversions.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates uncertainty quantification through error propagation. We perturb a surface point&#x27;s Z-coordinate and propagate the uncertainty through the model.">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_02_error_propagation_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_02_error_propagation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Error Propagation in Geological Models</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates uncertainty quantification by varying dip angles. We add uncertainty to orientation dips and propagate it through the geological model.">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_03_error_propagation_dips_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_03_error_propagation_dips.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Error Propagation for Dip Angles</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial provides a comprehensive walkthrough of Bayesian gravity inversion using the GemPy-Probability framework. We&#x27;ll explore both the theoretical foundations and practical implementation of inferring geological parameters from gravity observations.">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_04_gravity_inversion_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_04_gravity_inversion.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bayesian Gravity Inversion: Complete Workflow</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="What&#x27;s Different from Gravity?">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_05_magnetics_inversion_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_05_magnetics_inversion.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bayesian Magnetic Inversion: TMI Inversion Workflow</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates how to perform Bayesian inversion using surface lithological  classifications (e.g., from EnMap satellite data) as observations. Unlike gravity  inversion which uses continuous values, EnMap inversion deals with discrete categorical labels.">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_06_enmap_inversion_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_06_enmap_inversion.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bayesian EnMap Inversion: Categorical Likelihood and Ordinal Probabilities</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial demonstrates a joint Bayesian inversion combining two disparate data types: 1. Gravity Data: Volumetric measurements sensitive to subsurface density contrasts. 2. EnMap Satellite Data: Surface lithology classifications sensitive to the intersection     of geological units with topography.">

.. only:: html

  .. image:: /examples_probabilistic/images/thumb/sphx_glr_07_joint_inversion_thumb.png
    :alt:

  :ref:`sphx_glr_examples_probabilistic_07_joint_inversion.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Bayesian Joint Inversion: Gravity and EnMap</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples_probabilistic/02_error_propagation
   /examples_probabilistic/03_error_propagation_dips
   /examples_probabilistic/04_gravity_inversion
   /examples_probabilistic/05_magnetics_inversion
   /examples_probabilistic/06_enmap_inversion
   /examples_probabilistic/07_joint_inversion



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_