.. _valley_fill:


Valley fill Example
===================

In this tutorial, we introduce the concept of groups and group relations to
enable modelling unconformities with GemPy.  By default, gempy-drivers
assumes that all geological features in a history belong to a single group.  This
implies that all the features should be conformable with each other.  In order to
model unconformities, we need to organize the features into groups.

.. figure:: /images/groups/model.png
    :align: center
    :width: 100%

This example demonstrates how to use groups and relations to create two styles of
unconformity with GemPy. We use a valley fill example to demonstrate both a standard
and onlap unconformity. The default setting for all structural groups is an ``erode``
relation.  This means that the conformal features of the group will cut across any
features belonging to an older group.  The ``onlap`` relation specifies that the
features of a group should lap against older groups.  In the valley fill example, we
model a sequence of angled sedimentary layers that have been thrust faulted and
eroded to fill the fault valley.


The key to setting up this problem for GemPy is the organization of groups and group
relations.

.. _groups_and_relations_figure:

.. figure:: /images/groups/group_and_relations.png
    :align: center
    :width: 80%

    *UIJson options for providing group and relation data.*

In order to create the valley fill model, we need to specify 4 separate groups. The
first group contains two conformal tilted layers at the base of the model.

.. figure:: /images/groups/basal_units_mod.png
    :align: center
    :width: 100%

    *Basal units in the valley fill example.*

These layers are then offset by a thrust fault.  Since faults are not conformal to the
younger layers, the fault is placed in its own group.

.. figure:: /images/groups/fault_mod.png
    :align: center
    :width: 80%

    *Fault in the valley fill example.*

In order to have a surface to onlap against, we next need to erode the tilted layers
into a v-shaped valley that follows the hanging wall of the thrust fault and rounds off
the corner of the footwall.  This is accomplished by setting the base of the
``Conglomerate`` unit in its own group.

.. figure:: /images/groups/conglomerate_mod.png
    :align: center
    :width: 80%

    *Erosion of the basal units in the valley fill example.*

Finally, we need to define the group that forces the onlap behaviour of the valley
sediments.  The first unit of the valley sediments has already been defined by marking
the base of the conglomerate.  It is tempting to think of the conglomerate unit as
part of the onlap group since its volume does indeed onlap against the older strata.
Recall, however, that contact points in GemPy mark the base of a unit.  In order for
the conglomerate to unconformably erode the older strata it must be in its own group.
It's actually the younger alluvium surface being marked as onlap that governs the
behaviour of the volume above the conglomerate surface.

.. figure:: /images/groups/fill_mod.png
    :align: center
    :width: 80%

    *Valley fill sediments in the valley fill example.*


Notice that the observations for the valley fill are curved upward near the edges of
the valley to mimic geological processes, but are turned downward within the older
strata.  Since we have the onlap relation, we need to direct the valley fill surface
downward so that we don't end up filling the whole left side of the model.

At this point, we have a set of observations including contacts and orientations for
each element in the history.  Keep in mind that each group needs to have at least one
orientation. For this example, it was important to have contact points close to the
corners of the thrust valley and to provide orientations on either side of the valley
to force the erosion take a sharp angle instead of a broad S-shape.

In the :ref:`Table <onlap_history_table>` below is a summary of the geological units
and their relative ages and the group/relation data that is needed to create our model.

.. _onlap_history_table:

.. table:: Geological units organized by age and group/relation.

    +-----------+------------+---------------+----------+
    | Age       | Group      | Unit/Event    | Relation |
    | Index     |            |               |          |
    +===========+============+===============+==========+
    | 1         | Fill       | Air           | onlap    |
    +-----------+------------+---------------+----------+
    | 2         | Fill       | Alluvium      | onlap    |
    +-----------+------------+---------------+----------+
    | 3         | Erosion    | Conglomerate  | erode    |
    +-----------+------------+---------------+----------+
    | 4         | Fault      | Fault         | fault    |
    +-----------+------------+---------------+----------+
    | 5         | Basal      |  Layer 2      | erode    |
    +-----------+------------+---------------+----------+
    | 6         | Basal      |  Layer 1      | erode    |
    +-----------+------------+---------------+----------+

In gempy-drivers, age and events are provided by the ``Structural elements`` referenced
data.  The age is set by the order in the color table, and can be organized using the
method described in the :ref:`units and events table <history_table>` section of the
general workflow tutorial, or by the data preparation tool provided within Geoscience
ANALYST.

.. figure:: /images/groups/data_prep.png
    :align: center
    :width: 40%

    *Data preparation tool for GemPy. For details, see the user guide.*

To specify the groups and relations, we need to provide two more referenced data objects
to their respective :ref:`fields <groups_and_relations_figure>`.  These are provided per
observation so it is up to the user to ensure that the data is consistent.  That is, each
element is assigned to a single group and group relation.

For our example the observations are organized into four groups.

.. figure:: /images/groups/groups.png
    :align: center
    :width: 80%

    *Structural groups for the valley fill example.*

The valley fill group is marked with an ``onlap`` relation, while the rest are marked as
``erode``.

.. figure:: /images/groups/relations.png
    :align: center
    :width: 80%

    *Group relations for the valley fill example.*

The resulting model is shown below. Thanks to our group and relation input, the valley
sediments are onlapping against the unconformably eroded thrust valley.

.. figure:: /images/groups/basin_fill.png
    :align: center
    :width: 80%

    *Resulting model for the valley fill example.  There are two unconformities at work: 1. The base of the conglomerate unit is unconformably cut across the thrust valley, 2. The alluvium and air surfaces onlap against the faulted and eroded basal units.*