docs: Tutorial examples of a vertical fault using the ALM solver by jhuang2601 · Pull Request #4082 · GEOS-DEV/GEOS

jhuang2601 · 2026-06-10T20:09:45Z

This PR

documents the analytical verification of ALM solver using a slipped vertical fault problem (shear slip for frictionless fault) in porous media
documents the analytical verification of ALM solver using a stable vertical fault problem (shear stress for friction and stable fault) in porous media
compares the results with both external (splitting fault with mesh doctor) and internal (internal surface generator) workflow
benchmarks the convergence of the relative 𝐿2-error with respect to mesh resolution
adds smoke tests for both workflows to the integratedTests

dkachuma

The two examples look quite similar. Can we possibly discuss them in the same context as a comparison?

dkachuma · 2026-06-15T17:29:34Z

+     <File name="ALM_verticalFault_base.xml"/>
+  </Included>
+
+  <Constitutive>


I would expect constitutive relations to be in the base file and shared between the smoke/bench and internal/external cases. Are they actually different across these models?

Fault mechanical properties (in constitutive block) are different for the case with stable and slipped fault.

dkachuma · 2026-06-15T17:31:52Z

+      name="mesh1"
+      useGlobalIds="0"
+      nodesetNames="{ faultNodes }"
+      file="../../MESH/verticalFault_ISG_benchmark.vtu"/>


In these cases I have expected the internal workflow to be able to use the "domain" mesh from the external workflow. Are there differences between verticalFault_ISG_benchmark.vtu and Domain_verticalFault_benchmark.vtu?

Yes
The attribute faultNodes must be included in verticalFault_ISG_benchmark.vtu to define the location and extent of the fault plane, which will be used by SurfaceGenerator.
Domain_verticalFault_benchmark.vtu contains duplicated nodes after splitting the mesh with mesh-doc.

dkachuma · 2026-06-15T17:41:07Z

+For more information on defining finite elements numerical schemes,
+please see the dedicated :ref:`FiniteElement` section.
+
+The finite volume method requires the specification of a discretization scheme.


Suggested change

The finite volume method requires the specification of a discretization scheme.

The finite volume method, for the flow solver, requires the specification of a discretization scheme.

bd713

Thanks, @jhuang2601.
Along the same lines as @dkachuma, we could probably also share the scripts (especially for the analytical solution).

bd713 · 2026-06-15T18:47:33Z

+    :start-after: <!-- SPHINX_MESH -->
+    :end-before: <!-- SPHINX_MESH_END -->
+
+The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the damain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor  <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).


Suggested change

The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the damain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).

The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the domain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).

bd713 · 2026-06-15T18:52:40Z

+    :start-after: <!-- SPHINX_MESH -->
+    :end-before: <!-- SPHINX_MESH_END -->
+
+The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the damain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor  <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).


Suggested change

The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the damain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).

The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the domain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).

jhuang2601 · 2026-06-18T19:38:20Z

The two examples look quite similar. Can we possibly discuss them in the same context as a comparison?

As different fault modes (static vs slip), fault mechanical properties and resulting parameters (stress vs displacementJump) are used for two cases, I have to separate them into two examples to avoid confusion.

jhuang2601 · 2026-06-18T19:51:59Z

Thanks, @jhuang2601. Along the same lines as @dkachuma, we could probably also share the scripts (especially for the analytical solution).

Yes, generate_analytical.py has already been pushed.

jhuang2601 · 2026-06-26T18:06:43Z

Expected failure for adding new tests and rebaseline is required

=======================
Test failures
=======================
verticalFault_stable_ESG_smoke_01
verticalFault_stable_ESG_smoke_04
verticalFault_stable_ISG_smoke_01
verticalFault_stable_ISG_smoke_04
verticalFault_unstable_ESG_smoke_01
verticalFault_unstable_ESG_smoke_04
verticalFault_unstable_ISG_smoke_01
verticalFault_unstable_ISG_smoke_04
=======================
Overall status: FAILED
=======================

joshua-white · 2026-07-10T23:30:29Z

+
+**Context**
+
+In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026)  <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a frictional fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions and is coupled with a Coulomb friction law. Implemented in GEOS, the model computes displacement discontinuities (fault slip upon reactivation) along the frictionless fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022)  <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.


Suggested change

In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026) <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a frictional fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions and is coupled with a Coulomb friction law. Implemented in GEOS, the model computes displacement discontinuities (fault slip upon reactivation) along the frictionless fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022) <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.

In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026) <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a frictional fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements, coupled with a Coulomb friction law. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions. The model computes displacement discontinuities (fault slip upon reactivation) along the frictionless fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022) <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.

joshua-white · 2026-07-10T23:33:06Z

+------------------------------------------------------------------
+
+We simulate induced stresses and shear slip along a vertical fault in a depleted reservoir and compare our results against an analytical solution.
+In conformity to the analytical set-up, the reservoir is divided into two parts by a vertical fault. The fault crosses and offsets the entire reservoir layer and is well contained with the domain. The domain is infinite, homogeneous, isotropic, and elastic. The reservoir is depressurized uniformly upon depletion, and we neglect the transient effect of fluid flow. A pressure drop is applied to the reservoir layer located in the center of the domain. The overburden and underburden are impermeable, and no pressure changes occur in these layers. Due to poromechanical effects, pore pressure changes in the reservoir cause a mechanical deformation of the entire domain. This deformation leads to a stress (normal and shear) perturbation on the fault plane, potentially leading to fault reactivation. For verification, the numerical model considers plane strain deformation and the Coulomb failure criterion.


Suggested change

In conformity to the analytical set-up, the reservoir is divided into two parts by a vertical fault. The fault crosses and offsets the entire reservoir layer and is well contained with the domain. The domain is infinite, homogeneous, isotropic, and elastic. The reservoir is depressurized uniformly upon depletion, and we neglect the transient effect of fluid flow. A pressure drop is applied to the reservoir layer located in the center of the domain. The overburden and underburden are impermeable, and no pressure changes occur in these layers. Due to poromechanical effects, pore pressure changes in the reservoir cause a mechanical deformation of the entire domain. This deformation leads to a stress (normal and shear) perturbation on the fault plane, potentially leading to fault reactivation. For verification, the numerical model considers plane strain deformation and the Coulomb failure criterion.

In the analytical problem definition, the reservoir is divided into two parts by a vertical fault. The fault crosses and offsets the entire reservoir layer and is well contained with the domain. The domain is infinite, homogeneous, isotropic, and elastic. The reservoir is depressurized uniformly upon depletion, and we neglect the transient effect of fluid flow. A pressure drop is applied to the reservoir layer located in the center of the domain. The overburden and underburden are impermeable, and no pressure changes occur in these layers. Due to poromechanical effects, pore pressure changes in the reservoir cause a mechanical deformation of the entire domain. This deformation leads to a stress (normal and shear) perturbation on the fault plane, potentially leading to fault reactivation. For verification, the numerical model considers plane strain deformation and the Coulomb failure criterion.

joshua-white · 2026-07-10T23:34:40Z

+The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the domain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor  <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).
+
+
+For internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported


Suggested change

For internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported

For the internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported

joshua-white · 2026-07-10T23:37:07Z

+
+As mentioned before, the coupling solver and the solid mechanics solver require the specification of a discretization method called ``FE1``.
+In GEOS, this discretization method represents a finite element method
+using linear basis functions and Gaussian quadrature rules.


Suggested change

using linear basis functions and Gaussian quadrature rules.

using tri-linear basis functions and Gaussian quadrature rules.

joshua-white · 2026-07-10T23:38:19Z

+As mentioned before, the coupling solver and the solid mechanics solver require the specification of a discretization method called ``FE1``.
+In GEOS, this discretization method represents a finite element method
+using linear basis functions and Gaussian quadrature rules.
+For more information on defining finite elements numerical schemes,


Suggested change

For more information on defining finite elements numerical schemes,

For more information on defining the finite element numerical schemes,

joshua-white · 2026-07-10T23:41:51Z

+
+**Context**
+
+In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026)  <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a friction and stable fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions and is coupled with a Coulomb friction law. Implemented in GEOS, the model computes stress perturbations (normal and shear components) along the stable fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022)  <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.


Suggested change

In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026) <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a friction and stable fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions and is coupled with a Coulomb friction law. Implemented in GEOS, the model computes stress perturbations (normal and shear components) along the stable fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022) <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.

In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026) <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a friction and stable fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements, coupled with a Coulomb friction law. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions. The model computes stress perturbations (normal and shear components) along the stable fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022) <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.

joshua-white · 2026-07-10T23:44:17Z

@@ -0,0 +1,303 @@
+.. _unstableVerticalFault:


The description of the test cases (stable and slipped) is nearly identical. Perhaps we can merge into a single validation study with two subsections? Or simpler, make the second one much shorter, with a link to the other to get common details?

add xml files for benchmark examples

028502d

jhuang2601 self-assigned this Jun 10, 2026

jhuang2601 mentioned this pull request Jun 10, 2026

Tutorial example for fault slippage #2958

Closed

2 tasks

jhuang2601 added type: documentation EPIC - FF/Contact Contact mechanics labels Jun 10, 2026

jhuang2601 added 2 commits June 12, 2026 12:23

add rst file and script for slipped case

52cb65a

add rst file and script for stable case

5996f13

jhuang2601 marked this pull request as ready for review June 12, 2026 18:03

jhuang2601 requested review from OmarDuran, bd713, castelletto1, dkachuma, herve-gross, joshua-white and rrsettgast as code owners June 12, 2026 18:03

jhuang2601 and others added 5 commits June 12, 2026 13:03

Merge branch 'develop' into docs/jhuang/verticalFault

bf7ae59

update keyword for Coulomb

2528327

some fix

e467d0d

update python script

d79f70f

reduce fig size

228b114

jhuang2601 changed the title ~~docs: tutorial example with a vertical fault~~ docs: Tutorial examples of a vertical fault using the ALM solver Jun 12, 2026

jhuang2601 added ci: run CUDA builds Allows to triggers (costly) CUDA jobs ci: run integrated tests Allows to run the integrated tests in GEOS CI ci: run code coverage enables running of the code coverage CI jobs labels Jun 12, 2026

add smoke tests to integratedTests

b6ef64a

dkachuma reviewed Jun 15, 2026

View reviewed changes

bd713 reviewed Jun 15, 2026

View reviewed changes

herve-gross approved these changes Jun 15, 2026

View reviewed changes

address review comments

ab8b1fe

Merge branch 'develop' into docs/jhuang/verticalFault

71cf518

jhuang2601 added the flag: requires rebaseline Requires rebaseline branch in integratedTests label Jun 25, 2026

jhuang2601 added 5 commits June 26, 2026 13:13

update rebaseline tag

ca645bc

fix MPI runs for tests with surfaceGenerator

36efc4f

rebaseline again

f878a52

Merge branch 'develop' into docs/jhuang/verticalFault

76bab7b

update rebaseline

bfaff7b

joshua-white reviewed Jul 10, 2026

View reviewed changes

joshua-white approved these changes Jul 10, 2026

View reviewed changes

	The finite volume method requires the specification of a discretization scheme.
	The finite volume method, for the flow solver, requires the specification of a discretization scheme.


		Context

		In this example, the Augmented Lagrangian Method (ALM) `(Frigo et al., 2026) <https://www.sciencedirect.com/science/article/abs/pii/S0021999126003414>`__ is applied to solve a frictional fault contact problem in a depleted reservoir. This approach employs conformal discretization where discontinuities are explicitly represented by 2D interface elements placed between 3D continuum elements. The formulation overcomes the inf-sup instability of low-order discretizations by satisfying the Babuška–Brezzi condition via displacement enrichment with bubble functions and is coupled with a Coulomb friction law. Implemented in GEOS, the model computes displacement discontinuities (fault slip upon reactivation) along the frictionless fault, which are subsequently verified against the corresponding analytical solution `(Jansen and Meulenbroek, 2022) <https://njgjournal.nl/index.php/njg/article/view/11453/17972>`__. This comparison confirms the accuracy of our fault contact model and coupled poroelastic formulation.

		The vtm file ``verticalFault_ESG_benchmark.vtm`` references two separate mesh files: the domain mesh ``Domain_verticalFault_benchmark.vtu`` and the fault mesh ``Fault_verticalFault_benchmark.vtu``, which are generated prior to running the GEOS simulation. The ``mesh doctor`` module provides a convenient way to prepare these meshes. For this case, functions ``generateFractures`` and ``generateGlobalIds`` are used (more information here: `mesh doctor <https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/mesh-doctor.html#>`__).


		For internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported

	For internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported
	For the internal workflow, only the domain mesh file ``verticalFault_ISG_benchmark.vtu`` is imported

	using linear basis functions and Gaussian quadrature rules.
	using tri-linear basis functions and Gaussian quadrature rules.

	For more information on defining finite elements numerical schemes,
	For more information on defining the finite element numerical schemes,

Uh oh!

Conversation

jhuang2601 commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkachuma left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bd713 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jhuang2601 commented Jun 18, 2026

Uh oh!

jhuang2601 commented Jun 18, 2026

Uh oh!

jhuang2601 commented Jun 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joshua-white Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jhuang2601 commented Jun 10, 2026 •

edited

Loading

joshua-white Jul 10, 2026 •

edited

Loading