:orphan:

Plurigaussian Simulation
========================

Plurigaussian simulation (PGS) is used to simulate correlated fields
of categorical data, e.g. lithofacies, hydrofacies, soil types, or
cementitious materials.
In general, we define a categorical rule which dictates the relative
frequency and connectivity of the phases present in the final realisation.
We employ spatial random fields (SRFs) to map to this rule.
This mapping determines the phase of a given point in the simulation domain.
The definition of this rule limits how we can interact with it.
For example, the rule may be defined spatially (e.g. as an image or array)
or via a decision tree. Both forms will be explored in the following
examples, highlighting their differences.
Many PGS approaches constrain the number of input SRFs to match the
dimensions of the simulation domain. This constraint stems from the
implementation, not the method itself.
With a spatial lithotype, we perform bigaussian and trigaussian
simulations for two- and three-dimensional realisations, respectively.
In contrast, the tree-based approach allows an arbitrary number of SRFs,
yielding a fully *pluri*\ gaussian simulation.
This may sound more complicated than it is; we will clarify everything
in the examples that follow.


Examples
--------


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="As a first example, we will create a two dimensional plurigaussian field (PGS). Thus, we need two spatial random fields(SRF) and on top of that, we need a field describing the categorical data and its spatial relation. We will start off by creating the two SRFs with a Gaussian variogram, which makes the fields nice and smooth. But before that, we will import all necessary libraries and define a few variables, like the number of grid cells in each dimension.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_00_simple_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/00_simple`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A First and Simple Example</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we want to try to understand how exactly PGS are generated and how to influence them with the categorical field. First of all, we will set everything up very similar to the first example.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_01_pgs_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/01_pgs`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Understanding PGS</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we will try to understand how we can influence the spatial relationships of the different categories with the lithotypes field. For simplicity, we will start very similarly to the very first example.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_02_spatial_relations_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/02_spatial_relations`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Controlling Spatial Relations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Up until now, we have only used very smooth Gaussian variograms for the underlying spatial random fields. Now, we will combine a smooth Gaussian field with a much rougher exponential field. This example should feel familiar, if you had a look at the previous examples.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_03_correlations_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/03_correlations`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Understanding the Influence of Variograms</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Let&#x27;s create a 3d PGS! This will mostly feel very familiar, but the plotting will be a bit more involved.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_04_3d_pgs_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/04_3d_pgs`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating a Three Dimensional PGS</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In case we have knowledge about values of the PGS in certain areas, we should incorporate that knowledge. We can do this by using conditional fields, which are created by combining kriged fields with SRFs. This can be done quite easily with GSTools. For more details, have a look at the kriging and conditional field examples.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_05_conditioned_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/05_conditioned`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating conditioned PGS</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Plurigaussian fields with periodic boundaries (P-PGS) are used in various applications, including the simulation of interactions between the landsurface and the atmosphere, as well as the application of homogenisation theory to porous media, e.g. Ricketts 2024.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_06_periodic_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/06_periodic`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating PGS with periodic boundaries</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In typical PGS workflows, the lithotype is defined through a spatial rule. A more flexible approach can be taken such that the lithotype is represented as a decision tree. More specifically, this is given as a binary tree, where each node is a decision based on the values of the spatial random fields Sektnan et al., 2024. The leaf nodes are then assigned a discrete value which is given to the cell that is being evaluated. Here, a simple example is provided showing how to use the tree based approach in conducting plurigaussian simulation.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_07_tree_pgs_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/07_tree_pgs`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PGS through decision trees</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In many PGS implementations, the dimensions of the simulation domain often matches the number of fields that are supplied. However, this is not a requirement of the PGS algorithm. In fact, it is possible to use multiple spatial random fields in PGS, which can be useful for more complex lithotype definitions. In this example, we will demonstrate how to use multiple SRFs in PGS. In GSTools, this is done by utilising the tree based architecture.">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_08_multi_field_pgs_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/08_multi_field_pgs`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">From bigaussian to plurigaussian simulation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Let&#x27;s apply the decision tree approach to three dimensional PGS">

.. only:: html

  .. image:: /examples/11_plurigaussian/images/thumb/sphx_glr_09_3d_tree_pgs_thumb.png
    :alt:

  :doc:`/examples/11_plurigaussian/09_3d_tree_pgs`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Three dimensional PGS through decision trees</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/11_plurigaussian/00_simple
   /examples/11_plurigaussian/01_pgs
   /examples/11_plurigaussian/02_spatial_relations
   /examples/11_plurigaussian/03_correlations
   /examples/11_plurigaussian/04_3d_pgs
   /examples/11_plurigaussian/05_conditioned
   /examples/11_plurigaussian/06_periodic
   /examples/11_plurigaussian/07_tree_pgs
   /examples/11_plurigaussian/08_multi_field_pgs
   /examples/11_plurigaussian/09_3d_tree_pgs



.. only:: html

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

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