.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_user-guide/plot_simulate.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_user-guide_plot_simulate.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_user-guide_plot_simulate.py:


Running OGS Simulations from Python
===================================

.. sectionauthor:: Florian Zill (Helmholtz Centre for Environmental Research GmbH - UFZ)

OGSTools is a Python library designed to simplify the process of running
simulations with the OpenGeoSys (OGS) framework. The `Project` class is a core
component of OGSTools, providing a convenient interface for creating and
altering OGS6 input files up and executing OGS simulations. This allows you to
automate OGS-workflows in Python via Jupyter or just plain Python scripts.
The development of this functionality was first started in
[ogs6py](https://github.com/joergbuchwald/ogs6py/) and is continued in OGSTools.
Here you'll find the detailed API: :py:obj:`ogstools.ogs6py.project.Project`.

Features:
- alternate existing files (e.g., for parameter sweeps)
- create new input files from scratch
- execute project files
- tailored alteration of input files e.g. for mesh replacements or restarts
- display and export parameter settings

In this guide, we will walk you through the process of using the `Project` class
to run a simple simulation from an existing model setup.
Assuming you have prepared a model with your mesh and a project file you can
use the following setup, to run it from python.

.. GENERATED FROM PYTHON SOURCE LINES 30-49

.. code-block:: Python

    from pathlib import Path
    from tempfile import mkdtemp

    import ogstools as ot
    from ogstools.definitions import EXAMPLES_DIR

    results_dir = Path(mkdtemp())
    prj_path_in = EXAMPLES_DIR / "prj" / "simple_mechanics.prj"
    prj_path_out = results_dir / "simple_mechanics_modified.prj"
    prj = ot.Project(
        input_file=prj_path_in, output_file=prj_path_out, output_dir=results_dir
    )
    prj.write_input()
    # as the current working directory of this notebook is not the same as the
    # directory of the prj-file and the meshes, we have to tell OGS via the flag
    # "-m", that the meshes are in the same directory as the input_file
    # "-o" sets the output_directory
    prj.run_model(args=f"-m {prj_path_in.parent} -o {results_dir}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Project file written to output.
    Simulation: /tmp/tmp521ryi31/simple_mechanics_modified.prj
    Status: finished successfully.
    Execution took 0.12925243377685547 s




.. GENERATED FROM PYTHON SOURCE LINES 50-56

Manipulating the Project
========================
By using a prj-file as a template and modifying it in python we have an easy
way to parametrize simulations. Below are some methods, which change
different parts of the model definition. For more detailed information have
a look into the API.

.. GENERATED FROM PYTHON SOURCE LINES 58-68

.. code-block:: Python

    prj.replace_parameter_value(name="E", value=1e9)
    # You can achieve the same via the `replace_text` method:
    prj.replace_text(1e9, xpath="./parameters/parameter[name='E']/value")
    # Let's also replace the output prefix of the result
    prj.replace_text("E=1e9", xpath="./time_loop/output/prefix")
    # The density of a phase can also be changed
    prj.replace_phase_property_value(
        mediumid=0, phase="Solid", name="density", value="42"
    )








.. GENERATED FROM PYTHON SOURCE LINES 69-73

After modifying the Project you can execute the model in the same way as
before. You have to run the `write_input` method beforehand again. The changes
will not be reflected in the simulation otherwise. This step will be
automated in the future.

.. GENERATED FROM PYTHON SOURCE LINES 75-79

Background execution
====================
To execute a simulation in the background, so that your python environment is
not frozen until the simulation finishes, you can set `background` to True.

.. GENERATED FROM PYTHON SOURCE LINES 81-85

.. code-block:: Python

    prj.write_input()
    prj.run_model(background=True, args=f"-m {prj_path_in.parent} -o {results_dir}")
    print(prj.status)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Simulation: /tmp/tmp521ryi31/simple_mechanics_modified.prj
    Status: running for 0.0012149810791015625 s.




.. GENERATED FROM PYTHON SOURCE LINES 86-87

If you want to abort the simulation for any reason, use the following command:

.. GENERATED FROM PYTHON SOURCE LINES 89-92

.. code-block:: Python

    prj.terminate_run()
    print(prj.status)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Simulation: /tmp/tmp521ryi31/simple_mechanics_modified.prj
    Status: terminated with error code -9.




.. GENERATED FROM PYTHON SOURCE LINES 93-97

Creating a Project from scratch
===============================
You can also create a Project without a prj-file. Have a look at this example
to see how: :ref:`sphx_glr_auto_examples_howto_prjfile_plot_creation.py`


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.146 seconds)


.. _sphx_glr_download_auto_user-guide_plot_simulate.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_simulate.ipynb <plot_simulate.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_simulate.py <plot_simulate.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_simulate.zip <plot_simulate.zip>`