:orphan:

Examples
========

On this page you will find practical examples of using various features of
how ogstools can be used. Different stages of the simulation workflow are
covered.

.. toctree::
   :maxdepth: 3

.. contents:: Contents
   :local:
   :depth: 3



.. raw:: html

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

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Quick start
===========

In this section you will find examples helping you use the most commonly used
features of ogstools: reading data, plotting and simple post-processing

.. toctree::
   :maxdepth: 3



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Read mesh from file (vtu or xdmf) into pyvista mesh">

.. only:: html

  .. image:: /auto_examples/howto_quickstart/images/thumb/sphx_glr_plot_meshseries_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_quickstart_plot_meshseries.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read mesh from file (vtu or xdmf) into pyvista mesh</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The following example from the ogs benchmark collection is used for the stress analysis:">

.. only:: html

  .. image:: /auto_examples/howto_quickstart/images/thumb/sphx_glr_plot_solid_mechanics_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_quickstart_plot_solid_mechanics.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Stress analysis</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Pre-processing: preparing the simulation
========================================

This section shows how to create bulk meshes for the OGS simulation.
To complete the model, boundary meshes and a prj file must be created in
addition to the bulk mesh. Examples on those subjects will be added in the
future.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Creating a BHE mesh (Borehole Heat Exchanger)">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_gen_bhe_mesh_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_gen_bhe_mesh.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating a BHE mesh (Borehole Heat Exchanger)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For this example we create meshes from pyvista surfaces. See other examples for different meshing algorithms.">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_meshlib_pyvista_input_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_meshlib_pyvista_input.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating meshes from pyvista surfaces</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For this example we create meshes from surface layers.">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_meshlib_vtu_input_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_meshlib_vtu_input.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating meshes from vtu surface files</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This short example showcases the function remesh_with_tri which allows us to take an existing mesh and re-discretize it with triangle elements. This is useful for models, where the underlying meshing script is not available or hard to adapt.">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_remeshing_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_remeshing.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Remeshing with triangle elements</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we present how to create a unstructured grid in vtk format (\*.vtu) from a shapefile.">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_shapefile_meshing_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_shapefile_meshing.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Meshing a shapefile</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Terrain meshing">

.. only:: html

  .. image:: /auto_examples/howto_preprocessing/images/thumb/sphx_glr_plot_terrain_meshing_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_preprocessing_plot_terrain_meshing.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Terrain meshing</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Create and manipulate prj-files
===============================

The following jupyter notebooks provide some examples of how to use ogstools to
create and manipulate prj-files to configure OGS models.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The following example consists of a simple mechanics problem. The source file can be found in the [OGS benchmark folder](https://gitlab.opengeosys.org/ogs/ogs/-/blob/master/Tests/Data/Mechanics/Linear/square_1e2.prj?ref_type=heads). The names of the method calls are based on the corresponding XML tags.">

.. only:: html

  .. image:: /auto_examples/howto_prjfile/images/thumb/sphx_glr_plot_creation_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_prjfile_plot_creation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">How to Create Simple Mechanics Problem</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="E.g., to iterate over three Young&#x27;s moduli one can use the replace parameter method.">

.. only:: html

  .. image:: /auto_examples/howto_prjfile/images/thumb/sphx_glr_plot_manipulation_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_prjfile_plot_manipulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">How to Manipulate Prj-Files</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Running the simulation
======================

This section covers tools, that can be used to monitor OGS simulations at
runtime. Examples about running simulations from Python will be added in the
future.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This simple example demonstrates how to analyze the OGS (OpenGeoSys) log output to extract performance information regarding various computational parts of OGS. Here we utilize the project file from the benchmark titled: OGS: Constant viscosity (Hydro-Thermal)">

.. only:: html

  .. image:: /auto_examples/howto_simulation/images/thumb/sphx_glr_plot_100_logparser_intro_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_simulation_plot_100_logparser_intro.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Logparser: Introduction</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this section, we showcase various predefined analyses available in the log parser. We utilize project files from the following benchmarks: ogs: Constant viscosity (Hydro-Thermal) and for the staggered scheme we use a prj from ogs tests: HT StaggeredCoupling HeatTransportInStationaryFlow">

.. only:: html

  .. image:: /auto_examples/howto_simulation/images/thumb/sphx_glr_plot_101_logparser_analyses_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_simulation_plot_101_logparser_analyses.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Logparser: Predefined Analyses</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="We address to following:">

.. only:: html

  .. image:: /auto_examples/howto_simulation/images/thumb/sphx_glr_plot_102_logparser_advanced_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_simulation_plot_102_logparser_advanced.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Logparser: Advanced topics</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Post-processing: reading and analyzing the data
===============================================



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how to aggregate data in a model over all timesteps as well as plot differences between to timesteps. For this purpose we use a component transport example from the ogs benchmark gallery (https://www.opengeosys.org/docs/benchmarks/hydro-component/elder/).">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_aggregate_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_aggregate.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Aggregation of Meshseries Data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example explains how to use functions from meshlib to calculate differences between meshes.">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_calculate_diff_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_calculate_diff.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Calculate differences between meshes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows one possible implementation of how to do a convergence study with spatial and temporal refinement. For this, a simple model using a time dependent heat source on one side and constant temperature on the opposite side was set up. The heat source is generated with the :pyogstools.physics.nuclearwasteheat model.">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_convergence_study_nuclear_decay_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_convergence_study_nuclear_decay.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spatial & temporal refinement - nuclear decay</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows one possible implementation of how to do a convergence study. It uses the project file from the following benchmark with multiple discretizations to evaluate the accuracy of the numerical solutions. ogs: elliptic neumann benchmark">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_convergence_study_steady_state_diffusion_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_convergence_study_steady_state_diffusion.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Spatial refinement - steady state diffusion</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This examples shall demonstrate how we can better visualize integration point data (raw data used in OGS&#x27;s equation system assembly without output related artefacts), by tesselating elements in such a way that each integration point is represented by one subsection of a cell.">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_ipdata_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_ipdata.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Analyzing integration point data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="First, some minimal example usage:">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_nuclearwasteheat_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_nuclearwasteheat.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting nuclear waste heat over time</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Extract a 1D profile from 2D and plot it">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_sample_mesh_line_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_sample_mesh_line.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extract a 1D profile from 2D and plot it</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip=":pyogstools.variables provides classes (Scalar, Vector, Matrix) which encapsulate unit handling and data transformation for simplified processing of mesh data. There are also several predefined variables.">

.. only:: html

  .. image:: /auto_examples/howto_postprocessing/images/thumb/sphx_glr_plot_variables_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_postprocessing_plot_variables.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Variable presets and data transformation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Plotting the data
=================

The following jupyter notebooks provide some examples of how to use ogstools to
create all different kinds of plots.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="To demonstrate the creation of an animated plot we use a component transport example from the ogs benchmark gallery (https://www.opengeosys.org/docs/benchmarks/hydro-component/elder/).">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_animation_thumb.gif
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_animation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">How to create Animations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="By default, filled contour plots try to retain the true mesh proportions. If the meshes aspect ratio lies outside of predefined limits (setup.min_ax_aspect, setup.max_ax_aspect) the axes get compressed to stay inside the given limits. The following examples shall illustrate this behaviour.">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_aspect_ratios_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_aspect_ratios.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Aspect ratios</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="To demonstrate the creation of filled contour plots we load a 2D THM meshseries example. In the plot.setup we can provide a dictionary to map names to material ids. Other plot configurations are also available, see: :pyogstools.plot.plot_setup.PlotSetup. Some of these options are also available as keyword arguments in the function call. Please see :pyogstools.plot.contourplots.contourf for more information.">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_contourf_2d_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_contourf_2d.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Visualizing 2D model data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="For visualizing 3D data it might make sense to plot multiple views / slices. To create them we use pyvista as it provides all the necessary functionality. If we want to plot multiple meshes, they have to be in a 2D numpy array. The shape of this array determines the number of rows and columns in our plot. First, let&#x27;s load 3D example data from pyvista and plot the only available data: &quot;facies&quot; with a native pyvista plot.">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_contourf_3d_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_contourf_3d.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Visualizing 3D model data</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we plot the data values on observation points over all timesteps. Since requested observation points don&#x27;t necessarily coincide with actual nodes of the mesh different interpolation options are available. See :pyogstools.meshlib.mesh_series.MeshSeries.probe for more details. Here we use a component transport example from the ogs benchmark gallery (https://www.opengeosys.org/docs/benchmarks/hydro-component/elder/).">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_observation_points_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_observation_points.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">How to plot data at observation points</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how to create filled contourplots on a figure with subplots having shared axes.">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_shared_axes_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_shared_axes.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Shared axes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how to create a filled contourplot of transient data over a sampling line. For this purpose we use a component transport example from the ogs benchmark gallery (https://www.opengeosys.org/docs/benchmarks/hydro-component/elder/).">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_timeslice_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_timeslice.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">How to Create Time Slices</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This tutorial covers plotting meshseries data using user defined matplotlib objects for figure and / or axes. This is useful if different plotting functions ogstools are to be used on different subplots within the same figure.">

.. only:: html

  .. image:: /auto_examples/howto_plot/images/thumb/sphx_glr_plot_with_custom_fig_ax_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_plot_plot_with_custom_fig_ax.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Plotting different process variables on already existing Matplotlib figures / axes</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Conversion tools
================

This section covers tools designed to help with converting already existing
simulations setup with alternative software to open formats compatible with OGS.



.. raw:: html

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

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how a simple FEFLOW model consisting of two layers can be converted to a pyvista.UnstructuredGrid.">

.. only:: html

  .. image:: /auto_examples/howto_conversions/images/thumb/sphx_glr_plot_C_feflowlib_2layers_model_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_conversions_plot_C_feflowlib_2layers_model.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Feflowlib: How to work with FEFLOW data in pyvista.</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how a simple mass transport FEFLOW model can be converted to a pyvista.UnstructuredGrid and then be simulated in OGS with the component transport process.">

.. only:: html

  .. image:: /auto_examples/howto_conversions/images/thumb/sphx_glr_plot_D_feflowlib_CT_simulation_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_conversions_plot_D_feflowlib_CT_simulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Feflowlib: Component-transport model - conversion and simulation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how a simple flow/hydraulic FEFLOW model can be converted to a pyvista.UnstructuredGrid and then be simulated in OGS.">

.. only:: html

  .. image:: /auto_examples/howto_conversions/images/thumb/sphx_glr_plot_E_feflowlib_H_simulation_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_conversions_plot_E_feflowlib_H_simulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Feflowlib: Hydraulic model - conversion and simulation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this example we show how a simple hydro thermal FEFLOW model can be converted to a pyvista.UnstructuredGrid and then be simulated in OGS.">

.. only:: html

  .. image:: /auto_examples/howto_conversions/images/thumb/sphx_glr_plot_F_feflowlib_HT_simulation_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_howto_conversions_plot_F_feflowlib_HT_simulation.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Feflowlib: Hydro-thermal model - conversion and simulation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /auto_examples/howto_quickstart/index.rst
   /auto_examples/howto_preprocessing/index.rst
   /auto_examples/howto_prjfile/index.rst
   /auto_examples/howto_simulation/index.rst
   /auto_examples/howto_postprocessing/index.rst
   /auto_examples/howto_plot/index.rst
   /auto_examples/howto_conversions/index.rst