0% found this document useful (0 votes)

38 views

Geosx Geosx Readthedocs Hosted Com en Latest

The GEOS documentation provides a comprehensive guide for users and developers of the GEOS code framework, which focuses on physics simulations in high-performance computing environments. It includes sections such as a Quick Start Guide, Tutorials, User and Developer Guides, and details on building and managing dependencies. The documentation aims to support both application-focused users and developers, emphasizing the importance of high-quality documentation for successful code usage.

Uploaded by

axel.kfupm

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

38 views

Geosx Geosx Readthedocs Hosted Com en Latest

Uploaded by

axel.kfupm

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 993

GEOS Documentation

GEOS/GEOSX Developers

Dec 20, 2024

CONTENTS

1 Table of Contents 3
1.1 Quick Start Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3 Basic Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
1.4 Advanced Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
1.5 User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
1.6 Developer Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
1.7 Doxygen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
1.8 Build Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
1.9 Datastructure Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680
1.10 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976
1.11 Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 977
1.12 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986

2 Indices and tables 987

Index 989

i
ii
GEOS Documentation

GEOS is a code framework focused on enabling streamlined development of physics simulations on high performance
computing platforms. Our documentation is organized into several separate guides, given that different users will have
different needs.
We recommend all users begin with the Quick Start guide, which will walk you through downloading and compiling
the code. Application focused users may then want to explore our Tutorials, which provide an introduction to the basic
capabilities of the code. More detailed descriptions of these capabilities can then be found in the User Guide.
For those interested in developing new capabilities in GEOS, we provide a Developer Guide. The code itself is also
documented inline using doxygen. The Build Guide contains more detailed information about third-party dependencies,
the build system, and the continuous integration system. Finally, GEOS has a self-documenting data structure. The
Datastructure Index is an automatically generated list of all available input parameters and data structures in the code.
This is a comprehensive resource, but probably not the place to start.
High quality documentation is a critical component of a successful code. If you have suggestions for improving the
guides below, please post an issue on our issue tracker.
Quick Start Guide
New to GEOS? We will walk you through downloading the source, compiling the code, and testing the installation.
To the Quick Start
Tutorials
Working tutorials that show how to run some common problems. After going through these examples, you should have
a good understanding of how to set up and solve your own models.
To the Tutorials
Basic Examples
Example problems that are organized around physical processes (fluid flow, mechanics, etc.).
To the Basic Examples
Advanced Examples
Example problems that demonstrate additional physical models, constitutive models, advanced features, etc.
To the Advanced Examples
User Guide
Detailed instructions on how to construct input files, configure problems, manage outputs, etc.
To the User Guide
Python Tools
Documentation for the python packages distributed alongside GEOS used to manage xml files, condition numerical
meshes, read outputs, etc.
To the Python Tools Documentation
Feature Requests, Reporting Bugs, and Support
To make feature requests, report bugs, or get support (after reviewing the user guide) please submit an issue on Github.
To the “New issue” page on the GEOS Github repository

CONTENTS 1
GEOS Documentation

2 CONTENTS
CHAPTER

ONE

TABLE OF CONTENTS

1.1 Quick Start Guide

The goal of this page is to get you started as quickly as possible using GEOS. We will walk you through downloading
the source, compiling the code, and testing the installation.
Before jumping to the installation process, we want to first address some frequently asked questions we get from new
users. If you are itching to get started, feel free to jump ahead to the relevant sections.

1.1.1 Frequently Asked Questions

Does GEOS have a graphical user interface?:
Given the focus on rapid development and HPC environments, GEOS does not have a graphical user interface. This is
consistent with many other high performance computing packages, but we recognize it can be a deal-breaker for certain
users. For those who can get past this failing, we promise we still have a lot to offer. In a typical workflow, you will
prepare an XML-based input file describing your problem. You may also prepare a mesh file containing geometric and
property information describing, say, a reservoir you would like to simulate. There is no shortage of GUI tools that
can help you in this model building stage. The resulting input deck is then consumed by GEOS to run the simulation
and produce results. This may be done in a terminal of your local machine or by submitting a job to a remote server.
The resulting output files can then be visualized by any number of graphical visualization programs (typically VisIt or
paraview). Thus, while GEOS is GUI free, the typical workflow is not.

Do I need to be a code developer to use GEOS?:

For the moment, most users will need to download and compile the code from source, which we readily admit this
requires a certain level of development expertise. We try to make this process as easy as possible, and we are working
on additional deployment options to make this process easier. Once installed, however, our goal is to make GEOS
accessible to developers and non-developers alike. Our target audience includes engineers and scientists who want to
solve tough application problems, but could care less about the insides of the tool. For those of you who are interested
in scientific computing, however, GEOS is an open source project and we welcome external contributions.

What are the system requirements?:

GEOS is primarily written in C++, with a focus on standards compliance and platform-to-platform portability. It is
designed to run on everything from commodity laptops to the world’s most powerful supercomputers. We regularly test
the code across a variety of operating systems and compilers. Most of these operating systems are Linux/UNIX based
(e.g. Ubuntu, CentOS, Mac OSX). We do have developers working in Windows environments, but they use a Virtual
Machine or work within a docker image rather than directly in the Windows environment. In the instructions below, we
assume you have access to fairly standard development tools. Using advanced features of GEOS, like GPU-acceleration,
will of course introduce additional hardware and software requirements.

3
GEOS Documentation

Help, I get errors while trying to download/compile/run!:

Unfortunately, no set of instructions is foolproof. It is simply impossible to anticipate every system configuration or
user. If you run into problems during the installation, we recommend the following five-step process:
1. Take a moment to relax, and then re-read the instructions carefully. Perhaps you overlooked a key step? Re-read
the error message(s) closely. Modern compilation tools are often quite helpful in reporting exactly why things
fail.
2. Type a few keywords from your error into a search engine. It is possible someone else out there has encountered
your problem before, and a well-chosen keyword can often produce an instant solution. Note that when a com-
pilation fails, you may get pages and pages of errors. Try to identify the first one to occur and fix that. One error
will often trigger subsequent errors, and looking at the last error on the screen may not be so helpful.
3. If you encounter problems building one of the third-party libraries we depend on, check out their support pages.
They may be able to help you more directly than we can.
4. Still stuck? Check out our issues tracker, searching current or closed issues that may address your problem.
Perhaps someone has had an identical issue, or something close. The issue tracker has a convenient search bar
where you can search for relevant keywords. Remember to remove the default is:open keyword to search both
open and closed issues.
5. If you have exhausted the options above, it is time to seek help from the developers. Post an issue on our issue
tracker. Be specific, providing as much information as possible about your system setup and the error you are
encountering. Please be patient in this process, as we may need to correspond a few times and ask you to run
additional tests. Most of the time, users have a slightly unusual system configuration that we haven’t encountered
yet, such as an older version of a particular library. Other times there is a legitimate bug in GEOS to be addressed.
Take pride in the fact that you may be saving the next user from wasted time and frustration.

1.1.2 Repository Organization

The source for GEOS and related tools are hosted on Github. We use Git workflows to version control our code
and manage the entire development process. On Github, we have a GEOS Organization that hosts several related
repositories.
You should sign up for a free Github account, particularly if you are interested in posting issues to our issue tracker and
communicating with the developers. The main repository of interest is obviously GEOS itself: GEOS
We also rely on two types of dependencies: first-party and third-party. First-party dependencies are projects directly
associated with the GEOS effort, but kept in separate repositories because they form stand-alone tools. For example,
there is an equation-of-state package called PVTPackage or the streamlined CMake-based foundation BLT . These
packages are handled as Git Submodules, which provides a transparent way of coordinating multiple code development
projects. Most users will never have to worry that these modules are in fact separate projects from GEOS.
We also rely on several open-source Third-Party Libraries (TPLs) (see thirdPartyLibs). These are well-respected
projects developed externally to GEOS. We have found, however, that many compilation issues stem from version
incompatibilities between different packages. To address this, we provide a mirror of these TPLs, with version com-
binations we know play nicely together. We also provide a build script that conveniently and consistently builds those
dependencies.
Our build system will automatically use the mirror package versions by default. You are welcome to tune your config-
uration, however, to point to different versions installed on your system. If you work on an HPC platform, for example,
common packages may already be available and optimized for platform hardware. For new users, however, it may be
safer to begin with the TPL mirror.

ò Note

4 Chapter 1. Table of Contents

GEOS Documentation

If you are working on an HPC platform with several other GEOS users, we often compile the TPLs in a shared
location so individual users don’t have to waste their storage quota. Inquire with your institution’s point-of-contact
whether this option already exists. For all LLNL systems, the answer is yes.

Finally, there are also several private repositories only accessible to the core development team, which we use for
behind-the-scene testing and maintenance of the code.

1.1.3 Username and Authentication

New users should sign up for a free Github account.
If you intend to develop in the GEOS codebase, you may benefit from setting up your git credentials (see Git Workflow).

1.1.4 Download
It is possible to directly download the source code as a zip file. We strongly suggest, however, that users don’t rely on
this option. Instead, most users should use Git to either clone or fork the repository. This makes it much easier to stay
up to date with the latest releases and bug fixes. If you are not familiar with the basics of Git, here is a helpful resource
to get you started.
The tutorial here assumes you will use a https clone with no specific credentials. Using an ssh connection pattern
requires a very slight modification. See the Additional Notes at the end of this section for details.
If you do not already have Git installed on your system, you will need to install it. We recommend using a relatively
recent version of Git, as there have been some notable improvements over the past few years. You can check if Git is
already available by opening a terminal and typing

git --version

You’ll also need the git-lfs large file extension.

The first task is to clone the GEOS and thirdPartyLibs repositories. If you do not tell it otherwise, the build system
will expect the GEOS and thirdPartyLibs to be parallel to each other in the directory structure. For example,

codes/
GEOS/
thirdPartyLibs/

where the toplevel codes directory can be re-named and located wherever you like. It is possible to customize the
build system to expect a different structure, but for now let us assume you take the simplest approach.
First, using a terminal, create the codes directory wherever you like.

cd /insert/your/desired/path/
mkdir codes
cd codes

Inside this directory, we can clone the GEOS repository. We will also use some Git commands to initialize and down-
load the submodules (e.g. LvArray).

git clone https://github.com/GEOS-DEV/GEOS.git

cd GEOS
git lfs install
git submodule init
git submodule update
cd ..

1.1. Quick Start Guide 5

GEOS Documentation

If all goes well, you should have a complete copy of the GEOS source at this point. The most common errors people
encounter here have to do with Github not recognizing their authentication settings and/or repository permissions. See
the previous section for tips on ensuring your SSH is working properly.
Note: Previous versions of GEOS also imported the integratedTests submodule, which is not publicly available (access
is limited to the core development team). This may cause the git submodule update command to fail. In that case,
run git submodule deinit integratedTests before git submodule update. This submodule is not required
for building GEOS.

cd GEOS
git submodule update --init src/cmake/blt
git submodule update --init src/coreComponents/LvArray
git submodule update --init src/coreComponents/fileIO/coupling/hdf5_interface
git submodule update --init src/coreComponents/constitutive/PVTPackage
cd ..

Once we have grabbed GEOS, we do the same for the thirdPartyLibs repository. From the codes directory, type

git clone https://github.com/GEOS-DEV/thirdPartyLibs.git

cd thirdPartyLibs
git lfs install
git pull
git submodule init
git submodule update
cd ..

Again, if all goes well you should now have a copy of all necessary TPL packages.
Additional Notes:
#. git-lfs may not function properly (or may be very slow) if your version of git and git-lfs are not current. If you
are using an older version, you may need to add git lfs pull after git pull in the above procedures.
#. You can adapt the commands if you use an ssh connection instead. The clone https://github.com/GEOS-DEV/
GEOS.git becomes git clone [email protected]:GEOS-DEV/GEOS.git. You may also be willing to insert your
credentials in the command line (less secure) git clone https://${USER}:${TOKEN}@github.com/GEOS-DEV/
GEOS.git.

1.1.5 Configuration
Before proceeding, make sure to have installed all the minimal prerequisites as described in System prerequisites Note
that GEOS supports a variety of parallel computing models, depending on the hardware and software environment.
Advanced users are referred to the Build Guide for a discussion of the available configuration options.
Before beginning, it is a good idea to have a clear idea of the flavor and version of the build tools you are using. If
something goes wrong, the first thing the support team will ask you for is this information.

cpp --version
mpic++ --version
cmake --version

Here, you may need to replace cpp with the full path to the C++ compiler you would like to use, depending on how
your path and any aliases are configured.

6 Chapter 1. Table of Contents

GEOS Documentation

Defining a Host-Config File

GEOS compilations are driven by a CMake host-config file, which informs the build system about the compilers
you are using, where various packages reside, and what options you want to enable.
A template for creating a simple host-config is provided in host-configs/quick-start-template.cmake.

set( CONFIG_NAME "quick-start" )

# Set compilers path

set(CMAKE_C_COMPILER "path-to-gcc/bin/gcc" CACHE PATH "") # This is typically␣
˓→something like /usr/bin/gcc ... or clang

set(CMAKE_CXX_COMPILER "path-to-gcc/bin/g++" CACHE PATH "") # This is typically␣

˓→something like /usr/bin/g++ ... or clang++

set(ENABLE_FORTRAN OFF CACHE BOOL "" FORCE)

# Set paths to mpi

set(ENABLE_MPI ON CACHE PATH "")
set(MPI_C_COMPILER "path-to-mpi/bin/mpicc" CACHE PATH "") # This is typically␣
˓→something like /usr/bin/mpicc

set(MPI_CXX_COMPILER "path-to-mpi/bin/mpicxx" CACHE PATH "") # This is typically␣

˓→something like /usr/bin/mpicxx

set(MPIEXEC "path-to-mpi/bin/mpirun" CACHE PATH "") # This is typically␣

˓→something like /usr/bin/mpirun

# Set paths to blas and lapack

set( BLAS_LIBRARIES "path-to-blas" CACHE PATH "" FORCE ) # This is typically␣
˓→something like /usr/lib64/libblas.so

set( LAPACK_LIBRARIES "path-to-lapack" CACHE PATH "" FORCE ) # This is typically␣

ò Note

Building all of the TPLs can take quite a while, so you may want to go get a cup of coffee at this point. Also note
that you should not use a parallel make -j N command to try and speed up the build time.

8 Chapter 1. Table of Contents

GEOS Documentation

Compiling GEOS
Once the TPLs have been compiler, the next step is to compile the main code. The config-build.py script is used
to configure the build directory. Before running the configuration script, ensure that the path to the TPLs is correctly
set in the host configuration file by setting

set(GEOS_TPL_DIR "/path/to/your/TPL/installation/dir" CACHE PATH "")

If you have followed these instructions, the TPLs are installed at the default location, i.e. /path/to/your/TPL/
thirdPartyLibs/install-your-platform-release.

cd ../../GEOS
python scripts/config-build.py -hc host-configs/your-platform.cmake -bt Release

An alternative is to set the path GEOS_TPL_DIR via a cmake command line option, e.g.

python scripts/config-build.py -hc host-configs/your-platform.cmake -bt Release -D GEOS_

˓→TPL_DIR=/full/path/to/thirdPartyLibs

ò Note

We highly recommend using full paths, rather than relative paths, whenever possible.

Once the configuration process is completed, we proceed with the compilation of the main code and the instalation of
geos.

cd build-your-platform-release
make -j4
make install

The parallel make -j 4 will use four processes for compilation, which can substantially speed up the build if you have
a multi-processor machine. You can adjust this value to match the number of processors available on your machine.
The make install command then installs GEOS to a default location unless otherwise specified.
If all goes well, a geosx executable should now be available

GEOS/install-your-platform-release/bin/geosx

1.1.7 Running
We can do a quick check that the geosx executable is working properly by calling the executable with our help flag

./bin/geosx --help

This should print out a brief summary of the available command line arguments:

USAGE: geosx -i input.xml [options]

Options:
-?, --help
-i, --input, Input xml filename (required)
-r, --restart, Target restart filename
-x, --x-partitions, Number of partitions in the x-direction
-y, --y-partitions, Number of partitions in the y-direction
(continues on next page)

1.1. Quick Start Guide 9

GEOS Documentation

(continued from previous page)

-z, --z-partitions, Number of partitions in the z-direction
-s, --schema, Name of the output schema
-b, --use-nonblocking, Use non-blocking MPI communication
-n, --name, Name of the problem, used for output
-s, --suppress-pinned, Suppress usage of pinned memory for MPI communication buffers
-o, --output, Directory to put the output files
-t, --timers, String specifying the type of timer output
--trace-data-migration, Trace host-device data migration
--pause-for, Pause geosx for a given number of seconds before starting␣
˓→execution

Obviously this doesn’t do much interesting, but it will at least confirm that the executable runs. In typical usage, an
input XML must be provided describing the problem to be run, e.g.

./bin/geosx -i your-problem.xml

In a parallel setting, the command might look something like

mpirun -np 8 ./bin/geosx -i your-problem.xml -x 2 -y 2 -z 2

Note that we provide a series of Tutorials to walk you through the actual usage of the code, with several input examples.
Once you are comfortable the build is working properly, we suggest new users start working through these tutorials.

1.1.8 Testing
It is wise to run our unit test suite as an additional check that everything is working properly. You can run them in the
build folder you just created.

cd GEOS/build-your-platform-release
ctest -V

This will run a large suite of simple tests that check various components of the code. If you have access, you may also
consider running the integrated tests. Please refer to Integrated Tests for further information.

ò Note

If all of the unit tests fail, there is likely something wrong with your installation. Refer to the FAQs above for how
best to proceed in this situation. If only a few tests fail, it is possible that your platform configuration has exposed
some issue that our existing platform tests do not catch. If you suspect this is the case, please consider posting an
issue to our issue tracker (after first checking whether other users have encountered a similar issue).

1.2 Tutorials
The easiest way to learn to use GEOS is through worked examples. Here, we have included tutorials showing how to
run some common problems. After working through these examples, you should have a good understanding of how to
set up and solve your own models.
Note that these tutorials are intended to be followed in sequence, as each step introduces a few new skills. Most of the
tutorial models are also quite small, so that large computational resources are not required.

10 Chapter 1. Table of Contents

GEOS Documentation

1.2.1 Tutorial 1: First Steps

Context
In this tutorial, we use a single-phase flow solver (see Singlephase Flow Solver) to solve for pressure propagation on a
10x10x10 cube mesh with anisotropic permeability values. The pressure source is the lowest-left corner element, and
the pressure sink sits at the opposite top corner.

Objectives
At the end of this tutorial you will know:
• the basic structure of XML input files used by GEOS,
• how to run GEOS on a simple case requiring no external input files,
• the basic syntax of a solver block for single-phase problems,
• how to control output and visualize results.
Input file
GEOS runs by reading user input information from one or more XML files. For this tutorial, we only need a single
GEOS input file located at:

inputFiles/singlePhaseFlow/3D_10x10x10_compressible_smoke.xml

Running GEOS
If our XML input file is called my_input.xml, GEOS runs this file by executing:

/path/to/geosx -i /path/to/my_input.xml

The -i flag indicates the path to the XML input file. To get help on what other command line input flags GEOS
supports, run geosx --help.
Input file structure

1.2. Tutorials 11
GEOS Documentation

XML files store information in a tree-like structure using nested blocks of information called elements. In GEOS, the
root of this tree structure is the element called Problem. All elements in an XML file are defined by an opening tag
(<ElementName>) and end by a corresponding closing tag (</ElementName>). Elements can have properties defined
as attributes with key="value" pairs. A typical GEOS input file contains the following tags:
1. Solver
2. Mesh
3. Geometry
4. Events
5. NumericalMethods
6. ElementRegions
7. Constitutive
8. FieldSpecifications
9. Outputs
XML validation tools
If you have not already done so, please use or enable an XML validation tool (see User Guide/Input Files/Input
Validation). Such tools will help you identify common issues that may occur when working with XML files.

ò Note

Common errors come from the fact that XML is case-sensitive, and all opened tags must be properly closed.

Single-phase solver
GEOS is a multiphysics simulator. To find the solution to different physical problems such as diffusion or mechanical
deformation, GEOS uses one or more physics solvers. The Solvers tag is used to define and parameterize these
solvers. Different combinations of solvers can be applied in different regions of the domain at different moments of the
simulation.
In this first example, we use one type of solver in the entire domain and for the entire du-
ration of the simulation. The input file for this tutorial can be found in the repository at
inputFiles/singlePhaseFlow/3D_10x10x10_compressible_smoke.xml, which also includes input-
Files/singlePhaseFlow/3D_10x10x10_compressible_base.xml. The solver we are specifying here is a single-phase
flow solver. In GEOS, such a solver is created using a SinglePhaseFVM element. This type of solver is one among
several cell-centered single-phase finite volume methods.
The XML block used to define this single-phase finite volume solver is shown here:

<Solvers>
<SinglePhaseFVM
name="SinglePhaseFlow"
logLevel="1"
discretization="singlePhaseTPFA"
targetRegions="{ mainRegion }">
<NonlinearSolverParameters
newtonTol="1.0e-6"
newtonMaxIter="8"/>
<LinearSolverParameters
solverType="gmres"
(continues on next page)

12 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

preconditionerType="amg"
krylovTol="1.0e-10"/>
</SinglePhaseFVM>
</Solvers>

Each type of solver has a specific set of parameters that are required and some parameters that are optional. Optional
values are usually set with sensible default values.
name
First, we register a solver of type SinglePhaseFVM with a user-chosen name, here SinglePhaseFlow. This unique
user-defined name can be almost anything. However, some symbols are known to cause issues in names : avoid
commas, slashes, curly braces. GEOS is case-sensitive: it makes a distinction between two SinglePhaseFVM solvers
called mySolver and MySolver. Giving elements a name is a common practice in GEOS: users need to give unique
identifiers to objects they define. That name is the handle to this instance of a solver class.
logLevel
Then, we set a solver-specific level of console logging (logLevel set to 1 here). Notice that the value (1) is between
double-quotes. This is a general convention for all attributes: we write key="value" regardless of the value type
(integers, strings, lists, etc.).
For logLevel, higher values lead to more console output or intermediate results saved to files. When debugging,
higher logLevel values is often convenient. In production runs, you may want to suppress most console output.
discretization
For solvers of the SinglePhaseFVM family, one required attribute is a discretization scheme. Here, we use a Two-
Point Flux Approximation (TPFA) finite volume discretization scheme called singlePhaseTPFA. To know the list of
admissible values of an attribute, please see GEOS’s XML schema. This discretization type must know how to find
permeability values that it uses internally to compute transmissibilities. The permeabilityNames attribute tells the
solver the user-defined name (the handle) of the permeability values that will be defined elsewhere in the input file.
Note that the order of attributes inside an element is not important.
fluidNames, solidNames, targetRegions
Here, we specify a collection of fluids, rocks, and target regions of the mesh on which the solver will apply. Curly
brackets are used in GEOS inputs to indicate collections of values (sets or lists). The curly brackets used here are
necessary, even if the collection contains a single value. Commas are used to separate members of a set.
Nested elements
Finally, note that other XML elements can be nested inside the Solvers element. Here, we use specific XML ele-
ments to set values for numerical tolerances. The solver stops when numerical residuals are smaller than the specified
tolerances (convergence is achieved) or when the maximum number of iterations allowed is exceeded (convergence not
achieved).

Mesh
To solve this problem, we need to define a mesh for our numerical calculations. This is the role of the Mesh element.
There are two approaches to specifying meshes in GEOS: internal or external.
• The external approach allows to import mesh files created outside GEOS, such as a corner-point grid or an
unstructured grid representing complex shapes and structures.
• The internal approach uses GEOS’s built-in capability to create simple meshes from a small number of param-
eters. It does not require any external file information. The geometric complexity of internal meshes is limited,
but many practical problems can be solved on such simple grids.

1.2. Tutorials 13
GEOS Documentation

In this tutorial, to keep things self-contained, we use the internal mesh generator. We parameterize it with the Inter-
nalMesh element.

name
Just like for solvers, we register the InternalMesh element using a unique name attribute. Here the InternalMesh
object is instantiated with the name mesh.
elementTypes
We specify the collection of elements types that this mesh contains. Tetrahedra, hexahedra, and wedges are examples
of element types. If a mesh contains different types of elements (a hybrid mesh), we should indicate this here by listing
all unique types of elements in curly brackets. Keeping things simple, our element collection has only one type of
element: a C3D8 type representing a hexahedral element (linear 8-node brick).
A mesh can contain several geometrical types of elements. For numerical convenience, elements are aggregated by
types into cellBlocks. Here, we only have linear 8-node brick elements, so the entire domain is one object called
cellBlock.
xCoords, yCoords, zCoords, nx, ny, nz
This specifies the spatial arrangement of the mesh elements. The mesh defined here goes from coordinate x=0 to
x=10 in the x-direction, with nx=10 subdivisions along this segment. The same is true for the y-dimension and the
z-dimension. Our mesh is a cube of 10x10x10=1,000 elements with a bounding box defined by corner coordinates
(0,0,0) and (10,10,10).

14 Chapter 1. Table of Contents

GEOS Documentation

Geometry
The Geometry tag allows users to capture subregions of a mesh and assign them a unique name. Here, we name two
Box elements, one for the location of the source and one for the sink. Pressure values are assigned to these named
regions elsewhere in the input file.
The pressure source is the element in the (0,0,0) corner of the domain, and the sink is the element in the (10,10,10)
corner.
For an element to be inside a geometric region, it must have all its vertices strictly inside that region. Consequently, we
need to extend the geometry limits a small amount beyond the actual coordinates of the elements to catch all vertices.
Here, we use a safety padding of 0.01.
<Geometry>
<Box
name="source"
xMin="{ -0.01, -0.01, -0.01 }"
xMax="{ 1.01, 1.01, 1.01 }"/>

<Box
name="sink"
(continues on next page)

1.2. Tutorials 15
GEOS Documentation

(continued from previous page)

xMin="{ 8.99, 8.99, 8.99 }"
xMax="{ 10.01, 10.01, 10.01 }"/>
</Geometry>

There are several methods to achieve similar conditions (Dirichlet boundary condition on faces, etc.). The Box defined
here is one of the simplest approaches.

Events
In GEOS, we call Events anything that happens at a set time or frequency. Events are a central element for time-
stepping in GEOS, and a dedicated section just for events is necessary to give them the treatment they deserve.
For now, we focus on three simple events: the time at which we wish the simulation to end (maxTime), the times at
which we want the solver to perform updates, and the times we wish to have simulation output values reported.
In GEOS, all times are specified in seconds, so here maxTime=5000.0 means that the simulation will run from time 0
to time 5,000 seconds.
If we focus on the PeriodicEvent elements, we see :
1. A periodic solver application: this event is named solverApplications. With the attribute forceDt=20, it

16 Chapter 1. Table of Contents

GEOS Documentation

tells the solver to compute results at 20-second time intervals. We know what this event does by looking at its
target attribute: here, from time 0 to maxTime and with a forced time step of 20 seconds, we instruct GEOS to
call the solver registered as SinglePhaseFlow. Note the hierarchical structure of the target formulation, using
‘/’ to indicate a specific named instance (SinglePhaseFlow) of an element (Solvers). If the solver needs to
take smaller time steps, it is allowed to do so, but it will have to compute results for every 20-second increment
between time zero and maxTime regardless of possible intermediate time steps.
2. An output event: this event is used for reporting purposes and instructs GEOS to write out results at specific
frequencies. Here, we need to see results at every 100-second increment. This event triggers a full application
of solvers, even if solvers were not summoned by the previous event. In other words, an output event will force
an application of solvers, possibly in addition to the periodic events requested directly.

Numerical methods
GEOS comes with several useful numerical methods. In the Solvers elements, for instance, we had specified to use
a two-point flux approximation as discretization scheme for the finite volume single-phase solver. Now to use this
scheme, we need to supply more details in the NumericalMethods element.

Note that in GEOS, there is a difference between physics solvers and numerical methods. Their parameterizations are
thus independent. We can have multiple solvers using the same numerical scheme but with different tolerances, for
instance.
The available numerical methods and their options are listed in the GEOS XML schema documentation which may be
found by using the search function in the documentation.

Regions
In GEOS, ElementsRegions are used to attach material properties to regions of elements. Here, we use only one Cel-
lElementRegion to represent the entire domain (user name: mainRegion). It contains all the blocks called cellBlock
defined in the mesh section. We specify the materials contained in that region using a materialList. Several mate-
rials coexist in cellBlock, and we list them using their user-defined names: water and rock in this exemple. Each
material is a definition of physical properties.

<ElementRegions>
<CellElementRegion
name="mainRegion"
(continues on next page)

1.2. Tutorials 17
GEOS Documentation

(continued from previous page)

cellBlocks="{ * }"
materialList="{ water, rock }"/>
</ElementRegions>

Constitutive models
The Constitutive element attaches physical properties to all materials contained in the domain.
The physical properties of the materials defined as water, rockPorosity, and rockPerm are provided here,
each material being derived from a different material type: CompressibleSinglePhaseFluid for the water,
PressurePorosity for the rock porosity, and ConstantPermeability for rock permeability. The list of attributes
differs between these constitutive materials.

The names water, rockPorosity and rockPerm are defined by the user as handles to specific instances of physical
materials. GEOS uses S.I. units throughout, not field units. Pressures, for instance, are in Pascal, not psia. The x- and
y-permeability are set to 1.0e-12 m2 corresponding to approximately to 1 Darcy.
We have used the handles water, rockPorosity and rockPerm in the input file in the ElementRegions section of
the XML file, before the registration of these materials took place here, in Constitutive element.

ò Note

This highlights an important aspect of using XML in GEOS: the order in which objects are registered and used in
the XML file is not important.

18 Chapter 1. Table of Contents

GEOS Documentation

Defining properties
In the FieldSpecifications section, properties such as source and sink pressures are set. GEOS offers a lot of
flexibility to specify field values through space and time.
Spatially, in GEOS, all field specifications are associated to a target object on which the field values are mounted. This
allows for a lot of freedom in defining fields: for instance, one can have volume property values attached to a subset of
volume elements of the mesh, or surface properties attached to faces of a subset of elements.
For each FieldSpecification, we specify a name, a fieldName (this name is used by solvers or numerical meth-
ods), an objectPath, setNames and a scale. The ObjectPath is important and it reflects the internal class hier-
archy of the code. Here, for the fieldName pressure, we assign the value defined by scale (5e6 Pascal) to one of
the ElementRegions (class) called mainRegions (instance). More specifically, we target the elementSubRegions
called cellBlock (this contains all the C3D8 elements, effectively all the domain). The setNames allows to use the
elements defined in Geometry, or use everything in the object path (using the all).

The image below shows the pressures after the very first time step, with the domain initialized at 5 MPa, the sink at 0
MPa on the top right, and the source in the lower left corner at 10 MPa.

1.2. Tutorials 19
GEOS Documentation

Output
In order to retrieve results from a simulation, we need to instantiate one or multiple Outputs.
Here, we define a single object of type Silo. Silo is a library and a format for reading and writing a wide variety of
scientific data. Data in Silo format can be read by VisIt.
This Silo output object is called siloOutput. We had referred to this object already in the Events section: it was
the target of a periodic event named outputs. You can verify that the Events section is using this object as a target. It
does so by pointing to /Outputs/siloOutput.

GEOS currently supports outputs that are readable by VisIt and Kitware’s Paraview, as well as other visualization tools.
In this example, we only request a Silo format compatible with VisIt.
All elements are now in place to run GEOS.

20 Chapter 1. Table of Contents

GEOS Documentation

Running GEOS
The command to run GEOS is
path/to/geosx -i path/to/this/xml_file.xml
Note that all paths for files included in the XML file are relative to this XML file.
While running GEOS, it logs status information on the console output with a verbosity that is controlled at the object
level, and that can be changed using the logLevel flag.
The first few lines appearing to the console are indicating that the XML elements are read and registered correctly:

Adding Solver of type SinglePhaseFVM, named SinglePhaseFlow

Adding Mesh: InternalMesh, mesh
Adding Geometric Object: Box, source
Adding Geometric Object: Box, sink
Adding Event: PeriodicEvent, solverApplications
Adding Event: PeriodicEvent, outputs
Adding Output: Silo, siloOutput
Adding Object CellElementRegion named mainRegion from ObjectManager::Catalog.
mainRegion/cellBlock/water is allocated with 1 quadrature points.
mainRegion/cellBlock/rock is allocated with 1 quadrature points.
mainRegion/cellBlock/rockPerm is allocated with 1 quadrature points.
mainRegion/cellBlock/rockPorosity is allocated with 1 quadrature points.
mainRegion/cellBlock/nullSolid is allocated with 1 quadrature points.

Then, we go into the execution of the simulation itself:

Time: 0s, dt:20s, Cycle: 0

Attempt: 0, NewtonIter: 0
( R ) = ( 5.65e+00 ) ;
Attempt: 0, NewtonIter: 1
( R ) = ( 2.07e-04 ) ;
Last LinSolve(iter,res) = ( 63, 8.96e-11 ) ;
Attempt: 0, NewtonIter: 2
( R ) = ( 9.86e-11 ) ;
Last LinSolve(iter,res) = ( 70, 4.07e-11 ) ;

Each time iteration at every 20s interval is logged to console, until the end of the simulation at maxTime=5000:

Time: 4980s, dt:20s, Cycle: 249

Attempt: 0, NewtonIter: 0
( R ) = ( 4.74e-09 ) ;
Attempt: 0, NewtonIter: 1
( R ) = ( 2.05e-14 ) ;
Last LinSolve(iter,res) = ( 67, 5.61e-11 ) ;
SinglePhaseFlow: Newton solver converged in less than 4 iterations, time-step required␣
˓→will be doubled.

Cleaning up events
Umpire HOST sum across ranks: 14.8 MB
Umpire HOST rank max: 14.8 MB
total time 5.658s
initialization time 0.147s
run time 3.289s

All newton iterations are logged along with corresponding nonlinear residuals for each time iteration. In turn, for each

1.2. Tutorials 21
GEOS Documentation

newton iteration, LinSolve provides the number of linear iterations and the final residual reached by the linear solver.
Information on run times, initialization times, and maximum amounts of memory (high water mark) are given at the
end of the simulation, if successful.
Congratulations on completing this first run!

Visualization
Here, we have requested results to be written in Silo, a format compatible with VisIt. To visualize results, open VisIt
and directly load the database of simulation output files.
After a few time step, pressure between the source and sink are in equilibrium, as shown on the representation below.

To go further
Feedback on this tutorial
This concludes the single-phase internal mesh tutorial. For any feedback on this tutorial, please submit a GitHub issue
on the project’s GitHub page.
For more details
• More on single-phase flow solvers, please see Singlephase Flow Solver.

22 Chapter 1. Table of Contents

GEOS Documentation

• More on meshes, please see Meshes.

• More on events, please see Event Management.

1.2.2 Tutorial 2: External Meshes

Context
In this tutorial, we use a simple single-phase flow solver (see Singlephase Flow Solver) to solve for pressure propagation
on a mesh that is imported into GEOS. The main goal of this tutorial is to learn how to work with external meshes,
and to learn how easy it is to swap meshes on the same physical problem in GEOS. This makes GEOS a powerful tool
to solve real field applications with complex geometries and perform assessments of mesh geometry and resolution
effects.
Objectives
At the end of this tutorial you will know:
• the syntax and format of input meshes,
• how to input external files into a GEOS input XML file,
• how to run the same physical problem with two different meshes,
• how to use and visualize hexahedral and tetrahedral meshes.
Input Files
This tutorial uses an XML file containing the main input for GEOS and a separate file with all the mesh information.
As we will see later, the main XML file points to the external mesh file with an include statement. The XML input
file for this test case is located at:

inputFiles/singlePhaseFlow/vtk/3D_10x10x10_compressible_hex_gravity_smoke.xml

The mesh file format used in this tutorial is vtk. This format is a standard scientific meshing format not specific to
GEOS. vtk is a multi-purpose mesh format (structured, unstructured, serial, parallel, multi-block. . . ) and contains a
compact and complete representation of the mesh geometry and of its properties. The mesh file used here is human-
readable ASCII, and there is a binary storage as well. It contains a list of nodes with their (x,y,z) coordinates, and a list
of elements that are constructed from these nodes.

Hexahedral elements
In the first part of the tutorial, we will run flow simulations on a mesh made of hexahedral elements. These types of
elements are used in classical cartesian grids (sugar cubes) or corner-point grids or pillar grids.

Brief discussion about hexahedral meshes in GEOS

Although closely related, the hexahedral grids that GEOS can process are slightly different than either structured grid
or corner-point grids. The differences are worth pointing out here. In GEOS:
• Hexahedra can have irregular shapes: no pillars are needed and vertices can be anywhere in space. This is
useful for grids that turn, fold, or are heavily bent. Hexahedral blocks should nevertheless have 8 distinct vertices
that are not coalesced. Some tolerance exists for degeneration to wedges in some solvers (finite element solvers),
but it is best to avoid such situations and label elements according to their actual shape. Butterfly cells, flat cells,
negative or zero volume cells will cause problems.
• The mesh needs to be conformal: in 3D, this means that neighboring grid blocks have to share exactly a
complete face. Note that corner-point grids do not have this requirement and neighboring blocks can be offset.
When importing grids from commonly-used geomodeling packages, this is an important consideration. This
problem is solved by splitting shifted grid blocks to restore conformity. While it may seem convenient to be able
to have offset grid blocks at first, the advantages of conformal grids used in GEOS are worth the extra meshing

1.2. Tutorials 23
GEOS Documentation

effort: by using conformal grids, GEOS can run finite element and finite volume simulations on the same mesh
without problems, going seamlessly from one numerical method to the other. This is key to enabling multiphysics
simulation.
• There is no assumption of overall structure: GEOS does not need to know a number of block in the X, Y,
Z direction (no NX, NY, NZ) and does not assume that the mesh is a full cartesian domain that the interesting
parts of the reservoir must be carved out from. Blocks are numbered by indices that assume nothing about spatial
positioning and there is no concept of (i,j,k). This approach also implies that no “masks” are needed to remove
inactive or dead cells, as often done in cartesian grids to get the actual reservoir contours from a bounding box,
and here we only need to specify grid blocks that are active. For performance and flexibility, this lean approach
to meshes is important.

Importing an external mesh with VTK

In this first part of the tutorial, we use an hexahedral mesh provided to GEOS. This hexahedral mesh is strictly identical
to the grid used in the first tutorial (Tutorial 1: First Steps), but instead of using the internal grid generator GEOS, we
specify it with spatial node coordinates in vtk format. To import external grid into GEOS, we did develop a component
directly using the vtk library.
So here, our mesh consists of a simple sugar-cube stack of size 10x10x10. We inject fluid from one vertical face of a
cube (the face corresponding to x=0), and we let the pressure equilibrate in the closed domain. The displacement is
a single-phase, compressible fluid subject to gravity forces, so we expect the pressure to be constant on the injection
face, and to be close to hydrostatic on the opposite plane (x=10). We use GEOS to compute the pressure inside each
grid block over a period of time of 100 seconds.

To see how to import such a mesh, we inspect the following XML file:

inputFiles/singlePhaseFlow/vtk/3D_10x10x10_compressible_hex_gravity_smoke.xml

In the XML Mesh tag, instead of an InternalMesh tag, we have a VTKMesh tag. We see that a file called
cube_10x10x10_hex.vtk is imported using vtk, and this object is instantiated with a user-defined name value. The
file here contains geometric information in vtk format (it can also contain properties, as we will see in the next tutorial).

24 Chapter 1. Table of Contents

GEOS Documentation

Here is the vtk file :

Listing 1.1: cube_10x10x10_hex.vtk

# vtk DataFile Version 4.2
Cube structured points dataset
ASCII
DATASET STRUCTURED_POINTS
DIMENSIONS 11 11 11
ORIGIN 0.0 0.0 0.0
SPACING 1.0 1.0 1.0

GEOS can run different physical solvers on different regions of the mesh at different times. Here, to keep things simple,
we run one solver (single-phase flow) on the entire domain throughout the simulation. To do so, we need to define a
region encompassing the entire domain. We will name it Domain, as refered to in the single-phase flow solver (in its
targetRegions), and list its constitutive models in the materialList, which are water and rock. Since we have
imported a mesh with only one region, we can set cellBlocks to { * } (we have could also set cellBlocks to {
hexahedra } as the mesh has only hexahedral cells).
<ElementRegions>
<CellElementRegion
name="Domain"
cellBlocks="{ hexahedra }"
materialList="{ water, rock }"/>
</ElementRegions>

ò Note

If you use a name that is not hexahedra or all for this attribute, or if the mesh is changed and have not-hexahedral
cells, GEOS will throw an error at the beginning of the simulation. See Meshes for more information.

Running GEOS

The command to run GEOS is

path/to/geosx -i ../../../../../inputFiles/singlePhaseFlow/vtk/3D_10x10x10_compressible_
˓→hex_gravity_smoke.xml

Note that all paths for files included in the XML file are relative to this XML file, not to the GEOS executable. When
running GEOS, console messages will provide indications regarding the status of the simulation.
In our case, the first lines are:
Adding Mesh: VTKMesh, CubeHex
Adding Event: PeriodicEvent, solverApplications
Adding Event: PeriodicEvent, outputs
Adding Event: PeriodicEvent, restarts
(continues on next page)

1.2. Tutorials 25
GEOS Documentation

(continued from previous page)

Adding Solver of type SinglePhaseFVM, named SinglePhaseFlow
Adding Geometric Object: Box, left
Adding Output: Silo, siloOutput
Adding Output: Restart, restartOutput
Adding Object CellElementRegion named Domain from ObjectManager::Catalog.

This indicates initialization of GEOS. The mesh preprocessing tool VTKMesh is launched next, with console messages
as follows.

VTKMesh 'CubeHex': reading mesh from /path/to/inputFiles/singlePhaseFlow/vtk/cube_

˓→10x10x10_hex.vtk

Generating global Ids from VTK mesh

VTKMesh 'CubeHex': generating GEOS mesh data structure
Number of nodes: 1331
Number of elems: 1000
C3D8: 1000
Load balancing: min avg max
(element/rank): 1000 1000 1000

Notice the specification of the number of nodes (1331), and hexahedra (1000). After the adjacency calculations, GEOS
starts the simulation itself. with the time-step increments specified in the XML file.
At the end of your simulation, you should see something like:

Time: 96s, dt:2s, Cycle: 48

Time: 98s, dt:2s, Cycle: 49
Cleaning up events
SinglePhaseFlow, number of time steps: 50
SinglePhaseFlow, number of successful nonlinear iterations: 50
SinglePhaseFlow, number of successful linear iterations: 450
SinglePhaseFlow, number of time step cuts: 0
SinglePhaseFlow, number of discarded nonlinear iterations: 0
SinglePhaseFlow, number of discarded linear iterations: 0
Umpire HOST sum across ranks: 2.6 MB
Umpire HOST rank max: 2.6 MB
total time 3.518s
initialization time 0.132s
run time 3.076s

Process finished with exit code 0

Once this is done, GEOS is finished and we can inspect the outcome.

Visualization of results in VisIt

All results are written in a format compatible with VisIt. To load the results, point VisIt to the database file written
in the Silo output folder.

26 Chapter 1. Table of Contents

GEOS Documentation

We see that the face x=0 shown here in the back of the illustration applies a constant pressure boundary condition (col-
ored in red), whereas the face across from it displays a pressure field under gravity effect, equilibrated and hydrostatic.
These results are consistent with what we expect.
Let us now see if a tetrahedral mesh, under the same exact physical conditions, can reproduce these results.

Externally Generated Tetrahedral Elements

In the second part of the tutorial, we discretize the same cubic domain but with tetrahedral elements. Tetrahedral
meshes are not yet common in geomodeling but offer tremendous flexibility in modeling fracture planes, faults, complex
reservoir horizons and boundaries. Just like for hexahedral meshes, and for the same reasons (compatibility with finite
volume and finite element methods), tetrahedral meshes in GEOS must be conformal.
As stated previously, the problem we wish to solve here is the exact same physical problem as with hexahedral grid
blocks. We apply a constant pressure condition (injection) from the x=0 vertical face of the domain, and we let pressure
equilibrate over time. We observe the opposite side of the cube and expect to see hydrostatic pressure profiles because
of the gravitational effect. The displacement is a single phase, compressible flow subject to gravity forces. We use
GEOS to compute the pressure inside each grid block.
The set-up for this problem is almost identical to the hexahedral mesh set-up. We simply point our Mesh tag to include
a tetrahedral grid. The interest of not relying on I,J,K indices for any property specification or well trajectory makes it
easy to try different meshes for the same physical problems with GEOS. Swapping out meshes without requiring
other modifications to the input files makes mesh refinement studies easy to perform with GEOS.
Like before, the XML file for this problem is the following:

inputFiles/singlePhaseFlow/vtk/3D_10x10x10_compressible_tetra_gravity_smoke.xml

The only difference, is that now, the Mesh tag points GEOS to a different mesh file called cube_10x10x10_tet.vtk.
This file contains nodes and tetrahedral elements in vtk format, representing a different discretization of the exact same
10x10x10 cubic domain.

<Mesh>
<VTKMesh
(continues on next page)

1.2. Tutorials 27
GEOS Documentation

(continued from previous page)

name="CubeTetra"
file="cube_10x10x10_tet.vtk"/>
</Mesh>

The mesh now looks like this:

And the vtk file starts as follows (notice the tetrahedral point coordinates as real numbers):

Listing 1.2: cube_10x10x10_tet.vtk

# vtk DataFile Version 2.0
cube
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 366 float
0 0 10
0 0 0
0 10 10
0 10 0
10 0 10
10 0 0
10 10 10
10 10 0
0 0 1.666666666666662
0 0 3.333333333333323
0 0 4.999999999999986
0 0 6.666666666666647
0 0 8.333333333333321
0 1.666666666666662 10
0 3.333333333333323 10

Again, the entire field is one region called Domain which contains water and rock. Since we have imported a mesh

28 Chapter 1. Table of Contents

GEOS Documentation

with only one region, we can again set cellBlocks to { * } (we have could also set cellBlocks to { tetrahedra
} as the mesh has only tetrahedric cells).

Running GEOS

The command to run GEOS is

path/to/geosx -i ../../../../../inputFiles/singlePhaseFlow/vtk/3D_10x10x10_compressible_
˓→tetra_gravity_smoke.xml

Again, all paths for files included in the XML file are relative to this XML file, not to the GEOS executable. When
running GEOS, console messages will provide indications regarding the status of the simulation. In our case, the first
lines are:

Adding Mesh: VTKMesh, CubeTetra

Adding Event: PeriodicEvent, solverApplications
Adding Event: PeriodicEvent, outputs
Adding Event: PeriodicEvent, restarts
Adding Solver of type SinglePhaseFVM, named SinglePhaseFlow
Adding Geometric Object: Box, left
Adding Output: Silo, siloOutput
Adding Output: Restart, restartOutput
Adding Object CellElementRegion named Domain from ObjectManager::Catalog.

Followed by:

VTKMesh 'CubeTetra': reading mesh from /path/to/inputFiles/singlePhaseFlow/vtk/cube_

˓→10x10x10_tet.vtk

Generating global Ids from VTK mesh

VTKMesh 'CubeTetra': generating GEOS mesh data structure
Number of nodes: 366
Number of elems: 1153
C3D4: 1153
Load balancing: min avg max
(element/rank): 1153 1153 1153
regionQuadrature: meshBodyName, meshLevelName, regionName, subRegionName = CubeTetra,␣
˓→Level0, Domain, tetrahedra

CubeTetra/Level0/Domain/tetrahedra/water allocated 1 quadrature points

CubeTetra/Level0/Domain/tetrahedra/rock allocated 1 quadrature points

We see that we have now 366 nodes and 1153 tetrahedral elements. And finally, when the simulation is successfully
done we see:

Time: 0s, dt:1s, Cycle: 0

Time: 1s, dt:1s, Cycle: 1
Time: 2s, dt:1s, Cycle: 2
Time: 3s, dt:1s, Cycle: 3
(continues on next page)

1.2. Tutorials 29
GEOS Documentation

(continued from previous page)

Time: 4s, dt:1s, Cycle: 4
Time: 5s, dt:1s, Cycle: 5
...
Time: 95s, dt:1s, Cycle: 95
Time: 96s, dt:1s, Cycle: 96
Time: 97s, dt:1s, Cycle: 97
Time: 98s, dt:1s, Cycle: 98
Time: 99s, dt:1s, Cycle: 99
Cleaning up events
SinglePhaseFlow, number of time steps: 100
SinglePhaseFlow, number of successful nonlinear iterations: 100
SinglePhaseFlow, number of successful linear iterations: 1000
SinglePhaseFlow, number of time step cuts: 0
SinglePhaseFlow, number of discarded nonlinear iterations: 0
SinglePhaseFlow, number of discarded linear iterations: 0
Umpire HOST sum across ranks: 1.9 MB
Umpire HOST rank max: 1.9 MB
total time 5.837s
initialization time 0.094s
run time 5.432s

Process finished with exit code 0

Visualization of results in VisIt

All results are written in a format compatible with VisIt by default. If we load into VisIt the .database file found in the
Silo folder, we observe the following results:

Here, we can see that despite the different mesh sizes and shapes, we are able to recover our pressure profile without
any problems, or degradation in runtime performance.

30 Chapter 1. Table of Contents

GEOS Documentation

To go further
Feedback on this tutorial
This concludes the single-phase external mesh tutorial. For any feedback on this tutorial, please submit a GitHub issue
on the project’s GitHub page.
For more details
• A complete description of the Internal Mesh generator is found here Meshes.
• vtk is extensively documented. You can start browsing here.
• GEOS can handle tetrahedra, hexahedra, pyramids, wedges, prisms, and any combination thereof in one mesh.

1.2.3 Tutorial 3: Regions and Property Specifications

Context
In this tutorial, we set up a simple field case for single-phase flow simulation (see Singlephase Flow Solver). We
demonstrate how to run a basic flow simulation in the reservoir layer. We do not consider any coupling with wells.
Injection and production will be specified by imposing a high pressure in the cells close to the injection area and a low
pressure in the cells close to the production area.
Objectives
At the end of this tutorial you will know:
• how to import external mesh information and properties,
• how to run a specific solver (here, flow) in a specific region only,
• the basic method of using boxes to set up boundary conditions,
• how to use TableFunction to import fields varying in time and/or space,
• how to control output frequency and export results for visualization.
Input file
The XML input file for this test case is located at:

inputFiles/singlePhaseFlow/FieldCaseTutorial3_base.xml

inputFiles/singlePhaseFlow/FieldCaseTutorial3_smoke.xml

We consider the following mesh as a numerical support to the simulations in this tutorial:

1.2. Tutorials 31
GEOS Documentation

This mesh contains three continuous regions:

• a Bottom region (underburden, elementary tag = Underburden, attribute = 1)
• a Middle region (reservoir layer, elementary tag = Reservoir, attribute = 2)
• a Top region (overburden, elementary tag = Overburden, attribute = 3)

The mesh is defined using the VTK file format (see Meshes for more information on the supported mesh file format).
Each tetrahedron is associated to a unique tag.
The XML file considered here follows the typical structure of the GEOS input files:
1. Solver

32 Chapter 1. Table of Contents

GEOS Documentation

2. Mesh
3. Geometry
4. Events
5. NumericalMethods
6. ElementRegions
7. Constitutive
8. FieldSpecifications
9. Outputs
10. Functions

Single-phase solver
Let us inspect the Solver XML tags.

This node gathers all the information previously defined. We use a classical SinglePhaseFVM Finite Volume Method,
with the two-point flux approximation as will be defined in the NumericalMethods tag. The targetRegions refers
only to the Reservoir region because we only solve for flow in this region.
The NonlinearSolverParameters and LinearSolverParameters are used to set usual numerical solver parame-
ters such as the linear and nonlinear tolerances, the preconditioner and solver types or the maximum number of nonlinear
iterations.

Mesh
Here, we use the VTKMesh to load the mesh (see Importing the Mesh). The syntax to import external meshes is simple
: in the XML file, the mesh file is included with its relative or absolute path to the location of the GEOS XML file
and a user-specified name label for the mesh object.

1.2. Tutorials 33
GEOS Documentation

Geometry
Here, we are using definition of source and sink boxes in addition to the all box in order to flag sets of
nodes or cells which will act as injection or production.
<Geometry>
<Box
name="all"
xMin="{ -1e9, -1e9, -1e9 }"
xMax="{ 1e9, 1e9, 1e9 }"/>

In order to define a box, the user defines xMax and xMin, two diagonally opposite nodes of the box.

Events
The events are used here to guide the simulation through time, and specify when outputs must be triggered.
<Events maxTime="100.0e6">
<PeriodicEvent name="solverApplications"
forceDt="10.0e6"
target="/Solvers/SinglePhaseFlow" />

(continues on next page)

34 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

The Events tag is associated with the maxTime keyword defining the maximum time. If this time is ever reached or
exceeded, the simulation ends.
Two PeriodicEvent are defined. - The first one, solverApplications, is associated with the solver. The forceDt
keyword means that there will always be time-steps of 10e6 seconds. - The second, outputs, is associated with the
output. The timeFrequency keyword means that it will be executed every 10e6 seconds.

Numerical methods
Defining the numerical method used in the solver, we will provide information on how to discretize our equations. Here
a classical two-point flux approximation (TPFA) scheme is used to discretize water fluxes over faces.

Regions
Assuming that the overburden and the underburden are impermeable, and flow only takes place in the reservoir, we
need to define regions.
We need to define all the CellElementRegions according to the attribute values of the VTK file (which are
respectively 1, 2 and 3 for each region). As mentioned above, the solvers is only applied on the reservoir layer, (on
region 2). In this case, the ElementRegions tag is :

ò Note

This material list here is subject to change if the problem is not a single-phase flow problem.

1.2. Tutorials 35
GEOS Documentation

Constitutive models
We simulate a single-phase flow in the reservoir layer, hence with multiple types of materials, a fluid (water) and solid
(rock permeability and porosity).

The constitutive parameters such as the density, the viscosity, and the compressibility are specified in the International
System of Units.

ò Note

To consider an incompressible fluid, the user has to set the compressibility to 0.

ò Note

Currently GEOS handles permeability as a diagonal matrix, so the three values of the permeability tensor are set
individually using the component field. The ability for a full tensor permeability is planned for future releases.

Defining properties
The next step is to specify fields, including:
• The initial value (here, the pressure has to be initialized)
• The static properties (here, we have to define the permeability tensor and the porosity)

36 Chapter 1. Table of Contents

GEOS Documentation

• The boundary conditions (here, the injection and production pressure have to be set)

<FieldSpecification
name="sinkTerm"
(continues on next page)

1.2. Tutorials 37
GEOS Documentation

(continued from previous page)

objectPath="ElementRegions/Reservoir/2_tetrahedra"
fieldName="pressure"
scale="5e7"
setNames="{ sink }"/>
</FieldSpecifications>

You may note :

• All static parameters and initial value fields must have initialCondition field set to 1.
• The objectPath refers to the ElementRegion in which the field has its value,
• The setName field points to the box previously defined to apply the fields,
• name and fieldName have a different meaning: name is used to give a name to the XML block. This name must
be unique. fieldName is the name of the field registered in GEOS. This value has to be set according to the
expected input fields of each solver.

Output
The Outputs XML tag is used to trigger the writing of visualization files. Here, we write files in a format natively
readable by Paraview under the tag VTK:

ò Note

The name keyword defines the name of the output directory.

Using functions to specify properties

Eventually, one can define varying properties using TableFunction (Functions) under the Functions tag:

<TableFunction
name="initialPressureFunc"
inputVarNames="{ elementCenter }"
coordinateFiles="{ tables_FieldCaseTuto/xlin.geos, tables_FieldCaseTuto/ylin.geos,␣
˓→tables_FieldCaseTuto/zlin.geos }"

voxelFile="tables_FieldCaseTuto/pressure.geos"/>

<TableFunction
name="permxFunc"
inputVarNames="{ elementCenter }"
(continues on next page)

38 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

coordinateFiles="{ tables_FieldCaseTuto/xlin.geos, tables_FieldCaseTuto/ylin.geos,␣
˓→tables_FieldCaseTuto/zlin.geos }"

voxelFile="tables_FieldCaseTuto/permx.geos"
interpolation="nearest"/>

<TableFunction
name="permyFunc"
inputVarNames="{ elementCenter }"
coordinateFiles="{ tables_FieldCaseTuto/xlin.geos, tables_FieldCaseTuto/ylin.geos,␣
˓→tables_FieldCaseTuto/zlin.geos }"

voxelFile="tables_FieldCaseTuto/permy.geos"
interpolation="nearest"/>

<TableFunction
name="permzFunc"
inputVarNames="{ elementCenter }"
coordinateFiles="{ tables_FieldCaseTuto/xlin.geos, tables_FieldCaseTuto/ylin.geos,␣
˓→tables_FieldCaseTuto/zlin.geos }"

voxelFile="tables_FieldCaseTuto/permz.geos"
interpolation="nearest"/>
</Functions>

Here, the injection pressure is set to vary with time. Attentive reader might have noticed that sourceTerm was bound
to a TableFunction named timeInj under FieldSpecifications tag definition. The initial pressure is set based on the
values contained in the table formed by the files which are specified. In particular, the files xlin.geos, ylin.geos and
zlin.geos define a regular meshing of the bounding box containing the reservoir. The pressure.geos file then defines the
values of the pressure at those points.
We proceed in a similar manner as for pressure.geos to map a heterogeneous permeability field (here the 5th layer of
the SPE 10 test case) onto our unstructured grid. This mapping will use a nearest point interpolation rule.

1.2. Tutorials 39
GEOS Documentation

ò Note

The varying values imposed in values or passed through voxelFile are premultiplied by the scale attribute from
FieldSpecifications.

Running GEOS
The simulation can be launched with:

geosx -i FieldCaseTutorial3_smoke.xml

One can notice the correct load of the field function among the starting output messages

Adding Mesh: VTKMesh, SyntheticMesh

Adding Event: PeriodicEvent, solverApplications
Adding Event: PeriodicEvent, outputs
Adding Solver of type SinglePhaseFVM, named SinglePhaseFlow
Adding Geometric Object: Box, all
Adding Geometric Object: Box, source
Adding Geometric Object: Box, sink
Adding Output: VTK, reservoir_with_properties
TableFunction: timeInj
TableFunction: initialPressureFunc
TableFunction: permxFunc
TableFunction: permyFunc
TableFunction: permzFunc
Adding Object CellElementRegion named Reservoir from ObjectManager::Catalog.
Adding Object CellElementRegion named Burden from ObjectManager::Catalog.

Visualization of results
We can open the file syntheticReservoirVizFile.pvd with Paraview to visualize the simulation results. In the event block,
we have asked for the output to be generated at regular intervals throughout the simulation, we can thus visualize the
pressure distribution at different simulation times, showing the variation in the injection control.

40 Chapter 1. Table of Contents

GEOS Documentation

To go further
Feedback on this tutorial
This concludes this tutorial. For any feedback, please submit a GitHub issue on the project’s GitHub page.
For more details
• More on meshes, please see Meshes.
• More on events, please see Event Management.

1.2. Tutorials 41
GEOS Documentation

1.2.4 Tutorial 4: Boundary Conditions and Time-Dependent Functions

Context
In this tutorial, we use a small strain linear elastic based solid mechanics solver (see Solid Mechanics Solver) from
GEOS to solve for the bending problem of a three-dimensional cantilever beam. The beam is fixed at one end, and
subjects to a traction force pointing to the y-positive direction on the other end. The beam is deformed in the x-y plane.
Objectives
At the end of this tutorial, you will know:
• how to use the solid mechanics solver to solve a quasistatic problem,
• how to set up displacement boundary condition at element nodes,
• how to set up traction boundary condition on element surfaces,
• how to use a table function to control time-dependent loading.
Input file
This tutorial uses no external input files and everything required is contained within a single GEOS input file. The xml
input file for this test case is located at:

inputFiles/solidMechanics/beamBending_base.xml
inputFiles/solidMechanics/beamBending_benchmark.xml

Discretized computational domain

The following mesh is used in this tutorial:

This mesh contains 80 x 8 x 4 eight-node brick elements in the x, y and z directions, respectively. Here, the
InternalMesh is used to generate a structured three-dimensional mesh with C3D8 as the elementTypes. This mesh
is defined as a cell block with the name cb1.

<Mesh>
<InternalMesh
name="mesh1"
elementTypes="{ C3D8 }"
xCoords="{ 0, 80 }"
yCoords="{ 0, 8 }"
zCoords="{ 0, 4 }"
nx="{ 160 }"
ny="{ 16 }"
nz="{ 8 }"
(continues on next page)

42 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

cellBlockNames="{ cb1 }"/>
</Mesh>

Gravity
The gravity is turned off explicitly at the beginning of the input file:

Solid mechanics solver

The solid mechanics solver is based on the small strain Lagrangian finite element formulation. The problem is run
as QuasiStatic without considering the beam inertial. The computational domain is discretized by FE1, which is
defined in the NumericalMethods block. The material is designated as shale, whose properties are defined in the
Constitutive block.

Finite element discretization

The computational domain is discretized by C3D8 elements with the first order interpolation functions at each direction
in the parent domain. The 2 x 2 x 2 Gauss quadrature rule is adopted to be compatible with the first order interpolation
functions.

Constitutive model
Recall that in the SolidMechanicsLagrangianSSLE block, shale is designated as the material in the computational
domain. Here, the material is defined as linear isotropic.

1.2. Tutorials 43
GEOS Documentation

Boundary conditions
As aforementioned, the beam is fixed on one end, and subjects to surface traction on the other end. These bound-
ary conditions are set up through the FieldSpecifications block. Here, nodeManager and faceManager in the
objectPath indicate that the boundary conditions are applied to the element nodes and faces, respectively. Compo-
nent 0, 1, and 2 refer to the x, y, and z direction, respectively. And the non-zero values given by Scale indicate the
magnitude of the loading. Some shorthands, such as xneg and xpos, are used as the locations where the boundary
conditions are applied in the computational domain. For instance, xneg means the portion of the computational do-
main located at the left-most in the x-axis, while xpos refers to the portion located at the right-most area in the x-axis.
Similar shorthands include ypos, yneg, zpos, and zneg. Particularly, the time-dependent loading applied at the beam
tip is defined through a function with the name timeFunction.

Table function
A table function is used to define the time-dependent loading at the beam tip. The coordinates and values form
a time-magnitude pair for the loading time history. In this case, the loading magnitude increases linearly as the time
evolves.

<Functions>
<TableFunction
(continues on next page)

44 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="timeFunction"
inputVarNames="{ time }"
coordinates="{ 0.0, 10.0 }"
values="{ 0.0, 10.0 }"/>
</Functions>

Execution
Finally, the execution of the simulation is set up in the Events block, where target points to the solid mechanics
solver defined in the Solvers block, and the time increment forceDt is set as 1.0s.

Result
The deformed beam is shown as following (notice that the displacement is visually magnified):

To go further
Feedback on this tutorial
This concludes the solid mechanics for small-strain linear elasticity tutorial. For any feedback on this tutorial, please
submit a GitHub issue on the project’s GitHub page.
For more details
• More on meshes, please see Meshes.
• More on events, please see Event Management.

1.2. Tutorials 45
GEOS Documentation

1.3 Basic Examples

1.3.1 Multiphase Flow
Context
In this example, we set up a multiphase, multicomponent test case (see Compositional Multiphase Flow Solver). The
permeability field corresponds to the two bottom layers (layers 84 and 85) of the SPE10 test case. The thermody-
namic behavior of the fluid mixture is specified using a simple immiscible two-phase (Dead-Oil) model. Injection and
production are simulated using boundary conditions.
Objective
The main objective of this example is to review the main elements of a simple two-phase simulation in GEOS, including:
• the compositional multiphase flow solver,
• the multiphase constitutive models,
• the specifications of multiphase boundary conditions.
Input file
This example is based on the XML file located at

inputFiles/compositionalMultiphaseFlow/benchmarks/SPE10/deadOilSpe10Layers84_85_base_
˓→iterative.xml

The XML file considered here follows the typical structure of the GEOS input files:
1. Solver
2. Mesh
3. Geometry
4. Events
5. NumericalMethods
6. ElementRegions
7. Constitutive
8. FieldSpecifications
9. Outputs

Multiphase flow solver

In GEOS, the setup of a multiphase simulation starts in the Solvers XML block of the input file. This example relies on
a solver of type CompositionalMultiphaseFVM that implements a fully implicit finite-volume scheme based on the
standard two-point approximation of the flux (TPFA). More information on this solver can be found at Compositional
Multiphase Flow Solver.
Let us have a closer look at the Solvers XML block displayed below. The solver has a name (here, compflow) that can
be chosen by the user and is not imposed by GEOS. Note that this name is used in the Events XML block to trigger
the application of the solver. Using the targetRegions attribute, the solver defines the target regions on which it is
applied. In this example, there is only one region, named reservoir.
The CompositionalMultiphaseFVM block contains two important sub-blocks, namely NonlinearSolverParame-
ters and LinearSolverParameters. In NonlinearSolverParameters, one can finely tune the nonlinear tolerance,
the application of the linear search algorithm, and the heuristics used to increase the time step size. In Linear-
SolverParameters, the user can specify the linear tolerance, the type of (direct or iterative) linear solver, and the

46 Chapter 1. Table of Contents

GEOS Documentation

type of preconditioner, if any. For large multiphase flow problems, we recommend using an iterative linear solver
(solverType="gmres" or solverType="fgmres") combined with the multigrid reduction (MGR) preconditioner
(preconditionerType="mgr"). More information about the MGR preconditioner can be found in Linear Solvers.

ò Note

For non-trivial simulations, we recommend setting the initialDt attribute to a small value (relative to the time
scale of the problem) in seconds. If the simulation appears to be slow, use logLevel="1" in Compositional-
MultiphaseFVM to detect potential Newton convergence problems. If the Newton solver struggles, please set
lineSearchAction="Attempt" in NonlinearSolverParameters. If the Newton convergence is good, please add
logLevel="1" in the LinearSolverParameters block to detect linear solver problems, especially if an iterative
linear solver is used.

waterCompressibility="0.00000000041"
waterViscosity="0.0003"/>

</Constitutive>

Initial and boundary conditions

In the FieldSpecifications section, we define the initial and boundary conditions as well as the geological properties
(porosity, permeability). All this is done using SI units. Here, we focus on the specification of the initial and boundary
conditions for a simulation performed with the CompositionalMultiphaseFVM solver. We refer to Tutorial 1: First
Steps for a more general discussion on the FieldSpecification XML blocks.
For a simulation performed with the CompositionalMultiphaseFVM solver, we have to set the initial pressure as
well as the initial global component fractions (in this case, the oil and water component fractions). The component
attribute of the FieldSpecification XML block must use the order in which the phaseNames have been defined
in the DeadOilFluid XML block. In other words, component=0 is used to initialize the oil global component
fraction and component=1 is used to initialize the water global component fraction, because we previously set
phaseNames="{oil, water}" in the DeadOilFluid XML block.
To specify the sink terms, we use the FieldSpecification mechanism in a similar fashion to impose the sink pressure
and composition. This is done to mimic a pressure-controlled well (before breakthrough). To specify the source term,
we use a SourceFlux block to impose a fixed mass injection rate of component 1 (water) to mimic a rate-controlled
well.

<FieldSpecifications>
<FieldSpecification
name="permx"
(continues on next page)

1.3. Basic Examples 51

GEOS Documentation

(continued from previous page)

component="0"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="rockPerm_permeability"
functionName="permxFunc"
scale="9.869233e-16"/>
<FieldSpecification
name="permy"
component="1"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="rockPerm_permeability"
functionName="permyFunc"
scale="9.869233e-16"/>
<FieldSpecification
name="permz"
component="2"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="rockPerm_permeability"
functionName="permzFunc"
scale="9.869233e-16"/>

<FieldSpecification
name="initialPressure"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="pressure"
scale="4.1369e+7"/>
<FieldSpecification
name="initialComposition_oil"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="globalCompFraction"
component="0"
scale="0.9995"/>
<FieldSpecification
name="initialComposition_water"
(continues on next page)

52 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir/block"
fieldName="globalCompFraction"
component="1"
scale="0.0005"/>

</FieldSpecifications>

Output
In this section, we request an output of the results in VTK format. Note that the name defined here must match the
names used in the Events XML block to define the output frequency.

</Outputs>

All elements are now in place to run GEOS.

1.3. Basic Examples 53

GEOS Documentation

Running GEOS
The first few lines appearing to the console are indicating that the XML elements are read and registered correctly:

Adding Solver of type CompositionalMultiphaseFVM, named compflow

Adding Mesh: InternalMesh, mesh
Adding Geometric Object: Box, source
Adding Geometric Object: Box, sink1
Adding Geometric Object: Box, sink2
Adding Geometric Object: Box, sink3
Adding Geometric Object: Box, sink4
Adding Event: PeriodicEvent, outputs
Adding Event: PeriodicEvent, solverApplications
TableFunction: permxFunc
TableFunction: permyFunc
TableFunction: permzFunc
TableFunction: poroFunc
TableFunction: B_o_table
TableFunction: visc_o_table
Adding Output: VTK, vtkOutput
Adding Object CellElementRegion named region from ObjectManager::Catalog.
region/block/fluid is allocated with 1 quadrature points.
region/block/rock is allocated with 1 quadrature points.
aaregion/block/relperm is allocated with 1 quadrature points.

At this point, we are done with the case set-up and the code steps into the execution of the simulation itself:

Time: 0s, dt:1000s, Cycle: 0

Attempt: 0, NewtonIter: 0
( Rfluid ) = (2.28e+00) ; ( R ) = ( 2.28e+00 ) ;
Attempt: 0, NewtonIter: 1
( Rfluid ) = (8.83e-03) ; ( R ) = ( 8.83e-03 ) ;
Last LinSolve(iter,res) = ( 2, 2.74e-03 ) ;
Attempt: 0, NewtonIter: 2
( Rfluid ) = (8.86e-05) ; ( R ) = ( 8.86e-05 ) ;
Last LinSolve(iter,res) = ( 2, 8.92e-03 ) ;

compflow: Max phase CFL number: 0.00399585

compflow: Max component CFL number: 0.152466
compflow: Newton solver converged in less than 16 iterations, time-step required will be␣
˓→doubled.

Visualization
A file compatible with Paraview is produced in this example. It is found in the output folder, and usually has the
extension .pvd. More details about this file format can be found here. We can load this file into Paraview directly and
visualize results:

54 Chapter 1. Table of Contents

GEOS Documentation

To go further
Feedback on this example
This concludes the example on setting up an immiscible two-phase flow simulation in a channelized permeability field.
For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.
For more details
• A complete description of the reservoir flow solver is found here: Compositional Multiphase Flow Solver.
• The available constitutive models are listed at Constitutive Models.

1.3.2 Multiphase Flow with Wells

Context
In this example, we build on the concepts presented in Multiphase Flow to show how to set up a multiphase water
injection problem with wells in the three-dimensional Egg model. The twelve wells (four producers and eight injectors)
are placed according to the description of the original test case.
Objectives
In this example, we re-use many GEOS features already presented in Multiphase Flow, but we now focus on:
• how to import an external mesh with embedded geological properties (permeability) in the VTK format (.vtu),
• how to set up the wells.
Input file
This example is based on the XML file located at

distanceFromHead="18"/>
<Perforation
name="producer2_perf6"
distanceFromHead="22"/>
<Perforation
name="producer2_perf7"
distanceFromHead="26"/>
</InternalWell>

GEOS Documentation

Outputs
In this section, we request an output of the results in VTK format and an output of the rates for each producing well.
Note that the name defined here must match the name used in the Events XML block to define the output frequency.

</Outputs>

Tasks
In the Events block, we have defined four events requesting that a task periodically collects the rate for each producing
well. This task is defined here, in the PackCollection XML sub-block of the Tasks block. The task contains the path
to the object on which the field to collect is registered (here, a WellElementSubRegion) and the name of the field
(here, wellElementMixtureConnectionRate). The details of the history collection mechanism can be found in
Tasks Manager.

<PackCollection
(continues on next page)

66 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="wellRateCollection3"
objectPath="ElementRegions/wellRegion3/wellRegion3UniqueSubRegion"
fieldName="wellElementMixtureConnectionRate"/>

All elements are now in place to run GEOS.

Running GEOS
The first few lines appearing to the console are indicating that the XML elements are read and registered correctly:

Adding Mesh: VTKMesh, mesh

Adding Mesh: InternalWell, wellProducer1
Adding Mesh: InternalWell, wellProducer2
Adding Mesh: InternalWell, wellProducer3
Adding Mesh: InternalWell, wellProducer4
Adding Mesh: InternalWell, wellInjector1
Adding Mesh: InternalWell, wellInjector2
Adding Mesh: InternalWell, wellInjector3
Adding Mesh: InternalWell, wellInjector4
Adding Mesh: InternalWell, wellInjector5
Adding Mesh: InternalWell, wellInjector6
Adding Mesh: InternalWell, wellInjector7
Adding Mesh: InternalWell, wellInjector8
Adding Solver of type CompositionalMultiphaseReservoir, named coupledFlowAndWells
Adding Solver of type CompositionalMultiphaseFVM, named compositionalMultiphaseFlow
Adding Solver of type CompositionalMultiphaseWell, named compositionalMultiphaseWell
Adding Event: PeriodicEvent, vtk
Adding Event: PeriodicEvent, timeHistoryOutput1
Adding Event: PeriodicEvent, timeHistoryOutput2
Adding Event: PeriodicEvent, timeHistoryOutput3
Adding Event: PeriodicEvent, timeHistoryOutput4
Adding Event: PeriodicEvent, solverApplications
Adding Event: PeriodicEvent, timeHistoryCollection1
Adding Event: PeriodicEvent, timeHistoryCollection2
Adding Event: PeriodicEvent, timeHistoryCollection3
Adding Event: PeriodicEvent, timeHistoryCollection4
Adding Event: PeriodicEvent, restarts
Adding Output: VTK, vtkOutput
Adding Output: TimeHistory, timeHistoryOutput1
Adding Output: TimeHistory, timeHistoryOutput2
Adding Output: TimeHistory, timeHistoryOutput3
Adding Output: TimeHistory, timeHistoryOutput4
Adding Output: Restart, restartOutput
Adding Object CellElementRegion named reservoir from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion1 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion2 from ObjectManager::Catalog.
(continues on next page)

1.3. Basic Examples 67

GEOS Documentation

(continued from previous page)

Adding Object WellElementRegion named wellRegion3 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion4 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion5 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion6 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion7 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion8 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion9 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion10 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion11 from ObjectManager::Catalog.
Adding Object WellElementRegion named wellRegion12 from ObjectManager::Catalog.

This is followed by the creation of the 18553 hexahedral cells of the imported mesh. At this point, we are done with
the case set-up and the code steps into the execution of the simulation itself:

Time: 0s, dt:10000s, Cycle: 0

Attempt: 0, ConfigurationIter: 0, NewtonIter: 0
( Rflow ) = ( 1.01e+01 ) ; ( Rwell ) = ( 4.96e+00 ) ; ( R ) = ( 1.13e+01 ) ;
Attempt: 0, ConfigurationIter: 0, NewtonIter: 1
( Rflow ) = ( 1.96e+00 ) ; ( Rwell ) = ( 8.07e-01 ) ; ( R ) = ( 2.12e+00 ) ;
Last LinSolve(iter,res) = ( 44, 8.96e-03 ) ;
Attempt: 0, ConfigurationIter: 0, NewtonIter: 2
( Rflow ) = ( 4.14e-01 ) ; ( Rwell ) = ( 1.19e-01 ) ; ( R ) = ( 4.31e-01 ) ;
Last LinSolve(iter,res) = ( 44, 9.50e-03 ) ;
Attempt: 0, ConfigurationIter: 0, NewtonIter: 3
( Rflow ) = ( 1.77e-02 ) ; ( Rwell ) = ( 9.38e-03 ) ; ( R ) = ( 2.00e-02 ) ;
Last LinSolve(iter,res) = ( 47, 8.69e-03 ) ;
Attempt: 0, ConfigurationIter: 0, NewtonIter: 4
( Rflow ) = ( 1.13e-04 ) ; ( Rwell ) = ( 5.09e-05 ) ; ( R ) = ( 1.24e-04 ) ;
Last LinSolve(iter,res) = ( 50, 9.54e-03 ) ;
Attempt: 0, ConfigurationIter: 0, NewtonIter: 5
( Rflow ) = ( 2.17e-08 ) ; ( Rwell ) = ( 1.15e-07 ) ; ( R ) = ( 1.17e-07 ) ;
Last LinSolve(iter,res) = ( 55, 2.71e-04 ) ;
coupledFlowAndWells: Newton solver converged in less than 15 iterations, time-step␣
˓→required will be doubled.

We have instructed GEOS to output the time series of rates for each producer. The data contained in the corresponding
HDF5 files can be extracted and plotted as shown below.

To go further
Feedback on this example
This concludes the example on setting up a Dead-Oil simulation in the Egg model. For any feedback on this example,
please submit a GitHub issue on the project’s GitHub page.
For more details
• A complete description of the reservoir flow solver is found here: Compositional Multiphase Flow Solver.

68 Chapter 1. Table of Contents

GEOS Documentation

3500 Producer #1
Producer #2
Producer #3
3000 Producer #4
total rate [cubic meters per day]

2500

2000

1500

1000

500

0
0 20 40 60 80 100 120 140 160
time [days]

1.3. Basic Examples 69

GEOS Documentation

• The well solver is description at Compositional Multiphase Well Solver.

• The available constitutive models are listed at Constitutive Models.

1.3.3 CO 2 Injection
Context
In this example, we show how to set up a multiphase simulation of CO 2 injection.
Objectives
At the end of this example you will know:
• how to set up a CO 2 injection scenario with a well,
• how to run a case using MPI-parallelism.
Input file
The XML file for this test case is located at :

inputFiles/compositionalMultiphaseWell/simpleCo2InjTutorial_base.xml

inputFiles/compositionalMultiphaseWell/simpleCo2InjTutorial_smoke.xml

This mesh is a simple internally generated regular grid (50 x 1 x 150). A single CO 2 injection well is at the center of
the reservoir.
The XML file considered here follows the typical structure of the GEOS input files:
1. Solver
2. Mesh
3. Events
4. NumericalMethods
5. ElementRegions
6. Constitutive
7. FieldSpecifications
8. Outputs
9. Tasks

Multiphase flow and well solvers

Let us inspect the Solver XML tags. They consist of three blocks CompositionalMultiphaseFVM, Compositional-
MultiphaseWell and CompositionalMultiphaseReservoir, which are respectively handling the solution from multi-
phase flow in the reservoir, multiphase flow in the wells, and coupling between those two parts.

<Solvers>
<CompositionalMultiphaseReservoir
name="coupledFlowAndWells"
flowSolverName="compositionalMultiphaseFlow"
wellSolverName="compositionalMultiphaseWell"
logLevel="1"
initialDt="1e2"
targetRegions="{ reservoir, wellRegion }">
(continues on next page)

70 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

In the CompositionalMultiphaseFVM (Compositional Multiphase Flow Solver), a classical multiphase compositional

solver with a TPFA discretization is described.
The CompositionalMultiphaseWell (Compositional Multiphase Well Solver) consists of wellbore specifications (see
Multiphase Flow with Wells for detailed example). As its reservoir counterpart, it includes references to fluid and
relative permeability models, but also defines a WellControls sub-tag. This sub-tag specifies the CO 2 injector control
mode: the well is initially rate-controlled, with a rate specified in targetTotalRate and a maximum pressure specified
in targetBHP. The injector-specific attribute, injectionStream, describes the composition of the injected mixture
(here, pure CO 2 ).
The CompositionalMultiphaseReservoir coupling section describes the binding between those two previous elements
(see Poromechanics for detailed example on coupling physics in GEOS). In addition to being bound to the previously

1.3. Basic Examples 71

GEOS Documentation

described blocks through flowSolverName and wellSolverName sub-tags, it contains the initialDt starting time-
step size value and defines the NonlinearSolverParameters and LinearSolverParameters that are used to control
Newton-loop and linear solver behaviors (see Linear Solvers for a detailed description of linear solver attributes).

ò Note

To use the linear solver options of this example, you need to ensure that GEOS is configured to use the Hypre linear
solver package.

Mesh and well geometry

In this example, the Mesh tag is used to generate the reservoir mesh internally (Tutorial 1: First Steps). The in-
ternal generation of well is defined with the InternalWell sub-tag. Apart from the name identifier attribute and their
wellRegionName (ElementRegions) and wellControlsName (Solver) binding attributes, polylineNodeCoords and
polylineSegmentConn attributes are used to define the path of the wellbore and connections between its nodes. The
numElementsPerSegment discretizes the wellbore segments while the radius attribute specifies the wellbore ra-
dius (Multiphase Flow with Wells for details on wells). Once the wellbore is defined and discretized, the position of
Perforations is defined using the linear distance from the head of the wellbore (distanceFromHead).

ò Note

It is the responsibility of the user to make sure that there is a perforation in the bottom cell of the well mesh,
otherwise an error will be thrown and the simulation will terminate.

72 Chapter 1. Table of Contents

GEOS Documentation

Events
The solver is applied as a periodic event whose target is referred to as coupledFlowAndWells nametag. Using the
maxEventDt attribute, we specify a max time step size of 5 x 106 seconds.
The output event triggers a VTK output every 107 seconds, constraining the solver schedule to match exactly these
dates. The output path to data is specified as a target of this PeriodicEvent.
Another periodic event is defined under the name restarts. It consists of saved checkpoints every 5 x 107 seconds,
whose physical output folder name is defined under the Output tag.
Finally, the time history collection and output events are used to trigger the mechanisms involved in the generation of
a time series of well pressure (see the procedure outlined in Tasks Manager, and the example in Multiphase Flow with
Wells).

</Events>

Numerical methods
The TwoPointFluxApproximation is chosen for the fluid equation discretization. The tag specifies:
• A primary field to solve for as fieldName. For a flow problem, this field is pressure.
• A set of target regions in targetRegions.

1.3. Basic Examples 73

GEOS Documentation

• A coefficientName pointing to the field used for TPFA transmissibilities construction.

• A coefficientModelNames used to specify the permeability constitutive model(s).

Element regions
We define a CellElementRegion pointing to all reservoir mesh cells, and a WellElementRegion for the well. The two
regions contain a list of constitutive model names. The keyword “all” is used here to automatically select all cells of
the mesh.

Constitutive laws
Under the Constitutive tag, four items can be found:
• CO2BrinePhillipsFluid : this tag defines phase names, component molar weights, and fluid behaviors such as
CO 2 solubility in brine and viscosity/density dependencies on pressure and temperature.
• PressurePorosity : this tag contains all the data needed to model rock compressibility.
• BrooksCoreyRelativePermeability : this tag defines the relative permeability model for each phase, its end-
point values, residual volume fractions (saturations), and the Corey exponents.
• ConstantPermeability : this tag defines the permeability model that is set to a simple constant diagonal ten-
sor, whose values are defined in permeabilityComponent. Note that these values will be overwritten by the
permeability field imported in FieldSpecifications.

<CompressibleSolidConstantPermeability
name="rock"
solidModelName="nullSolid"
(continues on next page)

74 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

porosityModelName="rockPorosity"
permeabilityModelName="rockPerm"/>

</Constitutive>

The PVT data specified by CO2BrinePhillipsFluid is set to model the behavior of the CO 2 -brine system as a function
of pressure, temperature, and salinity. We currently rely on a two-phase, two-component (CO 2 and H 2 O) model in
which salinity is a constant parameter in space and in time. The model is described in detail in CO2-brine model. The
model definition requires three text files:
In co2flash.txt, we define the CO 2 solubility model used to compute the amount of CO 2 dissolved in the brine phase
as a function of pressure (in Pascal), temperature (in Kelvin), and salinity (in units of molality):

FlashModel CO2Solubility 1e6 1.5e7 5e4 367.15 369.15 1 0

The first keyword is an identifier for the model type (here, a flash model). It is followed by the model name. Then,
the lower, upper, and step increment values for pressure and temperature ranges are specified. The trailing 0 defines a
zero-salinity in the model. Note that the water component is not allowed to evaporate into the CO 2 -rich phase.
The pvtgas.txt and pvtliquid.txt files define the models used to compute the density and viscosity of the two phases, as
follows:

DensityFun SpanWagnerCO2Density 1.0e5 7.5e7 1e5 285.15 395.15 5

ViscosityFun FenghourCO2Viscosity 1.0e5 7.5e7 1e5 285.15 395.15 5

DensityFun PhillipsBrineDensity 1.0e5 7.5e7 1e5 285.15 395.15 5 0

ViscosityFun PhillipsBrineViscosity 0

In these files, the first keyword of each line is an identifier for the model type (either a density or a viscosity model). It
is followed by the model name. Then, the lower, upper, and step increment values for pressure and temperature ranges
are specified. The trailing 0 for PhillipsBrineDensity and PhillipsBrineViscosity entry is the salinity of the
brine, set to zero.

1.3. Basic Examples 75

GEOS Documentation

ò Note

It is the responsibility of the user to make sure that the pressure and temperature values encountered in the simulation
(in the reservoir and in the well) are within the bounds specified in the PVT files. GEOS will not throw an error if
a value outside these bounds is encountered, but the (nonlinear) behavior of the simulation and the quality of the
results will likely be negatively impacted.

Property specification
The FieldSpecifications tag is used to declare fields such as directional permeability, reference porosity, initial pressure,
and compositions. Here, these fields are homogeneous, except for the permeability field that is taken as an heteroge-
neous log-normally distributed field and specified in Functions as in Tutorial 3: Regions and Property Specifications.
<FieldSpecifications>
<FieldSpecification
name="permx"
initialCondition="1"
component="0"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="rockPerm_permeability"
scale="1e-15"
functionName="permxFunc"/>

<FieldSpecification
(continues on next page)

76 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="initialComposition_co2"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/reservoir"
fieldName="globalCompFraction"
component="0"
scale="0.0"/>

ò Note

In this case, we are using the same permeability field (perm.geos) for all the directions. Note also that the
fieldName values are set to rockPerm_permeability to access the permeability field handled as a Constitutive
law. These permeability values will overwrite the values already set in the Constitutive block.

. Warning

This XML file example does not take into account elevation when imposing the intial pressure with
initialPressure. Consider using a “HydrostraticEquilibrium” for a closer answer to modeled physical pro-
cesses.

Output
The Outputs XML tag is used to write visualization, restart, and time history files.
Here, we write visualization files in a format natively readable by Paraview under the tag VTK. A Restart tag is also be
specified. In conjunction with a PeriodicEvent, a restart file allows to resume computations from a set of checkpoints
in time. Finally, we require an output of the well pressure history using the TimeHistory tag.

(continues on next page)

1.3. Basic Examples 77

GEOS Documentation

(continued from previous page)

</Outputs>

Tasks
In the Events block, we have defined an event requesting that a task periodically collects the pressure at the well. This
task is defined here, in the PackCollection XML sub-block of the Tasks block. The task contains the path to the
object on which the field to collect is registered (here, a WellElementSubRegion) and the name of the field (here,
pressure). The details of the history collection mechanism can be found in Tasks Manager.

</Tasks>

Running GEOS
The simulation can be launched with 4 cores using MPI-parallelism:

mpirun -np 4 geosx -i simpleCo2InjTutorial_smoke.xml -x 1 -y 1 -z 4

A restart from a checkpoint file simpleCo2InjTutorial_restart_000000024.root is always available thanks to the follow-
ing command line :

mpirun -np 4 geosx -i simpleCo2InjTutorial_smoke.xml -r simpleCo2InjTutorial_restart_

˓→000000024 -x 1 -y 1 -z 4

GEOS Documentation

The heterogeneous values of the log permeability field can also be visualized in Paraview as shown below:

To go further
Feedback on this example
This concludes the CO 2 injection field case example. For any feedback on this example, please submit a GitHub issue
on the project’s GitHub page.
For more details
• A complete description of the reservoir flow solver is found here: Compositional Multiphase Flow Solver.
• The well solver is described at Compositional Multiphase Well Solver.
• The available fluid constitutive models are listed at Fluid Models.

1.3.4 Poromechanics
Context
In this example, we use a coupled solver to solve a poroelastic Terzaghi-type problem, a classic benchmark in poroe-
lasticity. We do so by coupling a single phase flow solver with a small-strain Lagrangian mechanics solver.
Objectives
At the end of this example you will know:
• how to use multiple solvers for poromechanical problems,
• how to define finite elements and finite volume numerical methods.
Input file
This example uses no external input files and everything required is contained within two GEOS input files located at:

1.3. Basic Examples 79

GEOS Documentation

inputFiles/poromechanics/PoroElastic_Terzaghi_base_direct.xml

inputFiles/poromechanics/PoroElastic_Terzaghi_smoke.xml

Description of the case

We simulate the consolidation of a poroelastic fluid-saturated column of height 𝐿 having unit cross-section. The column
is instantaneously loaded at time 𝑡 = 0 s with a constant compressive traction 𝑤 applied on the face highlighted in red
in the figure below. Only the loaded face if permeable to fluid flow, with the remaining parts of the boundary subject
to roller constraints and impervious.

Fig. 1.1: Sketch of the setup for Terzaghi’s problem.

GEOS will calculate displacement and pressure fields along the column as a function of time. We will use the analytical
solution for pressure to check the accuracy of the solution obtained with GEOS, namely
∞
(2𝑚 + 1)2 𝜋 2 𝑐𝑐 𝑡
[︂ ]︂ [︂ ]︂
4 ∑︁ 1 (2𝑚 + 1)𝜋𝑥
𝑝(𝑥, 𝑡) = 𝑝0 exp − sin ,
𝜋 𝑚=0 2𝑚 + 1 4𝐿2 2𝐿

where 𝑝0 = 𝐾𝑣 𝑆𝑏𝜖 +𝑏2 |𝑤| is the initial pressure, constant throughout the column, and 𝑐𝑐 = 𝜅 𝐾𝑣
𝜇 𝐾𝑣 𝑆𝜖 +𝑏2 is the consolida-
tion coefficient (or diffusion coefficient), with
• 𝑏 Biot’s coefficient
𝐸(1−𝜈)
• 𝐾𝑣 = (1+𝜈)(1−2𝜈) the uniaxial bulk modulus, 𝐸 Young’s modulus, and 𝜈 Poisson’s ratio

• 𝑆𝜖 = (𝑏−𝜑)(1−𝑏)
𝐾 + 𝜑𝑐𝑓 the constrained specific storage coefficient, 𝜑 porosity, 𝐾 = 𝐸
3(1−2𝜈) the bulk modulus,
and 𝑐𝑓 the fluid compressibility
• 𝜅 the isotropic permeability
• 𝜇 the fluid viscosity
𝐿2
The characteristic consolidation time of the system is defined as 𝑡𝑐 = 𝑐𝑐 . Knowledge of 𝑡𝑐 is useful for choosing
appropriately the timestep sizes that are used in the discrete model.

Coupled solvers
GEOS is a multi-physics tool. Different combinations of physics solvers available in the code can be applied in different
regions of the mesh at different moments of the simulation. The XML Solvers tag is used to list and parameterize
these solvers.
We define and characterize each single-physics solver separately. Then, we define a coupling solver between these
single-physics solvers as another, separate, solver. This approach allows for generality and flexibility in our multi-
physics resolutions. The order in which these solver specifications is done is not important. It is important, though, to
instantiate each single-physics solver with meaningful names. The names given to these single-physics solver instances
will be used to recognize them and create the coupling.
To define a poromechanical coupling, we will effectively define three solvers:
• the single-physics flow solver, a solver of type SinglePhaseFVM called here SinglePhaseFlowSolver (more
information on these solvers at Singlephase Flow Solver),
• the small-stress Lagrangian mechanics solver, a solver of type SolidMechanicsLagrangianSSLE called here
LinearElasticitySolver (more information here: Solid Mechanics Solver),

80 Chapter 1. Table of Contents

GEOS Documentation

• the coupling solver that will bind the two single-physics solvers above, an object of type
SinglePhasePoromechanics called here PoroelasticitySolver (more information at Poromechan-
ics Solver).
Note that the name attribute of these solvers is chosen by the user and is not imposed by GEOS.
The two single-physics solvers are parameterized as explained in their respective documentation.
Let us focus our attention on the coupling solver. This solver (PoroelasticitySolver) uses a set of attributes that
specifically describe the coupling for a poromechanical framework. For instance, we must point this solver to the correct
fluid solver (here: SinglePhaseFlowSolver), the correct solid solver (here: LinearElasticitySolver). Now that
these two solvers are tied together inside the coupling solver, we have a coupled multiphysics problem defined. More
parameters are required to characterize a coupling. Here, we specify the discretization method (FE1, defined further in
the input file), and the target regions (here, we only have one, Domain).

Multiphysics numerical methods

Numerical methods in multiphysics settings are similar to single physics numerical methods. All can be defined under
the same NumericalMethods XML tag. In this problem, we use finite volume for flow and finite elements for solid
mechanics. Both methods require additional parameterization attributes to be defined here.
As we have seen before, the coupling solver and the solid mechanics solver require the specification of a discretization
method called FE1. This discretization method is defined here as a finite element method using linear basis functions
and Gaussian quadrature rules. For more information on defining finite elements numerical schemes, please see the
dedicated FiniteElement section.
The finite volume method requires the specification of a discretization scheme. Here, we use a two-point flux approxi-
mation as described in the dedicated documentation (found here: FiniteVolume).

<NumericalMethods>
<FiniteElements>
<FiniteElementSpace
(continues on next page)

1.3. Basic Examples 81

GEOS Documentation

(continued from previous page)

name="FE1"
order="1"/>
</FiniteElements>

Mesh, material properties, and boundary conditions

Last, let us take a closer look at the geometry of this simple problem. We use the internal mesh generator to create a
beam-like mesh, with one single element along the Y and Z axes, and 21 elements along the X axis. All the elements
are hexahedral elements (C3D8) of the same dimension (1x1x1 meters).

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Units Value

𝐸 Young’s modulus [Pa] 104
𝜈 Poisson’s ratio [-] 0.2
𝑏 Biot’s coefficient [-] 1.0
𝜑 Porosity [-] 0.3
𝜌𝑓 Fluid density [kg/m3 ] 1.0
𝑐𝑓 Fluid compressibility [Pa-1 ] 0.0
𝜅 Permeability [m2 ] 10-4
𝜇 Fluid viscosity [Pa s] 1.0
|𝑤| Applied compression [Pa] 1.0
𝐿 Column length [m] 10.0

Material properties and boundary conditions are specified in the Constitutive and FieldSpecifications sections.
For such set of parameters we have 𝑝0 = 1.0 Pa, 𝑐𝑐 = 1.111 m2 s-1 , and 𝑡𝑐 = 90 s. Therefore, as shown in the Events
section, we run this simulation for 90 seconds.

82 Chapter 1. Table of Contents

GEOS Documentation

Running GEOS
To run the case, use the following command:
path/to/geosx -i inputFiles/poromechanics/PoroElastic_Terzaghi_smoke.xml
Here, we see for instance the RSolid and RFluid at a representative timestep (residual values for solid and fluid
mechanics solvers, respectively)

Attempt: 0, NewtonIter: 0
( RSolid ) = (5.00e-01) ; ( Rsolid, Rfluid ) = ( 5.00e-01, 0.00e+00 )
( R ) = ( 5.00e-01 ) ;
Attempt: 0, NewtonIter: 1
( RSolid ) = (4.26e-16) ; ( Rsolid, Rfluid ) = ( 4.26e-16, 4.22e-17 )
( R ) = ( 4.28e-16 ) ;

As expected, since we are dealing with a linear problem, the fully implicit solver converges in a single iteration.

Inspecting results
This plot compares the analytical pressure solution (continuous lines) at selected times with the numerical solution
(markers).

1.0

t = 0.0 s
0.8 t = 20.0 s
t = 40.0 s
t = 60.0 s
0.6 t = 80.0 s
pressure [Pa]

0.4

0.2

0.0
0 2 4 6 8 10
x [m]

1.3. Basic Examples 83

GEOS Documentation

To go further
Feedback on this example
This concludes the poroelastic example. For any feedback on this example, please submit a GitHub issue on the project’s
GitHub page.
For more details
• More on poroelastic multiphysics solvers, please see Poromechanics Solver.
• More on numerical methods, please see Numerical Methods.
• More on functions, please see Functions.

1.3.5 Hydraulic Fracturing

Mesh with biased boundaries

The mesh block for this example uses a biased mesh along the simulation boundaries to reduce the size of the problem,
while maintaining the desired spatial extents. For a given element region with bias, the left-hand element will be x%
smaller and the right-hand element will be x% larger than the average element size. Along the x-axis of the mesh, we
select a value of zero for the first region to indicate that we want a uniform-sized mesh, and we select a bias of -0.6 for
the second region to indicate that we want the element size to smoothly increase in size as it moves in the +x direction.
The other dimensions of the mesh follow a similar pattern.

Defining a fracture nodeset

For this example, we want to propagate a single hydraulic fracture along the plane defined by y = 0. To achieve this,
we need to define three nodesets:
• source_a: The location where we want to inject fluid. Typically, we want this to be a single face in the x-z plane.
• perf_a: This is the initial fracture for the simulation. This nodeset needs to be at least two-faces wide in the x-z
plane (to represent the fracture at least one internal node needs to be open).
• fracturable_a: This is the set of faces where we will allow the fracture to grow. For a problem where we expect
the fracture to curve out of the plane defined by y = 0 , this could be replaced.

<Geometry>
<Box
(continues on next page)

1.3. Basic Examples 87

GEOS Documentation

(continued from previous page)

name="source_a"
xMin="{ -0.1, -0.1, -0.1 }"
xMax="{ 4.1, 0.1, 4.1 }"/>

Boundary conditions
The boundary conditions for this problem are defined in the case-specific and the base xml files. The case specific
block includes four instructions:
• frac: this marks the initial perforation.
• separableFace: this marks the set of faces that are allowed to break during the simulation.
• waterDensity: this initializes the fluid in the perforation.
• sourceTerm: this instructs the code to inject fluid into the source_a nodeset. Note the usage of the symbolic
expression and parameters in the scale. This boundary condition is also driven by a function, which we will
define later.

<FieldSpecification
name="waterDensity"
fieldName="water_density"
initialCondition="1"
(continues on next page)

88 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions"
scale="1000"
setNames="{ perf_a }"/>

<SourceFlux
name="sourceTerm"
objectPath="ElementRegions/Fracture"
scale="`-1000.0/$Nperf$`"
functionName="flow_rate"
setNames="{ source_a }"/>
</FieldSpecifications>

The base block includes instructions to set the initial in-situ properties and stresses. It is also used to specify the
external mechanical boundaries on the system. In this example, we are using roller-boundary conditions (zero normal-
displacement). Depending upon how close they are to the fracture, they can significantly affect its growth. Therefore,
it is important to test whether the size of the model is large enough to avoid this.

<FieldSpecification
name="sigma_yy"
initialCondition="1"
setNames="{ all }"
(continues on next page)

1.3. Basic Examples 89

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions"
fieldName="rock_stress"
component="1"
functionName="sigma_yy"
scale="1.0"/>

Coupled hydraulic fracturing solver

The Solvers block is located in the base xml file. Note that the gravityVector attribute indicates that we are applying
gravity in the z-direction in this problem.
Similar to other coupled physics solvers, the Hydrofracture solver is specified in three parts:
• Hydrofracture: this is the primary solver, which will be called by the event manager. Two of its key attributes
are the names of the dependent solid and fluid solvers.
• SolidMechanicsLagrangianSSLE: this is the solid mechanics solver.
• SinglePhaseFVM: this is the fluid solver.

90 Chapter 1. Table of Contents

GEOS Documentation

The final solver present in this example is the SurfaceGenerator, which manages how faces in the model break.

<SurfaceGenerator
name="SurfaceGen"
targetRegions="{ Domain }"
(continues on next page)

1.3. Basic Examples 91

GEOS Documentation

(continued from previous page)

rockToughness="$K_upscaled$"
nodeBasedSIF="1"
mpiCommOrder="1"/>
</Solvers>

Events
Rather than explicitly specify the desired timestep behavior, this example uses a flexible approach for timestepping.
The hydrofracture solver is applied in the solverApplications event, which request a maxEventDt = 30 s. To
maintain stability during the critical early phase of the model, we delay turning on the pump by pump_start. We then
use the pumpStart event to limit the further limit the timestep to pump_ramp_dt_limit as the fracture experiences
rapid development (pump_start to pump_start + pump_ramp). Note that while this event does not have a target,
it can still influence the time step behavior. After this period, the hydraulic fracture solver will attempt to increase /
decrease the requested timestep to maintain stability.
Other key events in this problem include:
• preFracture: this calls the surface generator at the beginning of the problem and helps to initialize the fracture.
• outputs_vtk and outputs_silo: these produces output vtk and silo files.
• restarts (inactive): this is a HaltEvent, which tracks the external clock. When the runtime exceeds the specified
value (here $t_allocation$=28 minutes), the code will call the target (which writes a restart file) and instruct the
code to exit.

<PeriodicEvent
(continues on next page)

92 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="pumpStart"
beginTime="$pump_start$"
endTime="`$pump_start$+$pump_ramp$`"
maxEventDt="$pump_ramp_dt_limit$"/>

</Events>

Functions to set in-situ properties

The function definitions are in the base xml file, and rely upon the files in the tables directory. The functions in this
example include the flow rate over time, the in-situ principal stress, and the bulk/shear moduli of the rock. Note the
use of the table_root parameter, which contains the root path to the table files.
The flow_rate TableFunction is an example of a 1D function. It has a single input, which is time. The table is defined
using a single coordinateFile:

0.00000e+00
6.00000e+01
1.20000e+02
3.72000e+03
3.78000e+03
1.00000e+09

And a single voxelFile:

0.00000e+00
0.00000e+00
5.00000e-02
5.00000e-02
0.00000e+00
0.00000e+00

Given the specified linear interpolation method, these values define a simple trapezoidal function. Note: since this is a
1D table, these values could alternately be given within the xml file using the coordinates and values attributes.
The sigma_xx TableFunction is an example of a 3D function. It uses elementCenter as its input, which is a vector. It
is specified using a set of three coordinate files (one for each axis), and a single voxel file. The geologic model in this
example is a layer-cake, which was randomly generated, so the size of the x and y axes are 1. The interpolation method
used here is upper, so the values in the table indicate those at the top of each layer.

(continues on next page)

1.3. Basic Examples 93

GEOS Documentation

(continued from previous page)

<TableFunction
name="sigma_xx"
inputVarNames="{ elementCenter }"
coordinateFiles="{ $table_root$/x.csv, $table_root$/y.csv, $table_root$/z.csv }"
voxelFile="$table_root$/sigma_xx.csv"
interpolation="upper"/>

</Functions>

94 Chapter 1. Table of Contents

GEOS Documentation

Running GEOS
Assuming that the preprocessing tools have been correctly installed (see Advanced XML Features ), there will be a
script in the GEOS build/bin directory called geosx_preprocessed. Replacing geosx with geosx_preprocessed in an
input command will automatically apply the preprocessor and send the results to GEOS.
Before beginning, we reccomend that you make a local copy of the example and its tables. Because we are using
advanced xml features in this example, the input file must be pre-processed before running. For example, this will run
the code on a debug partition using a total of 36 cores.

cp -r examples/hydraulicFracturing ./hf_example
cd hf_example
srun -n 36 -ppdebug geosx_preprocessed -i heterogeneousInSitu_benchmark.xml -x 6 -y 2 -z␣
˓→3 -o hf_results

Note that as part of the automatic preprocessing step a compiled xml file is written to the disk (by default ‘[in-
put_name].preprocessed’). When developing an xml with advanced features, we reccomend that you check this file
to ensure its accuracy.

Inspecting results
In the above example, we requested vtk- and silo-format output files every minute. We can therefore import these into
VisIt, Paraview, or python and visualize the outcome. The following figure shows the extents of the generated fracture
over time:

Notes for visualization tools:

1.3. Basic Examples 95

GEOS Documentation

1) In Visit, we currently recommend that you look at the silo-format files (due to a compatibility issue with vtk)
2) In Paraview, you may need to use the Multi-block Inspector (on the right-hand side of the screen by default) to
limit the visualization to the fracture. In addition, the Properties inspector (on the left-hand side of the sceen by
default) may not include some of the parameters present on the fracture. Instead, we recommend that you use
the property dropdown box at the top of the screen.
Because we did not explicitly specify any fracture barriers in this example, the fracture dimensions are controlled by
the in-situ stresses. During the first couple of minutes of growth, the fracture quickly reaches its maximum/minimum
height, which corresponds to a region of low in-situ minimum stress.
The following figures show the aperture and pressure of the hydraulic fracture (near the source) over time:

96 Chapter 1. Table of Contents

GEOS Documentation

Modifying Parameters Via the Command-Line

The advanced xml feature preprocessor allows parameters to be set or overriden by specifying any number of -p name
value arguments on the command-line. Note that if the parameter value has spaces, it needs to be enclosed by quotation
marks.
To illustrate this feature, we can re-run the previous analysis with viscosity increased from 1 cP to 5 cP:

srun -n 36 -ppdebug geosx_preprocessed -i heterogeneousInSitu_benchmark.xml -p mu 0.005 -

˓→x 6 -y 2 -z 3 -o hf_results_lower_mu

To go further
Feedback on this example
This concludes the hydraulic fracturing example. For any feedback on this example, please submit a GitHub issue on
the project’s GitHub page.
For more details
• More on advanced xml features, please see Advanced XML Features.
• More on functions, please see Functions.
• More on biased meshes, please see Mesh Bias.

1.3. Basic Examples 97

GEOS Documentation

1.3.6 Triaxial Driver: Extended Drucker-Prager Elasto-Plastic Model

Context
In this example, we use the TriaxialDriver inside GEOS to simulate rock mechanics experiments, such as triaxial
tests. The triaxial driver allows to calibrate properties and model parameters against experimental data before using
them in field-scale simulations.
Objectives
At the end of this example, you will know:
• how to set up a triaxial test scenario with the TriaxialDriver,
• how to define a material model,
• how to specify loading conditions with TableFunction,
• how to save and postprocess simulation results.
Input file
The XML file for this test case is located at:

inputFiles/triaxialDriver/triaxialDriver_ExtendedDruckerPrager_basicExample.xml

This example also uses a set of table files located at:

inputFiles/triaxialDriver/tables/

Last, a Python script for post-processing the results is provided:

src/docs/sphinx/basicExamples/triaxialDriver/triaxialDriverFigure.py

Description of the case

Instead of launching a full finite-element simulation to mimic experimental loading conditions, GEOS provides a
TriaxialDriver to investigate constitutive behaviors and simulate laboratory tests. The triaxial driver makes it easy
to interpret the mechanical response and calibrate the constitutive models against experimental data.
In this example, the Extended Drucker-Prager model (see Model: Extended Drucker-Prager) is used to solve elasto-
plastic deformations of rock samples when subject to controlled loading conditions. The strain-hardening Extended
Drucker-Prager model with an associated plastic flow rule is tested in this example. To replicate a typical triaxial test,
we use a table function to specify loading conditions in axial and radial directions. The resulting strains and stresses
in both directions are numerically calculated and saved into a simple ASCII output file.
For this example, we focus on the Task, the Constitutive, and the Functions tags.

Task
In GEOS, the TriaxialDriver is defined with a dedicated XML structure. The TriaxialDriver is added to a
standard XML input deck as a solo task to the Tasks queue and added as a SoloEvent to the event queue.
For this example, we simulate the elastoplastic deformation of a confined specimen caused by external load. A ho-
mogeneous domain with one solid material is assumed. The material is named ExtendedDruckerPrager, and its
mechanical properties are specified in the Constitutive section.
Different testing modes are available in the TriaxialDriver to mimic different laboratory loading conditions:

98 Chapter 1. Table of Contents

GEOS Documentation

mode axial loading radial loading initial stress

axial strain controlled with
strainControl radial strain controlled with isotropic stress using
axialControl radialControl initialStress
axial stress controlled with
stressControl radial stress controlled with isotropic stress using
axialControl radialControl initialStress
mixedControlaxial strain controlled with radial stress controlled with isotropic stress using
axialControl radialControl initialStress

A triaxial test is usually conducted on a confined rock sample to determine material properties. As shown, a conven-
tional triaxial test is described using the mode="mixedControl" testing mode in the TriaxialDriver.
In a triaxial test, the testing sample is under confining pressure (radial stresses) and subject to increased axial load.
Therefore, a stress control radialControl="stressFunction" is defined in the radial direction to impose confining
pressure. A strain control axialControl="strainFunction" is applied in the axial direction to represent axial
compression.
The initial stress is specified by initialStress="-10.e6". To ensure static equilibrium at the first timestep, its value
should be consistent with the initial set of applied stresses defined in axial or radial loading functions. This stress has
a negative value due to the negative sign convention for compressive stress in GEOS.
Then, steps="200" defines the number of load steps and output="simulationResults.txt" specifies an output
file to which the simulation results will be written.

In addition to triaxial tests, volumetric and oedometer tests can be simulated by changing the strainControl mode,
and by defining loading controls in axial and radial direction accordingly. A volumetric test can be modelled by setting
the axial and radial control functions to the same strain function, whereas an oedometer test runs by setting the radial
strain to zero (see Triaxial Driver).

Constitutive laws
Any solid material model implemented in GEOS can be called by the TriaxialDriver.
For this problem, Extended Drucker Prager model ExtendedDruckerPrager is used to describe the mechan-
ical behavior of an isotropic material, when subject to external loading. As for the material parameters,
defaultInitialFrictionAngle, defaultResidualFrictionAngle and defaultCohesion denote the ini-
tial friction angle, the residual friction angle, and cohesion, respectively, as defined by the Mohr-Coulomb
failure envelope. As the residual friction angle defaultResidualFrictionAngle is larger than the initial
one defaultInitialFrictionAngle, a strain hardening model is adopted, whose hardening rate is given as
defaultHardening="0.0001". If the residual friction angle is set to be less than the initial one, strain weakening
will take place. Setting defaultDilationRatio="1.0" corresponds to an associated flow rule.

1.3. Basic Examples 99

GEOS Documentation

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Functions
The TriaxialDriver uses a simple form of time-stepping to advance through the loading steps, allowing for simu-
lating both rate-dependent and rate-independent models.
In this case, users should define two different time history functions (strainFunction and stressFunction) to
describe loading conditions in axial and radial direction respectively. More specifically, the table functions in this
example include the temporal variations of radial stress and axial strain, which rely upon the external files in the table
directory (see Functions). Note that for standard tests with simple loading history, functions can be embedded directly
in the XML file without using external tables.

The strainFunction TableFunction is an example of a 1D interpolated function, which describes the strain as a
function of time inputVarNames="{ time }". This table is defined using a single coordinate file:

0
1
2
3
4
5

And a single voxel file:

100 Chapter 1. Table of Contents

GEOS Documentation

0.0
-0.004
-0.002
-0.005
-0.003
-0.006

Similarly, the correlation between the confining stress and time is given through the stressFunction defined using
the same coordinate file:

0
1
2
3
4
5

And a different voxel file:

-10.0e6
-10.0e6
-10.0e6
-10.0e6
-10.0e6
-10.0e6

For this specific test, the confining stress is kept constant and equal to the initialStress. Instead of monotonic
changing the axial load, two loading/unloading cycles are specified in the strainFunction. This way, both plastic
loading and elastic unloading can be modeled.
Note that by convention in GEOS, stressFunction and strainFunction have negative values for a compressive
test.

Mesh
Even if discretization is not required for the TriaxialDriver, a dummy mesh should be defined to pass all the nec-
essary checks when initializing GEOS and running the module. A dummy mesh should be created in the Mesh section
and assigned to the cellBlocks in the ElementRegions section.

<ElementRegions>
<CellElementRegion
(continues on next page)

1.3. Basic Examples 101

GEOS Documentation

(continued from previous page)

where 𝜇𝑔 and 𝜇𝑤 represent the viscosity of gas and water phase respectively, assumed to be constant in this study.

1.4. Advanced Examples 105

GEOS Documentation

𝑑𝑓𝑔
The position of a particular saturation is given as a function of the injection time 𝑡 and the value of the derivative 𝑑𝑆𝑔
at that saturation:
(︂ )︂
𝑄𝑇 𝑡 𝑑𝑓𝑔
𝑥𝑆𝑔 =
𝐴𝜑 𝑑𝑆𝑔

where 𝑄𝑇 is the total flow rate, 𝐴 is the area of the cross-section in the core sample, 𝜑 is the rock porosity. In addition,
the abrupt saturation front is determined based on the tangent point on the fractional flow curve.
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The mesh was created with the internal mesh generator and parametrized in the InternalMesh XML tag. It contains
1000x1x1 eight-node brick elements in the x, y, and z directions respectively. Such eight-node hexahedral elements are
defined as C3D8 elementTypes, and their collection forms a mesh with one group of cell blocks named here cellBlock.
The width of the domain should be large enough to ensure the formation of a one-dimension flow.

Flow solver

The isothermal immiscible simulation is performed using the GEOS general-purpose multiphase flow solver. The
multiphase flow solver, a solver of type CompositionalMultiphaseFVM called here compflow (more information on
these solvers at Compositional Multiphase Flow Solver) is defined in the XML block CompositionalMultiphaseFVM:

<Solvers>
<CompositionalMultiphaseFVM
name="compflow"
logLevel="1"
discretization="fluidTPFA"
temperature="300"
initialDt="0.001"
useMass="1"
targetRegions="{ region }">
<NonlinearSolverParameters
newtonTol="1.0e-6"
newtonMaxIter="50"
maxTimeStepCuts="2"
lineSearchMaxCuts="2"/>
<LinearSolverParameters
solverType="direct"
directParallel="0"
(continues on next page)

106 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

logLevel="0"/>
</CompositionalMultiphaseFVM>
</Solvers>

We use the targetRegions attribute to define the regions where the flow solver is applied. Here, we only simu-
late fluid flow in one region named as region. We specify the discretization method (fluidTPFA, defined in the
NumericalMethods section), and the initial reservoir temperature (temperature="300").

Constitutive laws

This benchmark example involves an immiscible, incompressible, two-phase model, whose fluid rheology and perme-
ability are specified in the Constitutive section. The best approach to represent this fluid behavior in GEOS is to
use the DeadOilFluid model in GEOS.

Constant fluid densities and viscosities are given in the external tables for both phases. The formation volume factors are
set to 1 for incompressible fluids. The relative permeability for both phases are modeled with the power-law correlations
BrooksCoreyRelativePermeability (more information at Brooks-Corey relative permeability model), as shown
below. Capillary pressure is assumed to be negligible.

1.4. Advanced Examples 107

Symbol Parameter Unit Value

𝑘𝑟𝑔0
Max Relative Permeability of Gas [-] 1.0
𝑘𝑟𝑤 0 Max Relative Permeability of Water [-] 1.0
𝑛𝑔 Corey Exponent of Gas [-] 3.5
𝑛𝑤 Corey Exponent of Water [-] 3.5
𝑆𝑔𝑟 Residual Gas Saturation [-] 0.0
𝑆𝑤𝑟 Residual Water Saturation [-] 0.0
𝜑 Porosity [-] 0.2
𝜅 Matrix Permeability [m2 ] 9.0*10-13
𝜇𝑔 Gas Viscosity [Pa s] 2.3*10-5
𝜇𝑤 Water Viscosity [Pa s] 5.5*10-4
𝑄𝑇 Total Flow Rate [m3 /s] 2.5*10-7
𝐷𝐿 Domain Length [m] 0.1
𝐷𝑊 Domain Width [m] 1.0
𝐷𝑇 Domain Thickness [m] 0.002

Inspecting results

We request VTK-format output files and use Paraview to visualize the results. The following figure shows the distribu-
tion of phase saturations and pore pressures in the computational domain at 𝑡 = 70𝑠.
Two following dimensionless terms are defined when comparing the numerical solution with the analytical solutions:

𝑄𝑇 𝑡
𝑡⋆ =
𝐴𝐷𝐿 𝜑
𝑥𝑆𝑔
𝑥𝑑 =
𝐷𝐿

110 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.4: Simulation results of phase saturations and pore pressure

1.4. Advanced Examples 111

GEOS Documentation

The figure below compares the results from GEOS (dashed curves) and the corresponding analytical solution (solid
curves) for the change of gas saturation (𝑆𝑔 ) and water saturation (𝑆𝑤 ) along the flow direction.
GEOS reliably captures the immiscible transport of two phase flow (CO2 and water). GEOS matches the analytical
solutions in the formation and the progress of abrupt fronts in the saturation profiles.

1.0 Analytical_t*=0.062
1.0
Numerical_t*=0.062
Analytical_t*=0.123
Numerical_t*=0.123
0.8 Analytical_t*=0.185
Numerical_t*=0.185 0.8
Analytical_t*=0.247
Numerical_t*=0.247
Analytical_t*=0.308
0.6 Numerical_t*=0.308
Analytical_t*=0.37 0.6
Numerical_t*=0.37 Analytical_t*=0.062
Numerical_t*=0.062

Sw
Analytical_t*=0.432
Sg

Numerical_t*=0.432 Analytical_t*=0.123
0.4 0.4 Numerical_t*=0.123
Analytical_t*=0.185
Numerical_t*=0.185
Analytical_t*=0.247
Numerical_t*=0.247
Analytical_t*=0.308
0.2 0.2 Numerical_t*=0.308
Analytical_t*=0.37
Numerical_t*=0.37
Analytical_t*=0.432
Numerical_t*=0.432
0.00.0 0.2 0.4 0.6 0.8 1.0 0.00.0 0.2 0.4 0.6 0.8 1.0
xd xd

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

CO2 Plume Evolution and Leakage Through an Abandoned Well

Context
We consider a benchmark problem used in (Class et al., 2009) to compare a number of numerical models applied to
CO2 storage in geological formations. Using a simplified isothermal and immiscible two-phase setup, this test case
addresses the simulation of the advective spreading of CO2 injected into an aquifer and the leakage of CO2 from the
aquifer through an abandoned, leaky well.
Our goal is to review the different sections of the XML file reproducing the benchmark configuration and to demonstrate
that the GEOS results (i.e., arrival time of the CO2 plume at the leaky well and leakage rate through the abandoned
well) are in agreement with the reference results published in (Class et al., 2009).
The GEOS results obtained for the non-isothermal version of this test case (referred to as Problem 1.2 in (Class et al.,
2009)) are presented in a separate documentation page.
Input file
This benchmark test is based on the XML file located below:

inputFiles/compositionalMultiphaseFlow/benchmarks/isothermalLeakyWell/
˓→isothermalLeakyWell_benchmark.xml

112 Chapter 1. Table of Contents

GEOS Documentation

Problem description

The following text is adapted from the detailed description of the benchmark test case presented in (Ebigbo, Class,
Helmig, 2007) and (Class et al., 2009).
The leakage scenario considered here involves one CO2 injection well, one leaky well, two aquifers and an aquitard.
The setup is illustrated in the figure below. The leaky well connects the two aquifers. CO2 is injected into in the lower
aquifer, comes in contact with the leaky well and rises to the higher aquifer. The advective flow (including the buoyancy
effects) of CO2 in the initially brine-saturated aquifers and through the leaky well is the most important process in this
problem.
The model domain is located 2840 to 3000 m below the surface and has the following dimensions: 1000 x 1000 x 160
m. The distance between the injection and the leaky well is 100 m, and the injection rate of CO2 into the lower aquifer
is constant (equal to 8.87 kg/s). The wells are described as cylinders with a 0.15 m radius and are treated as a porous
medium with a higher permeability than the aquifers (i.e., this problem does not require a well model).

Fig. 1.5: Leakage scenario (image taken from (Ebigbo, Class, Helmig, 2007)).

The authors have used the following simplifying assumptions:

• The formation is isotropic.
• All processes are isothermal.
• CO2 and brine are two separate and immiscible phases. Mutual dissolution is neglected.
• Fluid properties such as density and viscosity are constant.
• The pressure conditions at the lateral boundaries are constant over time, and equal to the initial hydrostatic
condition.
• Relative permeabilities are linear functions of saturation.
• Capillary pressure is negligible.

1.4. Advanced Examples 113

GEOS Documentation

Mesh and element regions

The structured mesh is generated using the internal mesh generator as parameterized in the InternalMesh block of the
XML file. The mesh contains 112 x 101 x 60 hexahedral elements (C3D8 element type) in the x, y, and z directions
respectively.
The attributes nx, ny, nz, and cellBlockNames are used to define 5 x 3 x 3 = 45 cell blocks. Note that the cell block
names listed in cellBlockNames are mapped to their corresponding cell block using an k-j-i logic in which the k index
is the fastest index, and the i index is the slowest index.

<Mesh>
<InternalMesh
name="mesh"
elementTypes="{ C3D8 }"
xCoords="{ -500, -0.1329, 0.1329, 99.8671, 100.1329, 500 }"
yCoords="{ -500, -0.1329, 0.1329, 500 }"
zCoords="{ -3000, -2970, -2870, -2840 }"
nx="{ 50, 1, 20, 1, 40 }"
ny="{ 50, 1, 50 }"
nz="{ 20, 30, 10 }"
cellBlockNames="{ aquiferBottom00, aquiferBottom10, aquiferBottom20,␣
˓→aquiferBottom30, aquiferBottom40,

aquiferBottom01, aquiferBottom11, aquiferBottom21,␣

˓→aquiferBottom31, aquiferBottom41,

aquiferBottom02, aquiferBottom12, aquiferBottom22,␣

˓→aquiferBottom32, aquiferBottom42,

aquitard00, aquitard10, aquitard20, ␣

˓→aquitard30, aquitard40,
aquitard01, aquitard11, aquitard21, ␣
˓→aquitard31, aquitard41,
aquitard02, aquitard12, aquitard22, ␣
˓→aquitard32, aquitard42,
aquiferTop00, aquiferTop10, aquiferTop20, ␣
˓→aquiferTop30, aquiferTop40,
aquiferTop01, aquiferTop11, aquiferTop21, ␣
˓→aquiferTop31, aquiferTop41,
aquiferTop02, aquiferTop12, aquiferTop22, ␣
˓→aquiferTop32, aquiferTop42 }"/>
</Mesh>

ò Note

In the GEOS input file, the two wells are defined as columns of hexahedral elements of individual size 0.2658 x
0.2658 x 1 m. The coefficient 0.2858 is chosen to ensure that the cross-section of the wells is equal to the one
defined in the benchmark, in which wells are defined as cylinders with a radius of 0.15 m.

The cell block names are used in the ElementRegions block to define element regions in the aquifers and in the wells.
In the benchmark definition, the wells are treated as a porous medium with a higher permeability and therefore the
rock models are not the same in the aquifers (rock) and in the wells (rockWell). These names are defined in the
Constitutive block.

<ElementRegions>
<CellElementRegion
(continues on next page)

114 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="aquiferBottom"
cellBlocks="{ aquiferBottom00, aquiferBottom10, aquiferBottom20, aquiferBottom30,␣
˓→aquiferBottom40,

aquiferBottom01, aquiferBottom21, ␣
˓→aquiferBottom41,

aquiferBottom02, aquiferBottom12, aquiferBottom22, aquiferBottom32,␣

˓→aquiferBottom42 }"

materialList="{ fluid, rock, relperm }"/>

<CellElementRegion
name="aquiferTop"
cellBlocks="{ aquiferTop00, aquiferTop10, aquiferTop20, aquiferTop30, aquiferTop40,
aquiferTop01, aquiferTop21, aquiferTop41,
aquiferTop02, aquiferTop12, aquiferTop22, aquiferTop32, aquiferTop42␣
˓→}"

materialList="{ fluid, rock, relperm }"/>

Defining these element regions allows the flow solver to be applied only to the top and bottom aquifers (and wells),
since we follow the approach of (Class et al., 2009) and do not simulate flow in the aquitard, as we will see in the next
section.

ò Note

Since the two aquifer regions share the same material properties, they could have been defined as a single
CellElementRegion for a more concise XML file producing the same results. The same is true for the two
well regions.

Flow solver

The isothermal immiscible simulation is performed by the GEOS general-purpose multiphase flow solver based on a
TPFA discretization defined in the XML block CompositionalMultiphaseFVM:

118 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.6: CO2 saturation after 200 days

Fig. 1.7: Pressure after 200 days

1.4. Advanced Examples 119

GEOS Documentation

Code Arrival time [day]

GEOSX 9.6
COORES 8
DuMux 6
ECLIPSE 8
FEHM 4
IPARS-CO2 10
MUFTE 8
RockFlow 19
ELSA 14
TOUGH2/ECO2N 4
TOUGH2/ECO2N (2) 10
TOUGH2 (3) 9
VESA 7

ò Note

The time-stepping strategy used by the codes considered in (Class et al., 2009), as well as the meshes that have
been used, are not documented in the benchmark description. Therefore, even on this simple test case, we cannot
expect to obtain an exact match with the published results.

Next, we measure the CO2 leakage rate through the leaky well, defined by the authors as the CO2 mass flow at midway
between top and bottom aquifers divided by the injection rate (8.87 kg/s), in percent. The GEOS leakage rate is shown
in the figure below:
The leakage rates computed by the codes considered in (Class et al., 2009) are shown in the figure below.
The comparison between the previous two figures shows that GEOS can successfully reproduce the trend in leakage
rate observed in the published benchmark results. To further validate the GEOS results, we reproduce below Table 8
of (Class et al., 2009) to compare the maximum leakage rate, the time at which this maximum leakage rate is attained,
and the leakage rate at 1000 days.

Code Max leakage [%] Time at max leakage [day] Leakage at 1000 days [%]
GEOSX 0.219 50.6 0.1172
COORES 0.219 50 0.146
DuMux 0.220 61 0.128
ECLIPSE 0.225 48 0.118
FEHM 0.216 53 0.119
IPARS-CO2 0.242 80 0.120
MUFTE 0.222 58 0.126
RockFlow 0.220 74 0.132
ELSA 0.231 63 0.109
TOUGH2/ECO2N 0.226 93 0.110
TOUGH2/ECO2N (2) 0.212 46 0.115
TOUGH2 (3) 0.227 89 0.112
VESA 0.227 41 0.120

This table confirms the agreement between GEOS and the results of (Class et al., 2009). A particularly good match is
obtained with Eclipse, FEHM, and TOUGH2/ECO2N (2).

120 Chapter 1. Table of Contents

GEOS Documentation

0.25
ECLIPSE
TOUGH2
GEOSX
0.20
Leakage value [%]

0.15

0.10

0.05

0.00
0 200 400 600 800 1000
Time [days]

1.4. Advanced Examples 121

GEOS Documentation

Fig. 1.8: Leakage rates [%] obtained with the simulators considered in (Class et al., 2009).

122 Chapter 1. Table of Contents

GEOS Documentation

To go further

The more complex, non-isothermal version of this test is in Non-isothermal CO2 Plume Evolution and Leakage Through
an Abandoned Well.
Feedback on this example
For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Non-isothermal CO2 Plume Evolution and Leakage Through an Abandoned Well

Context
This validation case is a more complex version of the benchmark problem presented in CO2 Plume Evolution and
Leakage Through an Abandoned Well. While the latter is based on simple isothermal and immiscible fluid properties,
the present validation case relies on a more realistic fluid behavior accounting for thermal effects and mass exchange
between phases. This non-isothermal benchmark test has been used in (Class et al., 2009) to compare different imple-
mentations of CO2-brine fluid properties in the context of CO2 injection and storage in saline aquifers.
Our goal is to review the sections of the XML file that are used to parameterize the CO2-brine fluid behavior, and to
demonstrate that GEOS produces similar results as those presented in (Class et al., 2009).
Input file
This benchmark test is based on the XML file located below:

inputFiles/compositionalMultiphaseFlow/benchmarks/thermalLeakyWell/thermalLeakyWell_
˓→benchmark.xml

Problem description

Some of the text below is adapted from (Ebigbo, Class, Helmig, 2007).
The benchmark scenario remains the same as in CO2 Plume Evolution and Leakage Through an Abandoned Well. CO2
is injected into an aquifer, spreads within the aquifer, and, upon reaching a leaky well, rises up to a shallower aquifer.
The model domain still has the dimensions: 1000 x 1000 x 160 m, but it is now assumed to be shallower, between 640
m and 800 m of depth.
The figure below shows the pressure and temperature in the formation at the mentioned depths (assuming a geothermal
gradient of 0.03 K/m). The conditions in the aquifer at the considered depths range from supercritical to liquid to
gaseous. The figure also shows the CO2 density at the conditions of the formation. There is a large change in density at
a certain depth. This depth corresponds to the point where the line depicting the formation conditions crosses the CO2
saturation vapor curve, that is, the boundary between liquid and gaseous CO2. Other fluid properties such as viscosity
also change abruptly at that depth.
Therefore, as explained later, we use a more sophisticated fluid model in which the CO2 and brine fluid properties are
now a function of the aquifer conditions, such as pressure, temperature, and salinity. Specifically:
• The CO2 component is present in the CO2-rich phase but can also dissolve in the brine phase. The amount of
dissolved CO2 depends on pressure, temperature, and salinity. For now, in GEOS, the water component cannot
be present in the CO2-rich phase.
• Densities and viscosities depend nonlinearly on pressure, temperature, and salinity.
• The hydrostatic initial condition accounts for the geothermal gradient of 0.03 K/m specified in the benchmark
description.
We plan to use two types of physical models in this benchmark:
• A model simulating flow and mass transfer, but not heat transfer (i.e., no energy balance is used). The geothermal
gradient is constant in time, and is taken into account in the calculation of temperature-dependent properties.

1.4. Advanced Examples 123

GEOS Documentation

Fig. 1.9: Aquifer conditions (image taken from (Ebigbo, Class, Helmig, 2007)).

• A fully thermal model simulating flow as well as mass and heat transfer. The results obtained with this more
complex model are not available yet and will be added to this page later.

Mesh and element regions

As illustrated by the ECLIPSE results in (Class et al., 2009), the leakage rate exhibits a high dependence on the degree
of spatial refinement (particularly between the two wells in our observations). Therefore, we consider two meshes in
this test case:
• A “coarse” mesh with 206070 cells, whose spatial resolution is similar to that used by most codes based on the
information provided by Table 13 of (Class et al., 2009).
• A “fine” mesh with 339390 cells, whose spatial resolution is finer between the two wells.
These structured meshes are defined as in CO2 Plume Evolution and Leakage Through an Abandoned Well, as shown
next for the “fine” mesh.

<Mesh>
<InternalMesh
name="mesh"
elementTypes="{ C3D8 }"
xCoords="{ -500, -0.1329, 0.1329, 99.8671, 100.1329, 500 }"
yCoords="{ -500, -0.1329, 0.1329, 500 }"
zCoords="{ -800, -770, -670, -640 }"
nx="{ 50, 1, 20, 1, 40 }"
ny="{ 50, 1, 50 }"
nz="{ 20, 30, 10 }"
cellBlockNames="{ aquiferBottom00, aquiferBottom10, aquiferBottom20,␣
˓→aquiferBottom30, aquiferBottom40,

aquiferBottom01, aquiferBottom11, aquiferBottom21,␣

˓→aquiferBottom31, aquiferBottom41,

aquiferBottom02, aquiferBottom12, aquiferBottom22,␣

˓→aquiferBottom32, aquiferBottom42,

aquitard00, aquitard10, aquitard20, ␣

˓→aquitard30, aquitard40,
aquitard01, aquitard11, aquitard21, ␣
˓→aquitard31, aquitard41,
(continues on next page)

124 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

aquitard02, aquitard12, aquitard22, ␣
˓→aquitard32, aquitard42,
aquiferTop00, aquiferTop10, aquiferTop20, ␣
˓→aquiferTop30, aquiferTop40,
aquiferTop01, aquiferTop11, aquiferTop21, ␣
˓→aquiferTop31, aquiferTop41,
aquiferTop02, aquiferTop12, ␣
˓→aquiferTop22, aquiferTop32, aquiferTop42 }"/>
</Mesh>

As in the previous benchmark, we define four element regions whose material list now includes the name of the cap-
illary pressure constitutive model (cappres). We refer the reader to CO2 Plume Evolution and Leakage Through an
Abandoned Well for an example of this procedure.

Flow solver

Although the fluid behavior is significantly different from that of the previous benchmark, we still use the GEOS
general-purpose multiphase flow solver defined in the XML block CompositionalMultiphaseFVM:

ò Note

The attribute temperature listed above is mandatory, but are overridden by GEOS to impose a non-uniform
geothermal gradient along the z-axis, as we will see later.

1.4. Advanced Examples 125

GEOS Documentation

Constitutive models

The Brooks-Corey relative permeabilities and capillary pressure are described using tables constructed from the pa-
rameters values provided in the benchmark description, with a wetting-phase saturation range between 0.2 and 0.95,
an entry pressure of 10000 Pa, and a Brooks-Corey parameter of 2. We refer the reader to the files used in the Table-
Function listed below for the exact values that we have used:

The two-phase, two-component CO2-brine model implemented in GEOS is parameterized in the CO2BrinePhillips
XML block:

The components of this fluid model are described in detail in the CO2-brine model and are briefly summarized below.
They are parameterized using three parameter files that must be written carefully to obtain the desired behavior, as
explained next.

CO2 density and viscosity

These properties are obtained using the models proposed by Span and Wagner (1996) and Fenghour and Wakeham
(1998) for density and viscosity, respectively. The density and viscosity values are internally tabulated by GEOS at the
beginning of the simulation by solving the Helmholtz energy equation for each pair (𝑝, 𝑇 ).
The tables size and spacing are specified in the file pvtgas.txt. Here, for both quantities, the values are tabulated between
6.6e6 Pa and 4e7 Pa, with a pressure spacing of 1e6 Pa, and between 302 K and 312 K, with a temperature increment
of 5 K. These values have been chosen using the initial condition and an upper bound on the expected pressure increase
during the simulation.

DensityFun SpanWagnerCO2Density 6.6e6 4e7 1e6 302.0 312.0 5

ViscosityFun FenghourCO2Viscosity 6.6e6 4e7 1e6 302.0 312.0 5

ò Note

If pressure or temperature go outside the values specified in this parameter file, constant extrapolation is used to
obtain the density and viscosity values. Note that for now, no warning is issued by GEOS when this happens. We
plan to add a warning message to document this behavior in the near future.

126 Chapter 1. Table of Contents

GEOS Documentation

Brine density and viscosity

These properties depend on pressure, temperature, composition, and salinity via the models proposed by Phillips et
al. (1981). The brine density is modified to account for the presence of dissolved CO2 using the method proposed by
Garcia (2001). The values of (pure) brine density are also tabulated at a function of pressure and temperature, and we
use the same range as for the CO2 properties to construct this table:

DensityFun PhillipsBrineDensity 6.6e6 4e7 1e6 302.0 312.0 5 1.901285269

ViscosityFun PhillipsBrineViscosity 1.901285269

Importantly, the last value on each line in the file pvtliquid.txt defines the salinity in the domain. In our model, salinity
is constant in space and in time (i.e., unlike water and CO2, it is not tracked as a component in GEOS). In our model,
salinity is specified as a molal concentration in mole of NaCl per kg of solvent (brine). The value used here (1000 x 10
/ ( 58.44 x ( 100 - 10 ) ) = 1.901285269 moles/kg) is chosen to match the value specified in the benchmark (weight%
of 10%).

CO2 solubility in brine

As explained in CO2-brine model, we use the highly nonlinear model proposed by Duan and Sun (2004) to compute
the CO2 solubility as a function of pressure, temperature, composition, and salinity. In co2flash.txt, we use the same
parameters as above to construct the pressure-temperature tables of precomputed CO2 solubility in brine.

FlashModel CO2Solubility 6.6e6 4e7 1e6 302.0 312.0 5 1.901285269

Initial and boundary conditions

The domain is initially saturated with brine with a hydrostatic pressure field and a geothermal gradient of 0.03 K/m.
This is specified using the HydrostaticEquilibrium XML tag in the FieldSpecifications block:

Although this is the same block as in CO2 Plume Evolution and Leakage Through an Abandoned Well, GEOS is now
enforcing the geothermal gradient specified in the TableFunction named initTempTable, and is also accounting for
the nonlinear temperature dependence of brine density to equilibrate the pressure field.
We use the simple table-based approach shown below to impose the Dirichlet boundary conditions on the four sides of
the domain.

1.4. Advanced Examples 127

GEOS Documentation

(continued from previous page)

<FieldSpecification
(continues on next page)

128 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="bcPressureLeakyWell"
objectPath="ElementRegions/leakyWell"
setNames="{ east, west, south, north }"
fieldName="pressure"
functionName="pressureFunction"
scale="1"/>
<FieldSpecification
name="bcTemperatureLeakyWell"
objectPath="ElementRegions/leakyWell"
setNames="{ east, west, south, north }"
fieldName="temperature"
functionName="initTempTable"
scale="1"/>
<FieldSpecification
name="bcCompositionCO2LeakyWell"
setNames="{ east, west, south, north }"
objectPath="ElementRegions/leakyWell"
fieldName="globalCompFraction"
component="0"
scale="0.000001"/>
<FieldSpecification
name="bcCompositionWaterLeakyWell"
setNames="{ east, west, south, north }"
objectPath="ElementRegions/leakyWell"
fieldName="globalCompFraction"
component="1"
scale="0.999999"/>

<FieldSpecification
name="bcPressureInjectionWell"
objectPath="ElementRegions/injectionWell"
setNames="{ east, west, south, north }"
fieldName="pressure"
functionName="pressureFunction"
scale="1"/>
<FieldSpecification
name="bcTemperatureInjectionWell"
objectPath="ElementRegions/injectionWell"
setNames="{ east, west, south, north }"
fieldName="temperature"
functionName="initTempTable"
scale="1"/>
<FieldSpecification
name="bcCompositionCO2InjectionWell"
setNames="{ east, west, south, north }"
objectPath="ElementRegions/injectionWell"
fieldName="globalCompFraction"
component="0"
scale="0.000001"/>
<FieldSpecification
name="bcCompositionWaterInjectionWell"
setNames="{ east, west, south, north }"
(continues on next page)

1.4. Advanced Examples 129

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions/injectionWell"
fieldName="globalCompFraction"
component="1"
scale="0.999999"/>

where the setNames = "{ east, west, south, north }" are defined using the Box XML tags of the Geometry
section, and where the tables are defined as TableFunction in the Functions section.

ò Note

Due to the nonlinear dependence of brine density on temperature, this block does not exactly impose a Dirichlet
pressure equal to the initial condition. Instead, here, we impose a linear pressure gradient along the z-axis, whose
minimum and maximum values are the same as in the initial state. We could have imposed Dirichlet boundary
conditions preserving the initial condition using as many points in zlin.geos as there are cells along the z-axis
(instead of just two points).

The SourceFlux is the same as in the previous benchmark case (see CO2 Plume Evolution and Leakage Through an
Abandoned Well).

Inspecting results

We request VTK-format output files and use Paraview to visualize the results. The following figures show the distribu-
tion of CO2 saturation and pressure along the slice defined by x = 0 at t = 1,000 days.

Fig. 1.10: CO2 saturation after 1,000 days

To validate the GEOS results, we consider the metrics used in (Class et al., 2009) as previously done in CO2 Plume
Evolution and Leakage Through an Abandoned Well.
First, we consider the arrival time of the CO2 plume at the leaky well. As in (Class et al., 2009), we use the leakage rate
threshold of 0.005% to detect the arrival time. In our numerical tests, the arrival time is highly dependent on the degree
of spatial refinement in the vicinity of the wells and on the time step size, but these parameters are not documented in
(Class et al., 2009). The next table reports the GEOS arrival time at the leaky well and compares it with the values
published in (Class et al., 2009).

130 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.11: Pressure after 1,000 days

Code Arrival time [day]

GEOSX COARSE 36.8
GEOSX FINE 46.7
COORES 31
ECLIPSE HW 42
ECLIPSE SCHLUMBERGER COARSE 24
ECLIPSE SCHLUMBERGER FINE 34
RockFlow 30
TOUGH2 46

ò Note

In the table above, we only included the values obtained with the codes that do not solve an energy balance equation.
The values obtained with the fully thermal codes (FEHM, MUFTE, and RTAFF2) are omitted for now.

Next, we measure the CO2 leakage rate through the leaky well, defined by the authors as the CO2 mass flow at midway
between top and bottom aquifers divided by the injection rate (8.87 kg/s), in percent. The GEOS leakage rate is shown
in the figure below:
We see that GEOS produces a reasonable match with the numerical codes considered in the study. Although it is not
possible to exactly match the published results (due to the lack of information on the problem, such as mesh refinement
and time step size), GEOS reproduces well the trend exhibited by the other codes.
For reference, we include below the original figure from (Class et al., 2009) containing all the results, including those
obtained with the codes solving an energy equation.
To further validate the GEOS results, we reproduce below Table 9 of (Class et al., 2009) (only considering codes that
do not solve an energy equation) to compare the maximum leakage rate, the time at which this maximum leakage rate is
attained, and the leakage rate at 2000 days. We observe that the GEOS values are in the same range as those considered
in the benchmark.

1.4. Advanced Examples 131

GEOS Documentation

0.14

0.12

0.10
Leakage value [%]

0.08

0.06
ROCKFLOW
ECLIPSE (FINE)
0.04 ECLIPSE (COARSE)
COORES
0.02 TOUGH2
GEOSX (FINE)
GEOSX (COARSE)
0.00
0 250 500 750 1000 1250 1500 1750 2000
Time [days]

132 Chapter 1. Table of Contents

The authors have used the following simplifying assumptions:

• The formation is isotropic.
• The temperature is constant in time.
• The pressure conditions at the lateral boundaries are constant over time, and equal to the initial hydrostatic
condition.

Mesh and element regions

The proposed conforming discretization is fully hexahedral. A VTK filter PointToCell is used to map properties from
vertices to cells, which by default builds a uniform average of values over the cell. The structured mesh is generated
using some helpers python scripts from the formatted Point/Cells list provided. It is then imported using meshImport

The central wellbore is discretized internally by GEOS (see CO 2 Injection). It includes five segments with a perfo-

1.4. Advanced Examples 135

GEOS Documentation

ration in each segment. It has its own region wellRegion and control labeled wellControls defined and detailed
respectively in ElementRegions and Solvers (see below). In the ElementRegions block,

one single reservoir region labeled reservoir. A second region wellRegion is associated with the well. All those
regions define materials to be specified inside the Constitutive block.

Coupled solver

The simulation is performed by the GEOS coupled solver for multiphase flow and well defined in the XML block
CompositionalMultiphaseReservoir:

It references the two coupled solvers under the tags flowSolverName and wellSolverName. These are defined inside
the same Solvers block following this coupled solver. It also defined non-linear, NonlinearSolverParameters and and
linear, LinearSolverParameters, strategies.
The next two blocks are used to define our two coupled physics solvers compositionalMultiphaseFlow (of type
CompositionalMultiphaseFVM) and compositionalMultiphaseWell (of type CompositionalMultiphaseWell).

Flow solver

We use the targetRegions attribute to define the regions where the flow solver is applied.

<CompositionalMultiphaseReservoir
name="coupledFlowAndWells"
flowSolverName="compositionalMultiphaseFlow"
wellSolverName="compositionalMultiphaseWell"
logLevel="1"
initialDt="1e2"
targetRegions="{ reservoir, wellRegion }">
<NonlinearSolverParameters
newtonTol="1.0e-5"
newtonMaxIter="40"/>
<LinearSolverParameters
solverType="fgmres"
(continues on next page)

136 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

preconditionerType="mgr"
krylovTol="1e-6"
logLevel="1"/>
</CompositionalMultiphaseReservoir>

The FV scheme discretization used is TPFA (which definition can be found nested in NumericalMeth-
ods/FiniteVolume) and some parameter values.

Well solver

The well solver is applied on its own region wellRegion which consists of the five discretized segments. It is also
the place where the WellControls are set thanks to type, control, injectionStream , injectionTemperature,
targetTotalRateTableName and, targetBHP for instance if we consider an injection well.
For more details on the wellbore modeling please refer to Compositional Multiphase Well Solver.
<CompositionalMultiphaseWell
name="compositionalMultiphaseWell"
targetRegions="{ wellRegion }"
logLevel="1"
useMass="1">
<WellControls
name="wellControls"
logLevel="1"
type="injector"
control="totalVolRate"
referenceElevation="-3000"
targetBHP="1e8"
enableCrossflow="0"
useSurfaceConditions="1"
surfacePressure="101325"
surfaceTemperature="288.71"
targetTotalRateTableName="totalRateTable"
injectionTemperature="353.15"
injectionStream="{ 1.0, 0.0 }"/>
<WellControls
name="MAX_MASS_INJ"
logLevel="1"
type="injector"
control="massRate"
referenceElevation="-3000"
targetBHP="1e8"
enableCrossflow="0"
useSurfaceConditions="1"
surfacePressure="101325"
surfaceTemperature="288.71"
targetMassRate="15"
injectionTemperature="353.15"
injectionStream="{ 1.0, 0.0 }"/>
<WellControls
name="MAX_MASS_INJ_TABLE"
logLevel="1"
type="injector"
(continues on next page)

1.4. Advanced Examples 137

GEOS Documentation

(continued from previous page)

control="massRate"
referenceElevation="-3000"
targetBHP="1e8"
enableCrossflow="0"
useSurfaceConditions="1"
surfacePressure="101325"
surfaceTemperature="288.71"
targetMassRateTableName="totalMassTable"
injectionTemperature="353.15"
injectionStream="{ 1.0, 0.0 }"/>
</CompositionalMultiphaseWell>

Constitutive laws

This benchmark test involves a compositional mixture that defines two phases (CO2-rich and aqueous) labeled as gas
and water which contain two components co2 and water. The miscibility of CO2 results in the presence of CO2 in
the aqueous phase. The vaporization of H2O in the CO2-rich phase is not considered here.

The brine properties are modeled using Ezrokhi correlation, hence the block name CO2BrineEzrokhiFluid. The
external PVT files tables/pvtgas.txt and tables/pvtliquid_ex.txt give access to the models considered respectively for
the computation of gas density and viscosity and the brine density and viscosity, along with pressure, temperature,
salinity discretization of the parameter space. The external file tables/co2flash.txt gives the same type of information
for the CO2Solubility model (see CO2-brine model for details).
The rock model defines a slightly compressible porous medium with a reference porosity equal to 0.1.

The relative permeability model is input through tables thanks to TableRelativePermeability block.

138 Chapter 1. Table of Contents

GEOS Documentation

As this benchmark is testing the sensitivity of the plume dynamics to the relative permeability hysteresis model-
ing, in commented block the TableRelativePermeabilityHysteresis block sets up bounding curves for imbibition
and drainage under imbibitionNonWettingRelPermTableName, imbibitionWettingRelPermTableName and,
drainageWettingNonWettingRelPermTableNames compared to the wettingNonWettingRelPermTableNames
label of the drainage only TableRelativePermeability blocks. Those link to TableFunction blocks in Functions,
which define sample points for piecewise linear interpolation. This feature is used and explained in more details in the
following section dedicated to Initial and Boundary conditions.
See,

../../../../../../../inputFiles/compositionalMultiphaseWell/benchmarks/Class09Pb3/
˓→class09_pb3_hystRelperm_iterative_base.xml

for the input base with relative permeability hysteresis setup.

<TableRelativePermeabilityHysteresis
name="relperm"
phaseNames="{ gas, water }"
drainageWettingNonWettingRelPermTableNames="{␣
˓→drainageWaterRelativePermeabilityTable,

drainageGasRelativePermeabilityTable }"
imbibitionNonWettingRelPermTableName="imbibitionGasRelativePermeabilityTable"
imbibitionWettingRelPermTableName="imbibitionWaterRelativePermeabilityTable"/>

ò Note

wettingNonWettingRelPermTableNames in TableRelativePermeability and

drainageWettingNonWettingRelPermTableNames in TableRelativePermeabilityHysteresis are identi-
cal.

Capillary pressure is also tabulated and defined in TableCapillaryPressure. No hysteresis is modeled yet on the
capillary pressure.

Initial and boundary conditions

<HydrostaticEquilibrium
name="equil"
(continues on next page)

1.4. Advanced Examples 139

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions"
datumElevation="-3000"
datumPressure="3.0e7"
initialPhaseName="water"
componentNames="{ co2, water }"
componentFractionVsElevationTableNames="{ initCO2CompFracTable,
initWaterCompFracTable }"
temperatureVsElevationTableName="initTempTable"/>

In the Functions block, the TableFunction s named initCO2CompFracTable and initWaterCompFracTable de-
fine the brine-saturated initial state, while the TableFunction named initTempTable defines the temperature field as
a function of depth to impose the geothermal gradient.
The boundaries are set to have a constant 0.03 K/m temperature gradient as well as the hydrostatic pressure gradient.
We supplement that with water dominant content. Each block is linking a fieldName to a TableFunction tagged
as the value of functionName. In order to have those imposed on the boundary faces, we provide faceManager as
objectPath.

Outputing reservoir statistics

In order to output partitioning of CO2 mass, we use reservoir statistics implemented in GEOS. This is done by defining
a Task, with flowSolverName pointing to the dedicated solver and computeRegionStatistics set to 1 to compute
statistics by regions. The setNames field is set to 3 as it is its attribute tag in the input vtu mesh.

140 Chapter 1. Table of Contents

GEOS Documentation

and an Event for this to occur recursively with a forceDt argument for the period over which statistics are output and
target pointing towards the aforementioned Task.

This is a sample of the output we will have in the log file.

compflowStatistics, reservoir: Pressure (min, average, max): 2.5139e+07, 2.93668e+07, 3.

˓→23145e+07 Pa

compflowStatistics, reservoir: Delta pressure (min, max): -12157, 158134 Pa

compflowStatistics, reservoir: Temperature (min, average, max): 293.15, 371.199, 379.828␣
˓→K

compflowStatistics, reservoir: Total dynamic pore volume: 1.57994e+09 rm^3

compflowStatistics, reservoir: Phase dynamic pore volumes: { 1.00239e+06, 1.57894e+09 }␣
˓→rm^3

compflowStatistics, reservoir: Phase mass (including both trapped and non-trapped): { 7.

˓→24891e+08, 1.6245e+12 } kg

compflowStatistics, reservoir: Trapped phase mass: { 5.3075e+08, 3.2511e+11 } kg

compflowStatistics, reservoir: Dissolved component mass: { { 7.13794e+08, 4.53966e+06 },
˓→{ 1.6338e+08, 1.62433e+12 } } kg

compflowStatistics: Max phase CFL number: 65.1284

compflowStatistics: Max component CFL number: 2.32854

ò Note

The log file mentioned above could be an explicit printout of the stdio from MPI launch or the autogenerated output
from a SLURM job slurm.out or similar

Inspecting results

We request VTK-format output files and use Paraview to visualize the results under the Outputs block.
The following figure shows the distribution of CO2 saturation thresholded above a significant value (here 0.001). The
displayed cells are colored with respect to the CO2 mass they contain. If the relative permeability for the gas phase
drops below 10e-7, the cell is displayed in black.

Fig. 1.13: Plume of CO2 saturation for significant value where immobile CO2 is colored in black.

We observe the importance of hysteresis modeling in CO2 plume migration. Indeed, during the migration phase, the
cells at the tail of the plume are switching from drainage to imbibition and the residual CO2 is trapped. This results in
a slower migration and expansion of the plume.

1.4. Advanced Examples 141

GEOS Documentation

To validate the GEOS results, we consider the metrics used in (Class et al., 2009). The reporting values are the dis-
solved and gaseous CO2 with respect to time using only the drainage relative permeability and using hysteretic relative
permeabilities.

Fig. 1.14: CO2 mass in aqueous and CO2-rich phases as a function of without relative permeability hysteresis

We can see that at the end of the injection period the mass of CO2 in the gaseous phase stops increasing and starts
decreasing due to dissolution of CO2 in the brine phase. These curves confirm the agreement between GEOS and the
results of (Class et al., 2009).

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Faults & fractures

Sneddon’s Problem

Objectives
At the end of this example you will know:
• how to define fractures in a porous medium,

142 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.15: CO2 mass in aqueous and CO2-rich phases as a function of time with relative permeability hysteresis

1.4. Advanced Examples 143

GEOS Documentation

• how to use various solvers (EmbeddedFractures, LagrangianContact and HydroFracture) to solve the mechanics
problems with fractures.
Input file
This example uses no external input files and everything required is contained within GEOS input files.
The xml input files for the case with EmbeddedFractures solver are located at:

inputFiles/efemFractureMechanics/Sneddon_embeddedFrac_base.xml
inputFiles/efemFractureMechanics/Sneddon_embeddedFrac_verification.xml

The xml input files for the case with LagrangianContact solver are located at:

inputFiles/lagrangianContactMechanics/Sneddon_base.xml
inputFiles/lagrangianContactMechanics/Sneddon_benchmark.xml
inputFiles/lagrangianContactMechanics/ContactMechanics_Sneddon_benchmark.xml

The xml input files for the case with HydroFracture solver are located at:

inputFiles/hydraulicFracturing/Sneddon_hydroFrac_base.xml
inputFiles/hydraulicFracturing/Sneddon_hydroFrac_benchmark.xml

Description of the case

We compute the displacement field induced by the presence of a pressurized fracture, of length 𝐿𝑓 , in a porous medium.
GEOS will calculate the displacement field in the porous matrix and the displacement jump at the fracture surface. We
will use the analytical solution for the fracture aperture, 𝑤𝑛 (normal component of the jump), to verify the numerical
results
√︃
2
4(1 − 𝜈 )𝑝𝑓 𝐿2𝑓
𝑤𝑛 (𝑠) = − 𝑠2
𝐸 4

where - 𝐸 is the Young’s modulus - 𝜈 is the Poisson’s ratio - 𝑝𝑓 is the fracture pressure - 𝑠 is the local fracture coordinate
𝐿 𝐿
in [− 2𝑓 , 2𝑓 ]
In this example, we focus our attention on the Solvers, the ElementRegions, and the Geometry tags.

Mechanics solver

148 Chapter 1. Table of Contents

GEOS Documentation

specified in the Geometry section.

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Units Value

𝐾 Bulk modulus [GPa] 16.7
𝐺 Shear modulus [GPa] 10.0
𝐿𝑓 Fracture length [m] 2.0
𝑝𝑓 Fracture pressure [MPa] -2.0

Note that the internal fracture pressure has a negative value, due to the negative sign convention for compressive stresses
in GEOS.
Material properties and boundary conditions are specified in the Constitutive and FieldSpecifications sections.

Adding a fracture

The static fracture is defined by a nodeset occupying a small region within the computation domain, where the fracture
tends to open upon internal pressurization:
• The test case with EmbeddedFractures solver:

• The test case with LagrangianContact solver:

• The test case with HydroFracture solver:

1.4. Advanced Examples 149

GEOS Documentation

To make these cases identical to the analytical example, fracture propagation is not allowed in this example.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, a task is specified to output
fracture aperture (normal opening); however, for different solvers, different fieldName and objectPath should be
called:
• The test case with EmbeddedFractures solver:

• The test case with LagrangianContact solver:

• The test case with Hydrofracture solver:

150 Chapter 1. Table of Contents

GEOS Documentation

These tasks are triggered using the Event manager with a PeriodicEvent defined for these recurring tasks. GEOS
writes output files named after the string defined in the filename keyword and formatted as HDF5 files. The
TimeHistory file contains the collected time history information from each specified time history collector. This
information includes datasets for the simulation time, element center defined in the local coordinate system, and the
time history information. A Python script is used to read and plot any specified subset of the time history data for
verification and visualization.

Running GEOS

To run these three cases, use the following commands:

path/to/geos -i inputFiles/efemFractureMechanics/Sneddon_embeddedFrac_verification.xml
path/to/geos -i inputFiles/lagrangianContactMechanics/ContactMechanics_Sneddon_benchmark.
xml
path/to/geos -i inputFiles/hydraulicFracturing/Sneddon_hydroFrac_benchmark.xml

Inspecting results

This plot compares the analytical solution (continuous lines) with the numerical solutions (markers) for the normal
opening of the pressurized fracture. As shown below, consistently, numerical solutions with different solvers correlate
very well with the analytical solution.

0.30

0.25
Fracture Aperture [mm]

0.20

0.15

0.10
Analytical Solution
Embedded Fracture
0.05 Lagrange Contact
HydroFrac Solver
0.00
1.00 0.75 0.50 0.25 0.00 0.25 0.50 0.75 1.00
Fracture Length [m]

1.4. Advanced Examples 151

GEOS Documentation

To go further

Feedback on this example

This concludes the Sneddon example. For any feedback on this example, please submit a GitHub issue on the project’s
GitHub page.

Single Fracture Under Shear Compression

Context
In this example, a single fracture is simulated using a Lagrange contact model in a 2D infinite domain and subjected to
a constant uniaxial compressive remote stress (Franceschini et al., 2020). An analytical solution (Phan et al., 2003) is
available for verifying the accuracy of the numerical results, providing an analytical form for the normal traction and
slip on the fracture surface due to frictional contact. In this example, the TimeHistory function and a Python script
are used to output and postprocess multi-dimensional data (traction and displacement on the fracture surface).
Input file
Everything required is contained within these GEOS input files and one mesh file located at:

inputFiles/lagrangianContactMechanics/SingleFracCompression_base.xml

inputFiles/lagrangianContactMechanics/SingleFracCompression_benchmark.xml

inputFiles/lagrangianContactMechanics/ContactMechanics_SingleFracCompression_benchmark.
˓→xml

inputFiles/lagrangianContactMechanics/crackInPlane_benchmark.vtu

Description of the case

We simulate an inclined fracture under a compressive horizontal stress (𝜎), as shown below. This fracture is placed in
an infinite, homogeneous, isotropic, and elastic medium. Uniaxial compression and frictional contact on the fracture
surface cause mechanical deformation to the surrounding rock and sliding along the fracture plane. For verification
purposes, plane strain deformation and Coulomb failure criterion are considered in this numerical model.
To simulate this phenomenon, we use a Lagrange contact model. Displacement and stress fields on the fracture plane
are calculated numerically. Predictions of the normal traction (𝑡𝑁 ) and slip (𝑔𝑇 ) on the fracture surface are compared
with the corresponding analytical solution (Phan et al., 2003).
2
𝑡𝑁 = −𝜎(sin (𝜓))

4(1 − 𝜈 2 )
√︁
2
𝑔𝑇 = (𝜎sin (𝜓) (cos (𝜓) − sin (𝜓) tan (𝜃))) 𝑏2 − (𝑏 − 𝜉)
𝐸
where 𝜓 is the inclination angle, 𝜈 is Poisson’s ratio, 𝐸 is Young’s modulus, 𝜃 is the friction angle, 𝑏 is the fracture
half-length, 𝜉 is a local coordinate on the fracture varying in the range [0, 2𝑏].
In this example, we focus our attention on the Mesh tags, the Constitutive tags, and the FieldSpecifications
tags.

Mesh

GEOS is a multi-physics platform. Different combinations of physics solvers available in the code can be applied in
different regions of the domain and be functional at different stages of the simulation. The Solvers tag in the XML
file is used to list and parameterize these solvers.
To specify a coupling between two different solvers, we define and characterize each single-physics solver separately.
Then, we customize a coupling solver between these single-physics solvers as an additional solver. This approach
allows for generality and flexibility in constructing multi-physics solvers. Each single-physics solver should be given
a meaningful and distinct name because GEOS recognizes these single-physics solvers based on their given names to
create the coupling.
To setup a coupling between rock and fracture deformations, we define three different solvers:

1.4. Advanced Examples 155

GEOS Documentation

• For solving the frictional contact, we define a Lagrangian contact solver, called here lagrangiancontact. In
this solver, we specify targetRegions that includes both the continuum region Region and the discontinuum
region Fracture where the solver is applied to couple rock and fracture deformation. The contact constitutive
law used for the fracture elements is named fractureMaterial, and defined later in the Constitutive section.
• Rock deformations are handled by a solid mechanics solver SolidMechanics_LagrangianFEM. This solid
mechanics solver (see Solid Mechanics Solver) is based on the Lagrangian finite element formulation. The
problem is run as QuasiStatic without considering inertial effects. The computational domain is discretized by
FE1, which is defined in the NumericalMethods section. The solid material is named rock, and its mechanical
properties are specified later in the Constitutive section.
• The solver SurfaceGenerator defines the fracture region and rock toughness.

Constitutive laws

For this specific problem, we simulate the elastic deformation and fracture slippage caused by uniaxial compression.
A homogeneous and isotropic domain with one solid material is assumed, with mechanical properties specified in the
Constitutive section.
Fracture surface slippage is assumed to be governed by the Coulomb failure criterion. The contact constitutive behav-
ior is named fractureMaterial in the Coulomb block, where cohesion cohesion="0.0" and friction coefficient
frictionCoefficient="0.577350269" are specified.

<Coulomb
(continues on next page)

156 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="frictionLaw"
cohesion="0.0"
frictionCoefficient="0.577350269"/>
</Constitutive>

Recall that in the SolidMechanics_LagrangianFEM section, rock is the material of the computational domain. Here,
the isotropic elastic model ElasticIsotropic is used to simulate the mechanical behavior of rock.
All constitutive parameters such as density, bulk modulus, and shear modulus are specified in the International System
of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, tractionCollection
and displacementJumpCollection tasks are specified to output the local traction fieldName="traction" and
relative displacement fieldName="displacementJump" on the fracture surface.

These two tasks are triggered using the Event management, with PeriodicEvent defined for these recurring tasks.
GEOS writes two files named after the string defined in the filename keyword and formatted as HDF5 files (displace-
mentJump_history.hdf5 and traction_history.hdf5). The TimeHistory file contains the collected time history informa-
tion from each specified time history collector. This information includes datasets for the simulation time, element
center defined in the local coordinate system, and the time history information. Then, a Python script is used to access
and plot any specified subset of the time history data for verification and visualization.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (the remote compressive stress needs to be initialized),
• The boundary conditions (the constraints of the outer boundaries have to be set).
In this tutorial, we specify an uniaxial horizontal stress (𝜎𝑥 = -1.0e8 Pa). The remaining parts of the outer boundaries
are subjected to roller constraints. These boundary conditions are set up through the FieldSpecifications section.

4.0
0.0
Relative Shear Displacement [mm]

3.5
2.5 3.0
Normal Traction [MPa]

5.0 2.5
7.5 2.0
10.0 1.5
12.5 1.0
Analytical Solution Analytical Solution
15.0 Numerical Solution Numerical Solution
0.5
17.5 0.01.00 0.75 0.50 0.25 0.00 0.25 0.50 0.75 1.00
1.00 0.75 0.50 0.25 0.00 0.25 0.50 0.75 1.00
Length [m] Length [m]

1.4. Advanced Examples 161

GEOS Documentation

Fig. 1.20: Sketch of the problem (Phan et al., 2003)

162 Chapter 1. Table of Contents

GEOS Documentation

To simulate this problem, we use a Lagrange contact model. Displacement and stress fields on the fracture plane are
calculated numerically. Predictions of the normal traction and slip along the sliding fracture and mechanical aperture
of the pressurized fracture are compared with the corresponding literature work (Phan et al., 2003).
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used in this problem.

Fig. 1.21: Generated mesh

This mesh was created using the internal mesh generator as parametrized in the InternalMesh XML tag. The mesh
contains 300 x 300 x 2 eight-node brick elements in the x, y, and z directions respectively. Such eight-node hexahedral
elements are defined as C3D8 elementTypes, and their collection forms a mesh with one group of cell blocks named
here cb1.

<Mesh>
<InternalMesh
name="mesh1"
elementTypes="{ C3D8 }"
xCoords="{ -1000, -100, 100, 1000 }"
(continues on next page)

1.4. Advanced Examples 163

GEOS Documentation

(continued from previous page)

1.4. Advanced Examples 167

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions/Region"
fieldName="rock_stress"
component="1"
scale="-1.0e8"/>
</FieldSpecifications>

Note that the remote stress and internal fracture pressure has a negative value, due to the negative sign convention for
compressive stresses in GEOS.
The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [GPa] 38.89
𝐺 Shear Modulus [GPa] 29.17
𝜎𝑦 Remote Stress [MPa] -100.0
𝑃𝑖𝑛 Internal Pressure [MPa] -100.0
𝜃 Friction Angle [Degree] 30.0
𝐿ℎ Horizontal Frac Length [m] 50.0
𝐿𝑣 Vertical Frac Length [m] 100.0

Inspecting results

We request VTK-format output files and use Paraview to visualize the results. The following figure shows the distribu-
tion of 𝜎𝑥𝑥 in the computational domain.

Fig. 1.22: Simulation result of 𝜎𝑥𝑥

168 Chapter 1. Table of Contents

GEOS Documentation

The next figure shows the distribution of relative shear displacement values along the surface of two intersected frac-
tures.

Fig. 1.23: Simulation result of fracture slip

The figure below compares the results from GEOS (marks) and the corresponding literature reference solution (solid
curves) for the normal traction and slip distributions along the horizontal fracture and opening of the vertical fracture.
GEOS reliably captures the mechanical interactions between two intersected fractures and shows excellent agreement
with the reference solution. Due to sliding of the horizontal fracture, GEOS prediction as well as the reference solution
on the normal opening of pressurized vertical fracture deviates away from Sneddon’s analytical solution, especially
near the intersection point.

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Verification of Induced Stresses Along a Fault

Context
In this example, we evaluate the induced stresses in a pressurized reservoir displaced by a normal fault (permeable or
impermeable). This problem is solved using the poroelastic solver in GEOS to obtain the stress perturbations along the
fault plane, which are verified against the corresponding analytical solution (Wu et al., 2020).
Input file
The xml input files for the test case with impermeable fault are located at:

1.4. Advanced Examples 169

GEOS Documentation

120
Normal Traction [MPa]
100 50
80 25

Slip [mm]
60 0
40 25
20 Phan et al.(2003) 50 Phan et al.(2003)
0 GEOSX Results GEOSX Results
20 10 0 10 20 20 10 0 10 20
Horizontal Frac Length [m] Horizontal Frac Length [m]

250
Aperture [mm]

200
150
100
50 Phan et al.(2003)
GEOSX Results
0 Sneddon Solution
40 20 0 20 40
Vertical Frac Length [m]

inputFiles/poromechanics/faultPoroelastic_base.xml
inputFiles/poromechanics/impermeableFault_benchmark.xml

The xml input files for the test case with permeable fault are located at:

inputFiles/poromechanics/faultPoroelastic_base.xml
inputFiles/poromechanics/permeableFault_benchmark.xml

A mesh file and a python script for post-processing the simulation results are also provided:

inputFiles/poromechanics/faultMesh.vtu

src/docs/sphinx/advancedExamples/validationStudies/faultMechanics/faultVerification/
˓→faultVerificationFigure.py

Description of the case

We simulate induced stresses along a normal fault in a pressurized reservoir and compare our results against an analyti-
cal solution. In conformity to the analytical set-up, the reservoir is divided into two parts by an inclined fault. The fault
crosses the entire domain, extending into the overburden and the underburden. The domain is horizontal, infinite, ho-
mogeneous, isotropic, and elastic. The reservoir is pressurized uniformely upon injection, and we neglect the transient
effect of fluid flow. A pressure buildup is applied to: (i) the whole reservoir in the case of a permeable fault; (ii) the
left compartment in the case of an impermeable fault. The overburden and underburden are impermeable (no pressure
changes). Due to poromechanical effects, pore pressure changes in the reservoir cause a mechanical deformation of the
entire domain. This deformation leads to a stress perturbation on the fault plane that could potentially trigger sliding
of the fault. Here, the fault serves only as a flow boundary, and the mechanical separation of the fault plane (either by
shear slippage or normal opening) is prohibited, like in the analytical example. For verification purposes, a plane strain
deformation is considered in the numerical model.
In this example, we set up and solve a poroelastic model to obtain the spatial solutions of displacement and stress fields

170 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.24: Sketch of the problem

across the domain upon pressurization. Changes of total stresses along the fault plane are evaluated and compared with
the corresponding published work (Wu et al., 2020).
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used in this problem.

Fig. 1.25: Imported mesh

Here, we load the mesh with VTKMesh. The syntax to import external meshes is simple: in the XML file, the mesh file
faultMesh.vtu is included with its relative or absolute path to the location of the GEOS XML file and a user-specified
label (here FaultModel) is given to the mesh object. This mesh contains quadrilateral elements and local refinement
to conform with the fault geometry, and two reservoir compartments displaced by the fault. The size of the reservoir

1.4. Advanced Examples 171

GEOS Documentation

should be large enough to avoid boundary effects.

Solid mechanics solver

GEOS is a multi-physics platform. Different combinations of physics solvers available in the code can be applied in
different regions of the domain and be functional at different stages of the simulation. The Solvers tag in the XML
file is used to list and parameterize these solvers.
To specify a coupling between two different solvers, we define and characterize each single-physics solver separately.
Then, we customize a coupling solver between these single-physics solvers as an additional solver. This approach
allows for generality and flexibility in constructing multi-physics solvers. The order in which solvers are specified is
not important in GEOS. Note that end-users should give each single-physics solver a meaningful and distinct name, as
GEOS will recognize these single-physics solvers based on their customized names to create the expected couplings.
As demonstrated in this example, to setup a poromechanical coupling, we need to define three different solvers in the
XML file:
• the mechanics solver, a solver of type SolidMechanics_LagrangianFEM called here mechanicsSolver (more
information here: Solid Mechanics Solver),

<SolidMechanics_LagrangianFEM
name="mechanicsSolver"
timeIntegrationOption="QuasiStatic"
logLevel="1"
discretization="FE1"
targetRegions="{ Domain }">
<NonlinearSolverParameters
newtonTol = "1.0e-5"
newtonMaxIter = "15"/>
<LinearSolverParameters
solverType="gmres"
krylovTol="1.0e-10"/>
</SolidMechanics_LagrangianFEM>

• the single-phase flow solver, a solver of type SinglePhaseFVM called here singlePhaseFlowSolver (more
information on these solvers at Singlephase Flow Solver),

<SinglePhaseFVM
name="singlePhaseFlowSolver"
logLevel="1"
discretization="singlePhaseTPFA"
targetRegions="{ Domain }">
<NonlinearSolverParameters
newtonTol = "1.0e-6"
newtonMaxIter = "8"
/>
<LinearSolverParameters
solverType="gmres"
(continues on next page)

172 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

krylovTol="1.0e-12"/>
</SinglePhaseFVM>
</Solvers>

• the coupling solver (SinglePhasePoromechanics) that will bind the two single-physics solvers above, named
poromechanicsSolver (more information at Poromechanics Solver).

<Solvers gravityVector="{0.0, 0.0, 0.0}">

The two single-physics solvers are parameterized as explained in their corresponding documents.
In this example, let us focus on the coupling solver. This solver (poromechanicsSolver) uses a set of attributes that
specifically describe the coupling process within a poromechanical framework. For instance, we must point this solver
to the designated fluid solver (here: singlePhaseFlowSolver) and solid solver (here: mechanicsSolver). These
solvers are forced to interact with all the constitutive models in the target regions (here, we only have one, Domain).
More parameters are required to characterize a coupling procedure (more information at Poromechanics Solver). This
way, the two single-physics solvers will be simultaneously called and executed for solving the problem.

Discretization methods for multiphysics solvers

Numerical methods in multiphysics settings are similar to single physics numerical methods. In this problem, we use
finite volume for flow and finite elements for solid mechanics. All necessary parameters for these methods are defined
in the NumericalMethods section.
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, please see the
dedicated Finite Element Discretization section.
The finite volume method requires the specification of a discretization scheme. Here, we use a two-point flux ap-
proximation scheme (singlePhaseTPFA), as described in the dedicated documentation (found here: Finite Volume
Discretization).

<NumericalMethods>
<FiniteElements>
<FiniteElementSpace
name="FE1"
order="1"/>
(continues on next page)

1.4. Advanced Examples 173

GEOS Documentation

(continued from previous page)

</FiniteElements>

Constitutive laws

For this problem, a homogeneous and isotropic domain with one solid material is assumed for both the reservoir
and its surroundings. The solid and fluid materials are named as rock and water respectively, and their mechan-
ical properties are specified in the Constitutive section. PorousElasticIsotropic model is used to describe
the linear elastic isotropic response of rock when subjected to fluid injection. And the single-phase fluid model
CompressibleSinglePhaseFluid is selected to simulate the flow of water.
<Constitutive>
<PorousElasticIsotropic
name="porousRock"
solidModelName="rock"
porosityModelName="rockPorosity"
permeabilityModelName="rockPerm"
/>

<ConstantPermeability
name="rockPerm"
permeabilityComponents="{1.0e-18, 1.0e-18, 1.0e-18}"
(continues on next page)

174 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

/>
</Constitutive>

All constitutive parameters such as density, viscosity, and Young’s modulus are specified in the International System
of Units.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (the in-situ stresses and pore pressure have to be initialized),
• The boundary conditions (pressure buildup within the reservoir and constraints of the outer boundaries have to
be set).
In this example, we need to specify isotropic horizontal total stress (𝜎ℎ = -60.0 MPa and 𝜎𝐻 = -60.0 MPa), vertical total
stress (𝜎𝑣 = -70.0 MPa), and initial reservoir pressure (𝑃0 = 35.0 MPa). When initializing the model, a normal traction
(name="NormalTraction") of -70.0 MPa is imposed on the upper boundary (setNames="{ 91 }") to reach me-
chanical equilibrium. The lateral and lower boundaries are subjected to roller constraints. These boundary conditions
are set up through the FieldSpecifications section.
<FieldSpecifications>
<FieldSpecification
name="initialPressure"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/Domain"
fieldName="pressure"
scale="35.0e6"
/>

<FieldSpecification
name="stressZZ"
initialCondition="1"
(continues on next page)

1.4. Advanced Examples 175

GEOS Documentation

(continued from previous page)

setNames="{all}"
objectPath="ElementRegions/Domain"
fieldName="rock_stress"
component="2"
scale="-28.499545e6"
/>

In this example, the only difference between the impermeable fault and permeable fault cases is how to apply pressure
buildup. For the impermeable fault case, a constant pressure buildup is imposed to the left compartment of the reservoir
(objectPath="ElementRegions/Domain/97_hexahedra"):

176 Chapter 1. Table of Contents

GEOS Documentation

For the permeable fault case, a constant pressure buildup is imposed to both compartments of the reser-
voir: (objectPath="ElementRegions/Domain/97_hexahedra" and objectPath="ElementRegions/Domain/
96_hexahedra"):

The parameters used in the simulation are summarized in the following table, which are specified in the Constitutive
and FieldSpecifications sections. Note that stresses and traction have negative values, due to the negative sign
convention for compressive stresses in GEOS.

Symbol Parameter Unit Value

𝐸 Young’s Modulus [GPa] 14.95
𝜈 Poisson’s Ratio [-] 0.15
𝜎ℎ Min Horizontal Stress [MPa] -60.0
𝜎𝐻 Max Horizontal Stress [MPa] -60.0
𝜎𝑣 Vertical Stress [MPa] -70.0
𝑝0 Initial Reservoir Pressure [MPa] 35.0
∆𝑝 Pressure Buildup [MPa] 20.0
𝐾𝑠 Grain Bulk Modulus [GPa] 71.2
𝜃 Fault Dip [Degree] 60.0
𝜅 Matrix Permeability [m2 ] 1.0*10-18
𝜑 Porosity [-] 0.3
𝐷𝐿 Domain Length [m] 4000.0
𝐷𝑊 Domain Width [m] 2000.0
𝐷𝑇 Domain Thickness [m] 1000.0
𝑅𝑒𝑠𝑇 Reservoir Thickness [m] 300.0
𝐹𝑜𝑓 𝑓 Fault Vertical Offset [m] 100.0

Inspecting results

We request VTK-format output files and use Paraview to visualize the results. The following figure shows the distribu-
tion of resulting shear stress (𝜎𝑥𝑦 ) in the computational domain for two different cases (a permeable vs. an impermeable
fault). Numerical solutions for both cases are also compared with the corresponding analytical solutions.
The figure below compares the results from GEOS (marks) and the corresponding analytical solution (solid curves)
for the change of total stresses (𝜎𝑥𝑥 , 𝜎𝑦𝑦 and 𝜎𝑥𝑦 ) along the fault plane. As shown, GEOS reliably captures the
mechanical deformation of the faulted reservoir and shows excellent agreement with the analytical solutions for two

1.4. Advanced Examples 177

GEOS Documentation

Fig. 1.26: Simulation results of 𝜎𝑥𝑦

different scenarios. Differences in the stress perturbations between the cases with permeable and impermeable fault
are also noticeable, which suggests that fault permeability plays a crucial role in governing reservoir deformation for
the problems with reservoir pressurization or depletion.

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Hydraulic Fracture
Toughness dominated KGD hydraulic fracture

Description of the case

In this example, we consider a plane-strain hydraulic fracture propagating in an infinite, homogeneous and elastic
medium, due to fluid injection at a rate 𝑄0 during a period from 0 to 𝑡𝑚𝑎𝑥 . Two dimensional KGD fracture is charac-
terized as a vertical fracture with a rectangle-shaped cross section. For verification purpose, the presented numerical
model is restricted to the assumptions used to analytically solve this problem (Bunger et al., 2005). Vertical and im-
permeable fracture surface is assumed, which eliminate the effect of fracture plane inclination and fluid leakoff. The
injected fluid flows within the fracture, which is assumed to be governed by the lubrication equation resulting from
the mass conservation and the Poiseuille law. Fracture profile is related to fluid pressure distribution, which is mainly
dictated by fluid viscosity 𝜇. In addition, fluid pressure contributes to the fracture development through the mechanical
deformation of the solid matrix, which is characterized by rock elastic properties, including the Young modulus 𝐸, and
the Poisson ratio 𝜈.

178 Chapter 1. Table of Contents

GEOS Documentation

300 Analytical_imp
300 300
GEOSX_imp
Analytical_per
GEOSX_per
200 200 200

100 100 100

y (m)

y (m)
0 0 0

100 100 100

200 200 200

300 20 10 0 30012 8 4 0 4 8 12 30014 7 0 7 14

xx (MPa) yy (MPa) xy (MPa)

For toughness-dominated fractures, more work is spent to split the intact rock than that applied to move the fracturing
fluid. To make the case identical to the toughness dominated asymptotic solution, incompressible fluid with an ultra-
low viscosity of 0.001 cp and medium rock toughness should be defined. Fracture is propagating with the creation of
new surface if the stress intensity factor exceeds rock toughness 𝐾𝐼𝑐 .
In toughness-storage dominated regime, asymptotic solutions of the fracture length ℓ, the net pressure 𝑝0 and the
fracture aperture 𝑤0 at the injection point for the KGD fracture are provided by (Bunger et al., 2005):

𝐸𝑝 𝑄30 1/6 2/3

ℓ = 0.9324𝑋 −1/6 ( ) 𝑡
12𝜇
12𝜇𝑄0 1/2
𝑤02 = 0.5𝑋 1/2 ( ) ℓ
𝐸𝑝
𝑤0 𝑝0 = 0.125𝑋 1/2 (12𝜇𝑄0 𝐸𝑝 )1/2

where the plane modulus 𝐸𝑝 is defined by

𝐸
𝐸𝑝 =
1 − 𝜈2
and the term 𝑋 is given as:
4
256 𝐾𝐼𝑐
𝑋=
3𝜋 2 𝜇𝑄0 𝐸𝑝 3

Input file
The input xml files for this test case are located at:

inputFiles/hydraulicFracturing/kgdToughnessDominated_base.xml

and

inputFiles/hydraulicFracturing/kgdToughnessDominated_benchmark.xml

The corresponding integrated test with coarser mesh and smaller injection duration is also prepared:

1.4. Advanced Examples 179

GEOS Documentation

inputFiles/hydraulicFracturing/kgdToughnessDominated_Smoke.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

inputFiles/hydraulicFracturing/scripts/hydrofractureQueries.py

inputFiles/hydraulicFracturing/scripts/hydrofractureFigure.py

Mechanics solvers

The solver SurfaceGenerator defines rock toughness 𝐾𝐼𝑐 as:

Rock and fracture deformation are modeled by the solid mechanics solver SolidMechanicsLagrangianSSLE. In
this solver, we define targetRegions that includes both the continuum region and the fracture region. The name
of the contact constitutive behavior is also specified in this solver by the contactRelationName, besides the
solidMaterialNames.

The single phase fluid flow inside the fracture is solved by the finite volume method in the solver SinglePhaseFVM as:

<PackCollection
name="sourcePressureCollection"
objectPath="ElementRegions/Fracture/FractureSubRegion"
fieldName="pressure"
setNames="{ source }"/>

These tasks are triggered using the Event manager with a PeriodicEvent defined for the recurring tasks.
GEOS writes one file named after the string defined in the filename keyword and formatted as a HDF5 file
(kgdToughnessDominated_output.hdf5). This TimeHistory file contains the collected time history information
from specified time history collector. This file includes datasets for the simulation time, fluid pressure, element aper-
ture, hydraulic aperture and element area for the propagating hydraulic fracture. A Python script is prepared to read
and query any specified subset of the time history data for verification and visualization.
The parameters used in the simulation are summarized in the following table.

1.4. Advanced Examples 183

GEOS Documentation

Symbol Parameter Units Value

3
𝑄0 Injection rate [m /s] 10-4
𝐸 Young’s modulus [GPa] 30
𝜈 Poisson’s ratio [-] 0.25
𝜇 Fluid viscosity [Pa.s] 10-6
𝐾𝐼𝑐 Rock toughness [MPa.m1/2 ] 1

Inspecting results

Fracture propagation during the fluid injection period is shown in the figure below.

First, by running the query script

python ./hydrofractureQueries.py kgdToughnessDominated

the HDF5 output is postprocessed and temporal evolution of fracture characterisctics (fluid pressure and fracture width
at fluid inlet and fracure half length) are saved into a txt file model-results.txt, which can be used for verification
and visualization:

[[' time', ' pressure', ' aperture', ' length']]

2 4.086e+05 8.425e-05 2
4 3.063e+05 0.0001021 3
6 3.121e+05 0.0001238 3.5
8 2.446e+05 0.0001277 4.5
10 2.411e+05 0.0001409 5

Note: GEOS python tools geosx_xml_tools should be installed to run the query script (See Python Tools Setup for
details).
A good agreement between GEOS results and analytical solutions is shown in the comparison below, which is generated
using the visualization script:

python ./kgdToughnessDominatedFigure.py

To go further

Feedback on this example

This concludes the toughness dominated KGD example. For any feedback on this example, please submit a GitHub
issue on the project’s GitHub page.

Viscosity dominated KGD hydraulic fracture

Description of the case

The KGD problem addresses a single plane strain fracture growing in an infinite elastic domain. Basic assumptions and
characteristic shape for this example is similar to those of another case (Viscosity dominated KGD hydraulic fracture)
except that the viscosity dominated regime is now considered. In this regime, more work is spent to move the fracturing
fluid than to split the intact rock. In this test, slickwater with a constant viscosity of 1 cp is chosen as fracturing fluid,
whose compressibility is neglected. To make the case identical to the viscosity dominated asymptotic solution, an ultra-
low rock toughness 𝐾𝐼𝑐 is defined and fracture is assumed to be always propagating following fluid front. Asymptotic

184 Chapter 1. Table of Contents

GEOS Documentation

2.0

Fracture Mouth Opening (mm)

20
Fracture Half Length (m)

1.5
15

10 1.0

5 0.5
Asymptotic ( => 0, CL => 0 )
GEOSX ( => 0, CL => 0 )
0 20 40 60 80 100 0.0 20 40 60 80 100
Time (s) Time (s)
1.50
Net Pressure at Well (MPa)

1.25
1.00
0.75
0.50
0.25
0.00 20 40 60 80 100
Time (s)

1.4. Advanced Examples 185

GEOS Documentation

solutions of the fracture length ℓ, the net pressure 𝑝0 and the fracture aperture 𝑤0 at the injection point for the KGD
fracture with a viscosity dominated regime are provided by (Adachi and Detournay, 2002):
𝐸𝑝 𝑄30 1/6 2/3
ℓ = 0.6152( ) 𝑡
12𝜇
12𝜇𝑄0 1/2
𝑤02 = 2.1( ) ℓ
𝐸𝑝
𝑤0 𝑝0 = 0.62(12𝜇𝑄0 𝐸𝑝 )1/2
where the plane modulus 𝐸𝑝 is defined by
𝐸
𝐸𝑝 =
1 − 𝜈2
and the term 𝑋 is given as:
4
256 𝐾𝐼𝑐
𝑋=
3𝜋 𝜇𝑄0 𝐸𝑝 3
2

Input file
The input xml files for this test case are located at:

inputFiles/hydraulicFracturing/kgdViscosityDominated_base.xml

and

inputFiles/hydraulicFracturing/kgdViscosityDominated_benchmark.xml

The corresponding integrated test with coarser mesh and smaller injection duration is also prepared:

inputFiles/hydraulicFracturing/kgdViscosityDominated_smoke.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

inputFiles/hydraulicFracturing/scripts/hydrofractureQueries.py

inputFiles/hydraulicFracturing/scripts/hydrofractureFigure.py

Fluid rheology and rock toughness are defined in the xml blocks below. Please note that setting an absolute zero value
for the rock toughness could lead to instability issue. Therefore, a low value of 𝐾𝐼𝑐 is used in this example.

186 Chapter 1. Table of Contents

GEOS Documentation

First, by running the query script

python ./hydrofractureQueries.py kgdViscosityDominated

[[' time', ' pressure', ' aperture', ' length']]

2 1.075e+06 0.0001176 1.5
4 9.636e+05 0.0001645 2
6 8.372e+05 0.0001917 2.5
8 7.28e+05 0.000209 3
10 6.512e+05 0.000222 3.5

python ./kgdViscosityDominatedFigure.py

2.0
Fracture Mouth Opening (mm)

15.0
Fracture Half Length (m)

12.5 1.5
10.0
7.5 1.0
5.0 0.5
2.5 Asymptotic ( KIC => 0, CL => 0 )
GEOSX ( KIC => 0, CL => 0 )
0.0 20 40 60 80 100 0.0 20 40 60 80 100
Time (s) Time (s)
1.50
Net Pressure at Well (MPa)

1.25
1.00
0.75
0.50
0.25
0.00 20 40 60 80 100
Time (s)

1.4. Advanced Examples 187

GEOS Documentation

To go further

Feedback on this example

This concludes the viscosity dominated KGD example. For any feedback on this example, please submit a GitHub
issue on the project’s GitHub page.

Validating KGD Hydraulic Fracture with Experiment

Context
In this example, we use GEOS to model a planar hydraulic fracture propagating in a finite domain subject to traction-
free external boundaries. Contrary to the classic KGD problems, we do not assume an infinite rock domain. Existing
analytical solutions cannot model fracture behavior in this scenario, so this problem is solved using the hydrofracture
solver in GEOS. We validate the simulation results against a benchmark experiment (Rubin, 1983).
Input file
This example uses no external input files. Everything we need is contained within two GEOS input files:

inputFiles/hydraulicFracturing/kgdValidation_base.xml

inputFiles/hydraulicFracturing/kgdValidation_benchmark.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

src/docs/sphinx/advancedExamples/validationStudies/hydraulicFracture/kgdValidation/
˓→kgdValidationQueries.py

src/docs/sphinx/advancedExamples/validationStudies/hydraulicFracture/kgdValidation/
˓→kgdValidationFigure.py

Description of the case

We simulate a hydraulic fracturing experiment within a finite domain made of three layers of polymethylmethacrylate
(PMMA). As shown below, we inject viscous fluid to create a single planar fracture in the middle layer. The target layer
is bonded weakly to the adjacent layers, so a vertical fracture develops inside the middle layer. Four pressure gages are
placed to monitor wellbore pressure (gage 56) and fluid pressure along the fracture length (gage 57, 58, and 59). A linear
variable differential transducer (LVDT) measures the fracture aperture at 28.5 mm away from the wellbore. Images are
taken at regular time intervals to show the temporal evolution of the fracture extent. All experimental measurements
for the time history of pressure, aperture, and length are reported in Rubin (1983). We use GEOS to reproduce the
conditions of this test, including material properties and pumping parameters. In the experiment, the upper and lower
layers are used only to restrict the fracture height growth, they are therefore not simulated in GEOS but are present as
boundary conditions. Given the vertical plane of symmetry, only half of the middle layer is modeled. For verification
purposes, a plane strain deformation and zero fluid leak-off are considered in the numerical model.
In this example, we solve the hydraulic fracturing problem with the hydrofrac solver to obtain the temporal solution
of the fracture characteristics (length, aperture and pressure). These modeling predictions are compared with the
corresponding experimental results (Rubin, 1983).
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

188 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.27: Sketch of the problem

Mesh

The following figure shows the mesh used in this problem.

Fig. 1.28: Generated mesh

We use the internal mesh generator to create a computational domain (0.1525 𝑚 ×0.096 𝑚 ×0.055 𝑚), as parametrized
in the InternalMesh XML tag. The structured mesh contains 80 x 18 x 10 eight-node brick elements in the x, y, and
z directions respectively. Such eight-node hexahedral elements are defined as C3D8 elementTypes, and their collection
forms a mesh with one group of cell blocks named here cb1. Along the y-axis, refinement is performed for the elements
in the vicinity of the fracture plane.

<InternalMesh
(continues on next page)

1.4. Advanced Examples 189

GEOS Documentation

(continued from previous page)

name="mesh1"
elementTypes="{C3D8}"
xCoords="{ 0, 0.1525 }"
yCoords="{ -0.048, -0.012, -0.006, 0.006, 0.012, 0.048 }"
zCoords="{ 0.037, 0.092 }"
nx="{ 80 }"
ny="{ 4, 2, 6, 2, 4 }"
nz="{ 10 }"
cellBlockNames="{cb1}"/>

The fracture plane is defined by a nodeset occupying a small region within the computation domain, where the fracture
tends to open and propagate upon fluid injection:

Solid mechanics solver

• Rock and fracture deformation are modeled by the solid mechanics solver SolidMechanicsLagrangianSSLE.
In this solver, we define targetRegions that includes both the continuum region and the fracture region. The
name of the contact constitutive behavior is specified in this solver by the contactRelationName.

<SolidMechanicsLagrangianSSLE
name="lagsolve"
timeIntegrationOption="QuasiStatic"
discretization="FE1"
targetRegions="{ Domain, Fracture }"
(continues on next page)

190 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

contactRelationName="fractureContact"
contactPenaltyStiffness="1.0"/>

• The single-phase fluid flow inside the fracture is solved by the finite volume method in the solver
SinglePhaseFVM.

• The solver SurfaceGenerator defines the fracture region and rock toughness. With nodeBasedSIF="0",
edge-based Stress Intensity Factor (SIF) calculation is chosen for the fracture propagation criterion.

Constitutive laws

For this problem, a homogeneous and isotropic domain with one solid material is assumed, and its mechanical
properties and associated fluid rheology are specified in the Constitutive section. ElasticIsotropic model is
used to describe the mechanical behavior of rock, when subjected to fluid injection. The single-phase fluid model
CompressibleSinglePhaseFluid is selected to simulate the response of water upon fracture propagation.

<NullModel
(continues on next page)

1.4. Advanced Examples 191

GEOS Documentation

(continued from previous page)

name="nullSolid"/>

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, pressureCollection,
apertureCollection, hydraulicApertureCollection and areaCollection are specified to output the time
history of fracture characterisctics (pressure, width and area). objectPath="ElementRegions/Fracture/
FractureSubRegion" indicates that these PackCollection tasks are applied to the fracure element subregion.

These tasks are triggered using the Event manager with a PeriodicEvent defined for the recurring tasks.

192 Chapter 1. Table of Contents

GEOS Documentation

GEOS writes one file named after the string defined in the filename keyword and formatted as a HDF5 file
(KGD_validation_output.hdf5). This TimeHistory file contains the collected time history information from speci-
fied time history collector. This file includes datasets for the simulation time, fluid pressure, element aperture, hydraulic
aperture and element area for the propagating hydraulic fracture. A Python script is prepared to read and query any
specified subset of the time history data for verification and visualization.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial values: the waterDensity, separableFace and the ruptureState of the propagating fracture
have to be initialized,
• The boundary conditions: fluid injection rates and the constraints of the outer boundaries have to be set.
In this example, a mass injection rate SourceFlux (scale="-0.0000366") is applied at the surfaces of the initial
fracture. Only half of the injection rate is defined in this boundary condition because only a half-wing of the fracture
is modeled (the problem is symmetric). The value given for scale is 𝑄0 𝜌𝑓 /2 (not 𝑄0 /2). The lateral surfaces (xpos,
ypos and yneg) are traction free. The remaining parts of the outer boundaries are subjected to roller constraints. These
boundary conditions are set up through the FieldSpecifications section.

<FieldSpecification
(continues on next page)

1.4. Advanced Examples 193

GEOS Documentation

(continued from previous page)

name="xConstraint"
objectPath="nodeManager"
fieldName="totalDisplacement"
component="0"
scale="0.0"
setNames="{ xneg }"/>

Note that the applied traction has a negative value, due to the negative sign convention for compressive stresses in
GEOS.
The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [GPa] 4.11
𝐺 Shear Modulus [GPa] 1.2
𝐾𝐼𝑐 Rock Toughness [MPa.m1/2 ] 1.2
𝜇 Fluid Viscosity [Pa.s] 97.7
𝑄0 Injection Rate [m3 /s] 73.2x10-9
𝑡𝑖𝑛𝑗 Injection Time [s] 100
ℎ𝑓 Fracture Height [mm] 55

Inspecting results

The following figure shows the distribution of 𝜎𝑦𝑦 at 𝑡 = 100𝑠 within the computational domain..
By running the query script kgdValidationQueries.py, the HDF5 output is postprocessed and temporal evolution
of fracture characterisctics (fluid pressure and fracture width at fluid inlet and fracure half length) are saved into a txt
file model-results.txt, which can be used for verification and visualization:

[[' time', ' wpressure', '58pressure', '57pressure', ' Laperture', ' area']]
0 0 0 0 0 0.0001048
0.1 1.515e+07 0 0 0 0.0003145
0.2 1.451e+07 0 0 0 0.0003774
0.3 1.349e+07 0 0 0 0.0004194
0.4 1.183e+07 0 0 0 0.0005662
0.5 1.125e+07 0 0 0 0.0005662

Note: GEOS python tools geosx_xml_tools should be installed to run the query script (See Python Tools Setup for
details).
The figure below shows simulation results of the fracture extent at the end of the injection, which is generated using
the visualization script kgdValidationFigure.py. The temporal evolution of the fracture characteristics (length,
aperture and pressure) from the GEOS simulation are extracted and compared with the experimental data gathered at
specific locations. As observed, the time history plots of the modelling predictions (green curves) for the pressure at
three gage locations, the fracture length, and the fracture aperture at LVDT location correlate well with the experimental
data (blue circles).

194 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.29: Simulation result of 𝜎𝑥𝑥 at 𝑡 = 100𝑠

10
Experiment (Rubin, 1983)
Pressure @ Well (MPa)

8 GEOSX
6
4
2
00 20 40 60 80 100
Time (s)
5 150
Pressure @ Gage 58 (MPa)

Fracture Length (mm)

4 125
100
3
75
2
50
1 25
00 20 40 60 80 100 00 20 40 60 80 100
Time (s) Time (s)
5 800
Pressure @ Gage 57 (MPa)

Aperture @ LVDT (um)

4 600
3
400
2
1 200

00 20 40 60 80 100 00 20 40 60 80 100
Time (s) Time (s)

1.4. Advanced Examples 195

GEOS Documentation

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Toughness-Storage-Dominated Penny Shaped Hydraulic Fracture

Context
In this example, we simulate the growth of a radial hydraulic fracture in toughness-storage-dominated regime, a classic
benchmark in hydraulic fracturing (Settgast et al., 2016). The developed fracture is characterized as a planar fracture
with an elliptical cross-section perpendicular to the fracture plane and a circular fracture tip. This problem is solved
using the hydrofracture solver in GEOS. The modeling predictions on the temporal evolutions of the fracture charac-
teristics (length, aperture, and pressure) are verified against the analytical solutions (Savitski and Detournay, 2002).
Input file
This example uses no external input files. Everything we need is contained within two GEOS input files:

inputFiles/hydraulicFracturing/pennyShapedToughnessDominated_base.xml

inputFiles/hydraulicFracturing/pennyShapedToughnessDominated_benchmark.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

inputFiles/hydraulicFracturing/scripts/hydrofractureQueries.py

inputFiles/hydraulicFracturing/scripts/hydrofractureFigure.py

Description of the case

We model a radial fracture emerging from a point source and forming a perfect circular shape in an infinite, isotropic,
and homogenous elastic domain. As with the KGD problem, we simplify the model to a radial fracture in a toughness-
storage-dominated propagation regime. For toughness-dominated fractures, more work is spent on splitting the intact
rock than on moving the fracturing fluid. Storage-dominated propagation occurs if most of the fracturing fluid is
contained within the propagating fracture.
√ In this analysis, incompressible fluid with ultra-low viscosity (0.001𝑐𝑝)
and medium rock toughness (3.0𝑀 𝑃 𝑎 𝑚) are specified. In addition, an impermeable fracture surface is assumed to
eliminate the effect of fluid leak-off. This way, the GEOS simulations represent cases within the valid range of the
toughness-storage-dominated assumptions.
In this model, the injected fluid within the fracture follows the lubrication equation resulting from mass conservation
and Poiseuille’s law. The fracture propagates by creating new surfaces if the stress intensity factor exceeds the local rock
toughness 𝐾𝐼𝐶 . By symmetry, the simulation is reduced to a quarter-scale to save computational cost. For verification
purposes, a plane strain deformation is considered in the numerical model.
In this example, we set up and solve a hydraulic fracture model to obtain the temporal solutions of the fracture radius
𝑅, the net pressure 𝑝0 and the fracture aperture 𝑤0 at the injection point for the penny-shaped fracture developed in
this toughness-storage-dominated regime. The numerical predictions from GEOS are then compared with the corre-
sponding asymptotic solutions (Savitski and Detournay, 2002):

𝐸𝑝2 𝑄20 𝑡2 1/5

𝑅(𝑡) = 0.8546( )
𝐾𝑝2

𝐾𝑝4 𝑄0 𝑡 1/5
𝑤0 (𝑡) = 0.6537( )
𝐸𝑝4

196 Chapter 1. Table of Contents

GEOS Documentation

𝐾𝑝6 1/5
𝑝0 (𝑡) = 0.3004( )
𝐸𝑝 𝑄0 𝑡
where the plane modulus 𝐸𝑝 is related to Young’s modulus 𝐸 and Poisson’s ratio 𝜈:

𝐸
𝐸𝑝 =
1 − 𝜈2
The term 𝐾𝑝 is proportional to the rock toughness 𝐾𝐼𝐶 :

8
𝐾𝑝 = √ 𝐾𝐼𝐶
2𝜋
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used in this problem.

Fig. 1.30: Generated mesh

We use the internal mesh generator to create a computational domain (400 𝑚 × 400 𝑚 × 800 𝑚), as parametrized in
the InternalMesh XML tag. The structured mesh contains 80 x 80 x 60 eight-node brick elements in the x, y, and z
directions respectively. Such eight-node hexahedral elements are defined as C3D8 elementTypes, and their collection
forms a mesh with one group of cell blocks named here cb1. Local refinement is performed for the elements in the
vicinity of the fracture plane.
Note that the domain size in the direction perpendicular to the fracture plane, i.e. z-axis, must be at least ten times of
the final fracture radius to minimize possible boundary effects.

1.4. Advanced Examples 197

GEOS Documentation

The fracture plane is defined by a nodeset occupying a small region within the computation domain, where the fracture
tends to open and propagate upon fluid injection:

Solid mechanics solver

198 Chapter 1. Table of Contents

GEOS Documentation

• The single-phase fluid flow inside the fracture is solved by the finite volume method in the solver
SinglePhaseFVM.

• The solver SurfaceGenerator defines the fracture region and rock toughness rockToughness="3.0e6".
With nodeBasedSIF="1", a node-based Stress Intensity Factor (SIF) calculation is chosen for the fracture prop-
agation criterion.

Constitutive laws

For this problem, a homogeneous and isotropic domain with one solid material is assumed. Its mechanical prop-
erties and associated fluid rheology are specified in the Constitutive section. ElasticIsotropic model is
used to describe the mechanical behavior of rock when subjected to fluid injection. The single-phase fluid model
CompressibleSinglePhaseFluid is selected to simulate the response of water upon fracture propagation.

<Constitutive>
<CompressibleSinglePhaseFluid
name="water"
defaultDensity="1000"
(continues on next page)

1.4. Advanced Examples 199

GEOS Documentation

(continued from previous page)

defaultViscosity="1.0e-6"
referencePressure="0.0"
compressibility="5e-13"
referenceViscosity="1.0e-6"
viscosibility="0.0"/>

</Constitutive>

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, pressureCollection,
apertureCollection, hydraulicApertureCollection and areaCollection are specified to output the time
history of fracture characterisctics (pressure, width and area). objectPath="ElementRegions/Fracture/
FractureSubRegion" indicates that these PackCollection tasks are applied to the fracure element subregion.

<Tasks>
<PackCollection
(continues on next page)

200 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="pressureCollection"
objectPath="ElementRegions/Fracture/FractureSubRegion"
fieldName="pressure"/>

These tasks are triggered using the Event manager with a PeriodicEvent defined for the recurring tasks.
GEOS writes one file named after the string defined in the filename keyword and formatted as a HDF5 file
(pennyShapedToughnessDominated_output.hdf5). This TimeHistory file contains the collected time history in-
formation from specified time history collector. This file includes datasets for the simulation time, fluid pressure, ele-
ment aperture, hydraulic aperture and element area for the propagating hydraulic fracture. A Python script is prepared
to read and query any specified subset of the time history data for verification and visualization.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial values: the waterDensity, separableFace and the ruptureState of the propagating fracture
have to be initialized,
• The boundary conditions: fluid injection rates and the constraints of the outer boundaries have to be set.
In this example, a mass injection rate SourceFlux (scale="-6.625") is applied at the surfaces of the initial fracture.
Only one fourth of the total injection rate is defined in this boundary condition because only a quarter of the fracture is
modeled (the problem is symmetric). The value given for scale is 𝑄0 𝜌𝑓 /4 (not 𝑄0 /4). All the outer boundaries are
subject to roller constraints. These boundary conditions are set through the FieldSpecifications section.

1.4. Advanced Examples 201

GEOS Documentation

<SourceFlux
name="sourceTerm"
objectPath="ElementRegions/Fracture"
scale="-6.625"
(continues on next page)

202 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

setNames="{ source }"/>
</FieldSpecifications>

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [GPa] 20.0
𝐺 Shear Modulus [GPa] 12.0
𝐾𝐼𝐶 Rock Toughness [MPa.m1/2 ] 3.0
𝜇 Fluid Viscosity [Pa.s] 1.0x10-6
𝑄0 Injection Rate [m3 /s] 0.0265
𝑡𝑖𝑛𝑗 Injection Time [s] 400

Inspecting results

The following figure shows the distribution of 𝜎𝑧𝑧 at 𝑡 = 400𝑠 within the computational domain..

Fig. 1.31: Simulation result of 𝜎𝑧𝑧 at 𝑡 = 400𝑠

First, by running the query script

1.4. Advanced Examples 203

GEOS Documentation

python ./hydrofractureQueries.py pennyShapedToughnessDominated

the HDF5 output is postprocessed and temporal evolution of fracture characterisctics (fluid pressure and fracture width
at fluid inlet and fracure radius) are saved into a txt file model-results.txt, which can be used for verification and
visualization:

[[' time', ' pressure', ' aperture', ' length']]

2 8.207e+05 0.0004661 8.137
4 6.799e+05 0.0005258 10.59
6 7.082e+05 0.0006183 11.94
8 6.07e+05 0.0006163 13.73
10 6.32e+05 0.0006827 14.45

Note: GEOS python tools geosx_xml_tools should be installed to run the query script (See Python Tools Setup for
details).
Next, the figure below compares the asymptotic solutions (curves) and the GEOS simulation results (markers) for this
analysis, which is generated using the visualization script:

python ./pennyShapedToughnessDominatedFigure.py

The time history plots of fracture radius, fracture aperture and fluid pressure at the point source match the asymptotic
solutions, confirming the accuracy of GEOS simulations.

2.0
Fracture Mouth Opening (mm)

60
Fracture Half Length (m)

50 1.5
40
1.0
30
20 0.5
Asymptotic ( => 0, CL => 0 )
10 GEOSX ( => 0, CL => 0 )
100 200 300 400 0.0 100 200 300 400
Time (s) Time (s)
1.50
Net Pressure at Well (MPa)

1.25
1.00
0.75
0.50
0.25
0.00 100 200 300 400
Time (s)

204 Chapter 1. Table of Contents

GEOS Documentation

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Viscosity-Storage-Dominated Penny Shaped Hydraulic Fracture

Context
In this example, we simulate the propagation of a radial hydraulic fracture in viscosity-storage-dominated regime,
another classic benchmark in hydraulic fracturing (Settgast et al., 2016). The fracture develops as a planar fracture
with an elliptical cross-section perpendicular to the fracture plane and a circular fracture tip. Unlike the toughness-
storage-dominated fractures, fluid frictional loss during the transport of viscous fracturing fluids governs the growth
of viscosity-storage-dominated fractures. We solve this problem using the hydrofracture solver in GEOS. We simulate
the change in length, aperture, and pressure of the fracture, and compare them against the corresponding analytical
solutions (Savitski and Detournay, 2002).
Input file
This example uses no external input files. Everything we need is contained within two GEOS input files:

inputFiles/hydraulicFracturing/pennyShapedViscosityDominated_base.xml

inputFiles/hydraulicFracturing/pennyShapedViscosityDominated_benchmark.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

inputFiles/hydraulicFracturing/scripts/hydrofractureQueries.py

inputFiles/hydraulicFracturing/scripts/hydrofractureFigure.py

Description of the case

We model a radial fracture emerging from a point source and forming a perfect circular shape in an infinite, isotropic,
and homogenous elastic domain. As with the viscosity-dominated KGD problem, we restrict the model to a radial frac-
ture developed in a viscosity-storage-dominated propagation regime. For viscosity-dominated fractures, more energy
is applied to move the fracturing fluid than to split the intact rock. If we neglect fluid leak-off, the storage-dominated
propagation
√ occurs from most of the injected fluid confined within the opened surfaces. We use a low rock toughness
(0.3𝑀 𝑃 𝑎 𝑚), and the slickwater we inject has a constant viscosity value (1.0𝑐𝑝) and zero compressibility. In addi-
tion, we assume that the fracture surfaces are impermeable, thus eliminating fluid leak-off. With this configuration, our
GEOS simulations meet the requirements of the viscosity-storage-dominated assumptions.
The fluid injected in the fracture follows the lubrication equation resulting from mass conservation and Poiseuille’s
law. The fracture propagates by creating new surfaces if the stress intensity factor exceeds the local rock toughness
𝐾𝐼𝐶 . By symmetry, the simulation is reduced to a quarter-scale to save computational cost. For verification purposes,
a plane strain deformation is considered in the numerical model.
We set up and solve a hydraulic fracture model to obtain the evolution with time of the fracture radius 𝑅, the net
pressure 𝑝0 and the fracture aperture 𝑤0 at the injection point for the penny-shaped fracture developed in viscosity-
storage-dominated regime. Savitski and Detournay (2002) presented the corresponding asymptotic solutions, used here
to validate the results of our GEOS simulations:
𝐸𝑝 𝑄30 𝑡4 1/9
𝑅(𝑡) = 0.6955( )
𝑀𝑝
𝑀𝑝2 𝑄30 𝑡 1/9
𝑤0 (𝑡) = 1.1977( )
𝐸𝑝2

1.4. Advanced Examples 205

GEOS Documentation

𝐸𝑝2 𝑀𝑝 1/3
𝑝0 (Π, 𝑡) = Π𝑚𝑜 (𝜉)( )
𝑡
where the plane modulus 𝐸𝑝 is related to Young’s modulus 𝐸 and Poisson’s ratio 𝜈:
𝐸
𝐸𝑝 =
1 − 𝜈2
The term 𝑀𝑝 is proportional to the fluid viscosity 𝜇:

𝑀𝑝 = 12𝜇

The viscosity scaling function Π𝑚𝑜 is given as:

2 𝜉
Π𝑚𝑜 (𝜉) = 𝐴1 [2.479 − ] − 𝐵[ln( ) + 1]
3(1 − 𝜉)1/3 2
with 𝐴1 = 0.3581, 𝐵 = 0.09269, 𝑐1 = 0.6846, 𝑐2 = 0.07098, and 𝜉 = 𝑟/𝑅(𝑡) denoting a dimensionless radial
coordinate along the fracture.
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used in this problem.

Fig. 1.32: Generated mesh

206 Chapter 1. Table of Contents

GEOS Documentation

Note that the domain size in the direction perpendicular to the fracture plane, i.e. z-axis, must be at least ten times of
the final fracture radius to minimize possible boundary effects.

The fracture plane is defined by a nodeset occupying a small region within the computation domain, where the fracture
tends to open and propagate upon fluid injection:

Solid mechanics solver

• Rock and fracture deformation are modeled by the solid mechanics solver SolidMechanicsLagrangianSSLE.

1.4. Advanced Examples 207

GEOS Documentation

In this solver, we define targetRegions that includes both the continuum region and the fracture region. The
name of the contact constitutive behavior is specified in this solver by the contactRelationName.
<SolidMechanicsLagrangianSSLE
name="lagsolve"
timeIntegrationOption="QuasiStatic"
logLevel="1"
discretization="FE1"
targetRegions="{ Domain, Fracture }"
contactRelationName="fractureContact"
contactPenaltyStiffness="1.0e0">
<NonlinearSolverParameters
newtonTol="1.0e-6"/>
<LinearSolverParameters
solverType="gmres"
krylovTol="1.0e-10"/>
</SolidMechanicsLagrangianSSLE>

• The single-phase fluid flow inside the fracture is solved by the finite volume method in the solver
SinglePhaseFVM.
<SinglePhaseFVM
name="SinglePhaseFlow"
logLevel="1"
discretization="singlePhaseTPFA"
targetRegions="{ Fracture }">
<NonlinearSolverParameters
newtonTol="1.0e-5"
newtonMaxIter="10"/>
<LinearSolverParameters
solverType="gmres"
krylovTol="1.0e-12"/>
</SinglePhaseFVM>

• The solver SurfaceGenerator defines the fracture region and rock toughness rockToughness="0.3e6".
With nodeBasedSIF="1", a node-based Stress Intensity Factor (SIF) calculation is chosen for the fracture prop-
agation criterion.
<SurfaceGenerator
name="SurfaceGen"
targetRegions="{ Domain }"
nodeBasedSIF="1"
rockToughness="0.3e6"
mpiCommOrder="1"/>

Constitutive laws

For this problem, a homogeneous and isotropic domain with one solid material is assumed. Its mechanical proper-
ties and associated fluid rheology are specified in the Constitutive section. The ElasticIsotropic model is
used to describe the mechanical behavior of rock when subjected to fluid injection. The single-phase fluid model
CompressibleSinglePhaseFluid is selected to simulate the response of water upon fracture propagation.

<Constitutive>
<CompressibleSinglePhaseFluid
(continues on next page)

208 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="water"
defaultDensity="1000"
defaultViscosity="0.001"
referencePressure="0.0"
compressibility="5e-12"
referenceViscosity="1.0e-3"
viscosibility="0.0"/>

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, pressureCollection,
apertureCollection, hydraulicApertureCollection and areaCollection are specified to output the time
history of fracture characterisctics (pressure, width and area). objectPath="ElementRegions/Fracture/
FractureSubRegion" indicates that these PackCollection tasks are applied to the fracure element subregion.

1.4. Advanced Examples 209

GEOS Documentation

These tasks are triggered using the Event manager with a PeriodicEvent defined for the recurring tasks.
GEOS writes one file named after the string defined in the filename keyword and formatted as a HDF5 file
(pennyShapedViscosityDominated_output.hdf5). This TimeHistory file contains the collected time history in-
formation from specified time history collector. This file includes datasets for the simulation time, fluid pressure, ele-
ment aperture, hydraulic aperture and element area for the propagating hydraulic fracture. A Python script is prepared
to read and query any specified subset of the time history data for verification and visualization.

Initial and boundary conditions

Next, we specify initial and boundary conditions:

• Initial values: the waterDensity, separableFace and the ruptureState of the propagating fracture have to
be initialized,
• Boundary conditions: fluid injection rates and the constraints of the outer boundaries have to be set.
In this example, a mass injection rate SourceFlux (scale="-6.625") is applied at the surfaces of the initial fracture.
Only one fourth of the total injection rate is defined in this boundary condition because only a quarter of the fracture is
modeled (the problem is symmetric). The value given for scale is 𝑄0 𝜌𝑓 /4 (not 𝑄0 /4). All the outer boundaries are
subject to roller constraints. These boundary conditions are set through the FieldSpecifications section.

210 Chapter 1. Table of Contents

GEOS Documentation

<SourceFlux
name="sourceTerm"
objectPath="ElementRegions/Fracture"
scale="-6.625"
(continues on next page)

1.4. Advanced Examples 211

GEOS Documentation

(continued from previous page)

setNames="{ source }"/>
</FieldSpecifications>

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [GPa] 20.0
𝐺 Shear Modulus [GPa] 12.0
𝐾𝐼𝐶 Rock Toughness [MPa.m1/2 ] 0.3
𝜇 Fluid Viscosity [Pa.s] 1.0x10-3
𝑄0 Injection Rate [m3 /s] 0.0265
𝑡𝑖𝑛𝑗 Injection Time [s] 400

Inspecting results

The following figure shows the distribution of 𝜎𝑧𝑧 at 𝑡 = 400𝑠 within the computational domain..

Fig. 1.33: Simulation result of 𝜎𝑧𝑧 at 𝑡 = 400𝑠

First, by running the query script

212 Chapter 1. Table of Contents

GEOS Documentation

python ./hydrofractureQueries.py pennyShapedViscosityDominated

[[' time', ' pressure', ' aperture', ' length']]

2 1.654e+06 0.0006768 8.137
4 1.297e+06 0.000743 10.59
6 1.115e+06 0.0007734 12.36
8 1.005e+06 0.0007918 13.73
10 9.482e+05 0.0008189 15.14

Note: GEOS python tools geosx_xml_tools should be installed to run the query script (See Python Tools Setup for
details).
Next, GEOS simulation results (markers) and asymptotic solutions (curves) for the case with viscosity-storage domi-
nated assumptions are plotted together in the following figure, which is generated using the visualization script:

python ./pennyShapedViscosityDominatedFigure.py

As seen, GEOS predictions of the temporal evolution of fracture radius, wellbore aperture and pressure at fluid inlet
are nearly identical to the asymptotic solutions.

2.0
Fracture Mouth Opening (mm)
Fracture Half Length (m)

60 1.5

40 1.0

20 0.5
Asymptotic ( KIC => 0, CL => 0 )
GEOSX ( KIC => 0, CL => 0 )
100 200 300 400 0.0 100 200 300 400
Time (s) Time (s)
1.50
Net Pressure at Well (MPa)

1.25
1.00
0.75
0.50
0.25
0.00 100 200 300 400
Time (s)

1.4. Advanced Examples 213

GEOS Documentation

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Viscosity-Storage-Dominated PKN Hydraulic Fracture

Context
In this example, we simulate the propagation of a Perkins–Kern–Nordgren (PKN) fracture in a viscosity-storage-
dominated regime, a classic benchmark in hydraulic fracturing. The developed planar fracture displays an elliptical
vertical cross-section. Unlike KGD and penny-shaped fractures, the growth height of a PKN fracture is constrained
by mechanical barriers (such as bedding layers, sedimentary laminations, or weak interfaces), thus promoting lateral
propagation. This problem is solved using the hydrofracture solver in GEOS to obtain the temporal evolutions of the
fracture characteristics (length, aperture, and pressure). We validate these simulated values against existing analytical
solutions (Kovalyshen and Detournay, 2010; Economides and Nolte, 2000).
Input file
This example uses no external input files. Everything we need is contained within two GEOS input files:

inputFiles/hydraulicFracturing/pknViscosityDominated_base.xml

inputFiles/hydraulicFracturing/pknViscosityDominated_benchmark.xml

Python scripts for post-processing and visualizing the simulation results are also prepared:

inputFiles/hydraulicFracturing/scripts/hydrofractureQueries.py

inputFiles/hydraulicFracturing/scripts/hydrofractureFigure.py

Description of the case

In this example, a hydraulic fracture initiates and propagates from the center of a 20m-thick layer. This layer is ho-
mogeneous and bounded by neighboring upper and lower layers. For viscosity-dominated fractures, more energy is
necessary to move the fracturing fluid than to split the intact rock. If fluid leak-off is neglected, storage-dominated
propagation occurs with most of the injected fluid confined within the open surfaces. To meet the requirements of the
viscosity-storage-dominated assumptions, impermeable domain √ (no fluid leak-off), incompressible fluid with constant
viscosity (1.0𝑐𝑝) and ultra-low rock toughness (0.1𝑀 𝑃 𝑎 𝑚) are chosen in the GEOS simulation. With these param-
eters, the fracture stays within the target layer; it extends horizontally and meets the conditions of the PKN fracture in
a viscosity-storage-dominated regime.
We assume that the fluid injected in the fracture follows the lubrication equation resulting from mass conservation and
Poiseuille’s law. The fracture propagates by creating new surfaces if the stress intensity factor exceeds the local rock
toughness 𝐾𝐼𝐶 . As the geometry of the PKN fracture exhibits symmetry, the simulation is reduced to a quarter-scale.
For verification purposes, a plane strain deformation is considered in the numerical model.
We set up and solve a hydraulic fracture model to obtain the temporal solutions of the fracture half length 𝑙, the net pres-
sure 𝑝0 and the fracture aperture 𝑤0 at the fluid inlet for the PKN fracture propagating in viscosity-storage-dominated
regime. Kovalyshen and Detournay (2010) and Economides and Nolte (2000) derived the analytical solutions for this
classic hydraulic fracture problem, used here to verify the results of the GEOS simulations:
𝐸𝑝 𝑄30 𝑡4 1/5
𝑙(𝑡) = 0.3817( )
𝜇ℎ4
𝜇𝑄0 𝑙 1/4
𝑤0 (𝑡) = 3( )
𝐸𝑝

214 Chapter 1. Table of Contents

GEOS Documentation

16𝜇𝑄0 𝐸𝑝3 𝑙 1/4

𝑝0 (𝑡) = ( )
𝜋ℎ4
where the plane modulus 𝐸𝑝 is related to Young’s modulus 𝐸 and Poisson’s ratio 𝜈:
𝐸
𝐸𝑝 =
1 − 𝜈2
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used in this problem.

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, pressureCollection,
apertureCollection, hydraulicApertureCollection and areaCollection are specified to output the time
history of fracture characterisctics (pressure, width and area). objectPath="ElementRegions/Fracture/
FractureSubRegion" indicates that these PackCollection tasks are applied to the fracure element subregion.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [GPa] 20.0
𝐺 Shear Modulus [GPa] 12.0
𝐾𝐼𝐶 Rock Toughness [MPa.m1/2 ] 0.1
𝜇 Fluid Viscosity [Pa.s] 1.0x10-3
𝑄0 Injection Rate [m3 /s] 0.0265
𝑡𝑖𝑛𝑗 Injection Time [s] 200
ℎ𝑓 Fracture Height [m] 20

Inspecting results

The following figure shows the distribution of 𝜎𝑧𝑧 at 𝑡 = 200𝑠 within the computational domain..

Fig. 1.35: Simulation result of 𝜎𝑧𝑧 at 𝑡 = 200𝑠

First, by running the query script

python ./hydrofractureQueries.py pknViscosityDominated

1.4. Advanced Examples 221

GEOS Documentation

[[' time', ' pressure', ' aperture', ' length']]

2 1.413e+06 0.0006093 5.6
4 1.174e+06 0.0007132 8.4
6 1.077e+06 0.0007849 10.8
8 1.044e+06 0.0008482 12.8
10 1.047e+06 0.0009098 14.8

Note: GEOS python tools geosx_xml_tools should be installed to run the query script (See Python Tools Setup for
details).
Next, figure below shows the comparisons between the results from GEOS simulations (markers) and the corresponding
analytical solutions (curves) for the example with viscosity-storage dominated assumptions, which is generated using
the visualization script:

python ./pknViscosityDominatedFigure.py

The evolution in time of the fracture half-length, the near-wellbore fracture aperture, and the fluid pressure all correlate
well with the analytical solutions.

2.0
Fracture Mouth Opening (mm)
Fracture Half Length (m)

125
100 1.5

75 1.0
50
0.5
25 Asymptotic ( KIC => 0, CL => 0 )
GEOSX ( KIC => 0, CL => 0 )
0
50 100 150 200 0.0 50 100 150 200
Time (s) Time (s)
1.50
Net Pressure at Well (MPa)

1.25
1.00
0.75
0.50
0.25
0.00 50 100 150 200
Time (s)

222 Chapter 1. Table of Contents

GEOS Documentation

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Proppant Slot Test

Context
In this example, a simulation is built up to model a proppant slot test. In this way, the implemented proppant model
is validated by comparing numerical results with the corresponding experimental data. Furthermore, this calibrated
proppant model can allow field engineers to customize stimulation design and optimize field operations in multiple
engineering aspects (Huang et al., 2021).
Input file
This example uses no external input files and everything is contained within a single xml file that is located at:

inputFiles/proppant/ProppantSlotTest_base.xml

inputFiles/proppant/ProppantSlotTest_benchmark.xml

Description of the case

Chun et al. (2020) conducted slot tests on proppant transport with slickwater. As shown below, a 4 ft X 1 ft slot with
0.3 in gap width was constructed. Three fluid inlets with 0.5 in inner diameter were placed at the right side of the slot,
which were three inches away from each other. One outlet was placed on the top side to allow pressure relief. The other
one was located on the left side acting as a fluid sink. In their tests, to resemble a slickwater fracturing treatment, the
proppant concentration was kept at 1.5 ppg and the viscosity of carrying fluid was approximately 1 cp. The slurry was
mixed well and then injected into the flow channel at a constant injection rate of 6 gpm. A simulation case with the
same settings is built up to mimic these slot tests. A vertical and impermeable fracture surface is assumed in this case,
which eliminates the effect of fracture plane inclination and fluid leak-off. A static fracture with an uniform aperture
of 0.3 in is defined and fracture propagation is not involved. 30/50 mesh proppant is injected via the three inlets and is
flowed through the slot for 30 seconds.
To simulate proppant transport phenomenon, a proppant solver based on the assumption of multi-component single
phase flow is used in this example. Proppant concentration and distribution within the slot are numerically calculated
by solving the equations of proppant transport in hydraulic fractures. These numerical predictions are then validated
against the corresponding testing results (Chun et al., 2020).
In this example, we focus our attention on the Solvers, Constitutive and FieldSpecifications tags.

Mesh

The following figure shows the mesh used for solving this problem.
We use the internal mesh generator InternalMesh to create a computational domain. This mesh contains 2 x 97 x
24 eight-node brick elements in the x, y and z directions, respectively. Here, a structured three-dimensional mesh is
generated with C3D8 as the elementTypes (eight-node hexahedral elements). This mesh is defined as a cell block with
the name cb1.

<Mesh>
<InternalMesh
name="mesh"
elementTypes="{ C3D8 }"
(continues on next page)

1.4. Advanced Examples 223

GEOS Documentation

Fig. 1.36: Configuration of the slot for proppant transport experiment (after Chun et al., 2020)

Fig. 1.37: Mesh for simulating the proppant slot tests.

224 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

xCoords="{ -1, 1 }"
yCoords="{ 0, 1.2319 }"
zCoords="{ 0, 0.3048 }"
nx="{ 2 }"
ny="{ 97 }"
nz="{ 24 }"
cellBlockNames="{ cb1 }"/>
</Mesh>

Proppant transport solver

GEOS is a multi-physics platform. Different combinations of physics solvers available in the code can be applied in
different regions of the domain and be functional at different stages of the simulation. The Solvers tag in the XML
file is used to define these solvers.
To specify a coupling between two different solvers, we define and characterize each single-physics solver separately.
Then, we customize a coupling solver between these single-physics solvers as an additional solver. This approach
allows for generality and flexibility in constructing multi-physics solvers. The order of specifying these solvers is not
restricted in GEOS. Note that end-users should give each single-physics solver a meaningful and distinct name, as
GEOS will recognize these single-physics solvers based on their customized names and create user-expected coupling.
As demonstrated in this example, to setup a coupled proppant transport solver, we need to define three different solvers
in the XML file:
• the proppant transport solver for the fracture region, a solver of type ProppantTransport called here
ProppantTransport (see Proppant Transport Solver for more information),

• the single-phase flow solver, a solver of type SinglePhaseProppantFVM called here SinglePhaseFVM,

<SinglePhaseProppantFVM
name="SinglePhaseFVM"
logLevel="1"
discretization="singlePhaseTPFA"
(continues on next page)

1.4. Advanced Examples 225

GEOS Documentation

(continued from previous page)

targetRegions="{ Fracture }">
<NonlinearSolverParameters
newtonTol="1.0e-6"
newtonMaxIter="8"
lineSearchAction="None"
newtonMinIter="0"/>
<LinearSolverParameters
solverType="gmres"
preconditionerType="amg"
krylovTol="1.0e-7"/>
</SinglePhaseProppantFVM>

• the coupling solver (FlowProppantTransport) that binds the two single-physics solvers above, which is named
as FlowProppantTransport

In this example, let us focus on the coupling solver. This solver (FlowProppantTransport) describes the coupling
process between proppant and flow transport within the Fracture region. In this way, the two single-physics solvers
(ProppantTransport and SinglePhaseFVM) are sequentially called to solve the sub-problems (proppant transport
and pressure problem, respectively) involved in this test case.

Constitutive laws

For this slot test, 30/50 mesh proppant is injected via the three inlets and flowing through the slot for 30 seconds.
The viscosity of carrying fluid is 0.001 Pa.s to resemble slickwater fracturing. In this example, the solid and fluid
materials are named as sand and water respectively. Proppant characterization and fluid rheology are specified in the
Constitutive section:

(continues on next page)

226 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

The constitutive parameters such as proppant density and proppant diameter are specified in the International System
of Units.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (fracture aperture, fluid pressure and proppant concentration within the fracture have to be
initialized)
• The boundary conditions (fluid pressure and proppant concentration at fluid inlets and outlets)
These boundary conditions are set up through the FieldSpecifications section. At a constant injection rate, the
slurry is equally flowing into the open channel through three inlets.
<FieldSpecifications>
<FieldSpecification
name="frac"
initialCondition="1"
setNames="{ fracture }"
objectPath="faceManager"
fieldName="ruptureState"
scale="1"/>

<FieldSpecification
name="frac1"
(continues on next page)

1.4. Advanced Examples 227

GEOS Documentation

(continued from previous page)

initialCondition="1"
objectPath="ElementRegions/Fracture"
fieldName="pressure"
scale="0.0"
component="0"
setNames="{ fracture }"/>

<SourceFlux
name="left2a"
objectPath="ElementRegions/Fracture"
scale="-0.14"
(continues on next page)

228 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

component="0"
setNames="{ left2 }"/>

Note: For static (non-propagating) fracture problems, the fields ruptureState and elementAperture should be
provided in the initial conditions. FieldName="pressure" here means that the source flux term is added to the mass
balance equation for pressure.
The parameters used in the simulation are summarized in the following table.

1.4. Advanced Examples 229

GEOS Documentation

Symbol Parameter Unit Value

𝑑𝑝 Proppant Diameter [m] 0.00045
𝑓 Darcy Friction Coefficient [-] 0.04
𝑁𝑠ℎ Critical Shields Number [-] 0.0
𝑐𝑠 Max Fraction of Proppant [-] 0.62
𝜌𝑓 Fluid Density [kg/m^3] 1000
𝜇𝑓 Fluid Viscosity [Pa*s] 0.001
𝜌𝑝 Proppant Density [kg/m^3] 2550
𝜆𝑠 Hindered Settling Coefficient [-] 4.5
𝑐𝑝 Proppant Concentration in Slurry [m^3/m^3] 0.07
𝐿 Fracture Length [m] 1.219
𝐻 Fracture Height [m] 0.3048
𝑎 Fracture Aperture [m] 0.00762
𝑄 Injection Rate [m^3/s] 0.0003785

Inspecting results

The following figure shows the modelling prediction of proppant distribution at 10 s and 30 s, which are compared
with the experiments in (Chun et al., 2020). Due to proppant settling in low viscosity fluid, a heterogeneous proppant
distribution is obtained, which evolves with injection time. Three different zones (immobile proppant bed, suspended
proppant and clean fluid) are visually identified for both the presented experiment and simulation.

Fig. 1.38: Proppant distribution profile

As shown below, consistently, the modelling predictions (green curve) on proppant transport and distribution show a
good agreement with the reported experimental data (red dot) at each time.

To go further

Feedback on this example

This concludes the example on simulating a proppant slot test. For any feedback on this example, please submit a
GitHub issue on the project’s GitHub page.
For more details
• More on proppant solver, please see Proppant Transport Solver.

230 Chapter 1. Table of Contents

GEOS Documentation

1.2 0.5
Normalized Bank Length (a) (b)
1.0

Normalized Bank Area

0.4
0.8
0.3
0.6
0.2
0.4
0.2 Experiment-30/50 0.1 Experiment-30/50
GEOSX-30/50 mesh GEOSX-30/50 mesh
0.0 0.0
0 5 10 15 20 25 30 35 40 0 5 10 15 20 25 30 35 40
Normalized Suspended Proppant Area

Time (s) Time (s)

0.6 1.0
(c) (d)

Normalized Total Propped Area

Experiment-30/50 Experiment-30/50
0.5 GEOSX-30/50 mesh 0.8 GEOSX-30/50 mesh
0.4
0.6
0.3
0.4
0.2
0.1 0.2

0.0 0.0
0 5 10 15 20 25 30 35 40 0 5 10 15 20 25 30 35 40
Time (s) Time (s)

Wellbore Problems
Kirsch Wellbore Problem

Context
In this example, we simulate a vertical elastic wellbore subjected to in-situ stress and the induced elastic deformation
of the reservoir rock. Kirsch’s solution to this problem provides the stress and displacement fields developing around
a circular cavity, which is hereby employed to verify the accuracy of the numerical results. For this example, the
TimeHistory function and python scripts are used to output and post-process multi-dimensional data (stress and
displacement).
Input file
Everything required is contained within two GEOS input files located at:

inputFiles/solidMechanics/KirschProblem_base.xml

inputFiles/solidMechanics/KirschProblem_benchmark.xml

Description of the case

We solve a drained wellbore problem subjected to anisotropic horizontal stress (𝜎𝑥𝑥 and 𝜎𝑦𝑦 ) as shown below. This
is a vertical wellbore drilled in an infinite, homogeneous, isotropic, and elastic medium. Far-field in-situ stresses and
internal supporting pressure acting at the circular cavity cause a mechanical deformation of the reservoir rock and
stress concentration in the near-wellbore region. For verification purpose, a plane strain condition is considered for the
numerical model.

1.4. Advanced Examples 231

GEOS Documentation

Fig. 1.39: Sketch of the wellbore problem

In this example, stress (𝜎𝑟𝑟 , 𝜎𝜃𝜃 , and 𝜎𝑟𝜃 ) and displacement (𝑢𝑟 and 𝑢𝜃 ) fields around the wellbore are calculated
numerically. These numerical predictions are compared with the corresponding Kirsch solutions (Poulos and Davis,
1974).
𝜎𝑥𝑥 + 𝜎𝑦𝑦 𝑎0 𝜎𝑥𝑥 − 𝜎𝑦𝑦 𝑎0 𝑎0 𝑎0
𝜎𝑟𝑟 = [1 − ( )2 ] + [1 − 4( )2 + 3( )4 ]cos (2𝜃) + 𝑃𝑤 ( )2
2 𝑟 2 𝑟 𝑟 𝑟
𝜎𝑥𝑥 + 𝜎𝑦𝑦 𝑎0 2 𝜎𝑥𝑥 − 𝜎𝑦𝑦 𝑎0 4 𝑎0 2
𝜎𝜃𝜃 = [1 + ( ) ] − [1 + 3( ) ]cos (2𝜃) − 𝑃𝑤 ( )
2 𝑟 2 𝑟 𝑟
𝜎𝑥𝑥 − 𝜎𝑦𝑦 𝑎0 2 𝑎0 4
𝜎𝑟𝜃 = − [1 + 2( ) − 3( ) ]sin (2𝜃)
2 𝑟 𝑟
(𝑎0 )2 𝜎𝑥𝑥 + 𝜎𝑦𝑦 𝜎𝑥𝑥 − 𝜎𝑦𝑦 𝑎0
𝑢𝑟 = − [ + (4(1 − 𝜈) − ( )2 )cos (2𝜃) − 𝑃𝑤 ]
2𝐺𝑟 2 2 𝑟
(𝑎0 )2 𝜎𝑥𝑥 − 𝜎𝑦𝑦 𝑎0 2
𝑢𝜃 = [2(1 − 2𝜈) + ( ) ]sin (2𝜃)
2𝐺𝑟 2 𝑟
where 𝑎0 is the intiial wellbore radius, 𝑟 is the radial coordinate, 𝜈 is the Poisson’s ratio, 𝐺 is the shear modulus, 𝑃𝑤
is the normal traction acting on the wellbore wall, the angle 𝜃 is measured with respect to x-z plane and defined as
positive in counter-clockwise direction.
In this example, we focus our attention on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

Following figure shows the generated mesh that is used for solving this wellbore problem.
Let us take a closer look at the geometry of this wellbore problem. We use the internal wellbore mesh generator
InternalWellbore to create a rock domain (10 𝑚 × 5 𝑚 × 2 𝑚), with a wellbore of initial radius equal to 0.1
m. Only half of the domain is modeled by a theta angle from 0 to 180, assuming symmetry for the rest of the
domain. Coordinates of trajectory defines the wellbore trajectory, a vertical well in this example. By turning on
autoSpaceRadialElems="{ 1 }", the internal mesh generator automatically sets number and spacing of elements in
the radial direction, which overrides the values of nr. With useCartesianOuterBoundary="0", a Cartesian aligned
boundary condition is enforced on the outer blocks. This way, a structured three-dimensional mesh is created with 50 x
40 x 2 elements in the radial, tangential and z directions, respectively. All elements are eight-node hexahedral elements
(C3D8) and refinement is performed to conform with the wellbore geometry. This mesh is defined as a cell block with
the name cb1.

232 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.40: Generated mesh for a vertical wellbore problem

Solid mechanics solver

For a drained wellbore problem, the pore pressure variation is omitted. Therefore, we just need to define a solid
mechanics solver, which is called mechanicsSolver. This solid mechanics solver (see Solid Mechanics Solver) is
based on the Lagrangian finite element formulation. The problem is run as QuasiStatic without considering inertial
effects. The computational domain is discretized by FE1, which is defined in the NumericalMethods section. The
material is named rock, whose mechanical properties are specified in the Constitutive section.

<Solvers gravityVector="{0.0, 0.0, 0.0}">

<SolidMechanics_LagrangianFEM
name="mechanicsSolver"
timeIntegrationOption="QuasiStatic"
(continues on next page)

1.4. Advanced Examples 233

GEOS Documentation

(continued from previous page)

logLevel="1"
discretization="FE1"
targetRegions="{Omega}">
<NonlinearSolverParameters
newtonTol = "1.0e-5"
newtonMaxIter = "15"
/>
<LinearSolverParameters
directParallel="0"/>
</SolidMechanics_LagrangianFEM>
</Solvers>

Constitutive laws

For this drained wellbore problem, we simulate a linear elastic deformation around the circular cavity. A homogeneous
and isotropic domain with one solid material is assumed, with mechanical properties specified in the Constitutive
section:

Recall that in the SolidMechanics_LagrangianFEM section, rock is the material in the computational domain. Here,
the isotropic elastic model ElasticIsotropic simulates the mechanical behavior of rock.
The constitutive parameters such as the density, the bulk modulus, and the shear modulus are specified in the Interna-
tional System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, stressCollection and
displacementCollection tasks are specified to output the resultant stresses (tensor stored as an array with Voigt
notation) and total displacement field (stored as a 3-component vector) respectively.

These two tasks are triggered using the Event management, where PeriodicEvent are defined for these recurring

234 Chapter 1. Table of Contents

GEOS Documentation

tasks. GEOS writes two files named after the string defined in the filename keyword and formatted as HDF5 files
(displacement_history.hdf5 and stress_history.hdf5). The TimeHistory file contains the collected time history infor-
mation from each specified time history collector. This information includes datasets for the simulation time, element
center or nodal position, and the time history information. Then, a Python script is prepared to access and plot any
specified subset of the time history data for verification and visualization.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (the in-situ stresses and traction at the wellbore wall have to be initialized),
• The boundary conditions (constraints of the outer boundaries have to be set).
Here, we specify anisotropic horizontal stress values (𝜎𝑦𝑦 = -9.0 MPa and 𝜎𝑥𝑥 = -11.25 MPa) and a vertical stress
(𝜎𝑧𝑧 = -15.0 MPa). A compressive traction (WellLoad) 𝑃𝑤 = -2.0 MPa is loaded at the wellbore wall rneg. The
remaining parts of the outer boundaries are subjected to roller constraints. These boundary conditions are set in the
FieldSpecifications section.

<Traction
name="WellLoad"
setNames="{ rneg }"
objectPath="faceManager"
scale="-2.0e6"
(continues on next page)

1.4. Advanced Examples 235

GEOS Documentation

(continued from previous page)

tractionType="normal"
/>

With tractionType="normal", traction is applied to the wellbore wall rneg as a pressure specified as the scalar
product of scale scale="-2.0e6" and the outward face normal vector. In this case, the loading magnitude of the
traction does not change with time.
You may note :
• All initial value fields must have initialCondition field set to 1;
• The setName field points to the previously defined set to apply the fields;
• nodeManager and faceManager in the objectPath indicate that the boundary conditions are applied to the
element nodes and faces, respectively;
• fieldName is the name of the field registered in GEOS;
• Component 0, 1, and 2 refer to the x, y, and z direction, respectively;
• And the non-zero values given by scale indicate the magnitude of the loading;
• Some shorthand, such as xneg and xpos, are used as the locations where the boundary conditions are applied
in the computational domain. For instance, xneg means the face of the computational domain located at the
left-most extent in the x-axis, while xpos refers to the face located at the right-most extent in the x-axis. Similar
shorthands include ypos, yneg, zpos, and zneg;
• The mud pressure loading and in situ stresses have negative values due to the negative sign convention for com-
pressive stress in GEOS.

236 Chapter 1. Table of Contents

GEOS Documentation

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [MPa] 500.0
𝐺 Shear Modulus [MPa] 300.0
𝜎𝑦𝑦 Min Horizontal Stress [MPa] -9.0
𝜎𝑥𝑥 Max Horizontal Stress [MPa] -11.25
𝜎𝑧𝑧 Vertical Stress [MPa] -15.0
𝑎0 Initial Well Radius [m] 0.1
𝑃𝑤 Traction at Well [MPa] -2.0

Inspecting results

In the above examples, we request VTK output files that can be imported into Paraview to visualize the outcome. The
following figure shows the distribution of 𝜎𝑥𝑥 in the near wellbore region.

Fig. 1.41: Simulation result of 𝜎𝑥𝑥

We use time history function to collect time history information and run a Python script to query and plot the results.
The figure below shows the comparisons between the numerical predictions (marks) and the corresponding analytical
solutions (solid curves) with respect to the distributions of stress components and displacement at 𝜃 = 45 degrees.
Predictions computed by GEOS match the analytical results.

1.4. Advanced Examples 237

GEOS Documentation

0.0 0.25
2.5 0.00

Displacement (mm)
5.0 0.25
(MPa)

7.5
0.50
10.0
rr - Analytical 0.75
12.5 rr - GEOSX
15.0
- Analytical 1.00 ur - Analytical
- GEOSX ur - GEOSX
r - Analytical 1.25 u - Analytical
17.5 r - GEOSX u - GEOSX
10 1 100 10 1 100
r (m) r (m)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Cased Elastic Wellbore Problem

Problem description

This example uses the solid mechanics solver to handle a cased wellbore problem subjected to a pressure test. The com-
pleted wellbore is composed of a steel casing, a cement sheath and rock formation. Isotropic linear elastic behavior is
assumed for all the three materials. No separation is allowed for the casing-cement and cement-rock contact interfaces.
Analytical results of the radial and hoop stresses, 𝜎𝑟𝑟 and 𝜎𝜃𝜃 , in casing, cement sheath and rock are expressed as
(Hervé and Zaoui, 1995) :
2𝐺𝐵
𝜎𝑟𝑟 = (2𝜆 + 2𝐺)𝐴 −
𝑟2
2𝐺𝐵
𝜎𝜃𝜃 = (2𝜆 + 2𝐺)𝐴 +
𝑟2
where 𝜆 and 𝐺 are the Lamé moduli, 𝑟 is the radial coordinate, 𝐴 and 𝐵 are piecewise constants that are obtained by
solving the boundary and interface conditions, as detailed in the post-processing script.
Input file
This benchmark example uses no external input files and everything required is contained within two GEOS xml files
that are located at:

inputFiles/wellbore/CasedElasticWellbore_base.xml

and

inputFiles/wellbore/CasedElasticWellbore_benchmark.xml

The corresponding integrated test is

inputFiles/wellbore/CasedElasticWellbore_smoke.xml

In this example, we would focus our attention on the Solvers, Mesh and Constitutive tags.

238 Chapter 1. Table of Contents

Results and benchmark

A good agreement between the GEOS results and analytical results is shown in the figure below:

5.75
2.25 GEOSX result
Analytic
5.50
2.50
5.25
2.75
Radial stress (MPa)

Hoop stress (MPa)

5.00
3.00
4.75
3.25
4.50
3.50
4.25
3.75
4.00
4.00
0.110 0.115 0.120 0.125 0.130 0.110 0.115 0.120 0.125 0.130
r (m) r (m)

To go further

Feedback on this example

This concludes the cased wellbore example. For any feedback on this example, please submit a GitHub issue on the
project’s GitHub page.

Deviated Elastic Wellbore Problem

Problem description

This example uses the solid mechanics solver to handle a deviated wellbore problem with open hole completion. This
wellbore is subjected to a mud pressure at wellbore wall and undrained condition is assumed (no fluid flow in the
rock formation). A segment of the wellbore with isotropic linear elastic deformation is simulated in this case. Far
field stresses and gravity effect are excluded. The main goal of this example is to validate the internal wellbore mesh
generator and mechanics solver for the case of an inclined wellbore.
Analytical results of the radial and hoop stresses, 𝜎𝑟𝑟 and 𝜎𝜃𝜃 , around the wellbore are expressed as (Detournay and
Cheng, 1988) :

𝑎2
𝜎𝑟𝑟 = 𝑝0
𝑟2
𝑎2
𝜎𝜃𝜃 = −𝑝0
𝑟2
where 𝑝0 is the applied mud pressure at wellbore wall, 𝑎 is the wellbore radius and 𝑟 is the radial coordinate.
Input file
This benchmark example uses no external input files and everything required is contained within two GEOS xml files
that are located at:

242 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/wellbore/DeviatedElasticWellbore_base.xml

and

inputFiles/wellbore/DeviatedElasticWellbore_benchmark.xml

The corresponding xml file for the integrated test is

inputFiles/wellbore/DeviatedElasticWellbore_smoke.xml

In this example, we would focus our attention on the Mesh tag.

Solid mechanics solver

As fluid flow is not considered, only the solid mechanics solver SolidMechanicsLagrangianSSLE is required for
solving this wellbore problem.

Deviated wellbore mesh

The internal wellbore mesh generator InternalWellbore is employed to create the mesh of this wellbore problem.
The radius of the wellbore and the size of the surrounding rock formation are defined by a vector radius. In the tangent
direction, theta angle is specified from 0 to 180 degree for a half of the domain regarding its symmetry. Note that the
whole domain could be specified with a theta angle from 0 to 360 degree, if modeling complicated scenarios. The
trajectory of the well is defined by trajectory. In this example, the wellbore is inclined in the x-z plane by an angle
of 45 degree. The autoSpaceRadialElems parameter allows optimally increasing the element size from local zone
around the wellbore to the far-field zone, which is set to 1 to activate this option. The useCartesianOuterBoundary
transforms the far-field boundary to a squared shape to enforce a Cartesian aligned outer boundary, which eases the
loading of the far-field boundary conditions. In this example, this value is set to 0 for the single region along the radial
direction.

<Mesh>
<InternalWellbore
name="mesh1"
elementTypes="{ C3D8 }"
radius="{ 0.1, 2 }"
theta="{ 0, 180 }"
zCoords="{ -0.5, 0.5 }"
nr="{ 30 }"
nt="{ 80 }"
nz="{ 100 }"
trajectory="{ { -0.5, 0.0, -0.5 },
{ 0.5, 0.0, 0.5 } }"
autoSpaceRadialElems="{ 1 }"
useCartesianOuterBoundary="0"
(continues on next page)

1.4. Advanced Examples 243

GEOS Documentation

(continued from previous page)

cellBlockNames="{ cb1 }"/>
</Mesh>

Constitutive law

Isotropic linear elastic constitutive behavior is considered for the rock around the wellbore. Note that the default density
is useless in this specific example, as gravity effect is neglected.

Boundary conditions

Far-field boundaries are subjected to roller constraints and in-situ stresses are not considered. The mud pressure on
the wellbore wall is defined by Traction field specification. The nodeset generated by the internal wellbore generator
for this face is named as rneg. The traction type is normal to mimic a pressure that is applied normal to the wellbore
wall. The negative sign of the scale is attributed to the negative sign convention for compressive stresses in GEOS.

(continues on next page)

244 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Results and benchmark

A good agreement between the GEOS results and the corresponding analytical solutions is shown in the figure below:

To go further

Feedback on this example

This concludes the deviated elastic wellbore example. For any feedback on this example, please submit a GitHub issue
on the project’s GitHub page.

Extended Drucker-Prager Model for Wellbore Problems

Context
The main goal of this example is to learn how to use the internal wellbore mesh generator and an elasto-plastic model
to handle wellbore problems in GEOS. The Extended Drucker-Prager model (see Model: Extended Drucker-Prager)
is applied to solve for elastoplastic deformation within the vicinity of a vertical wellbore. For the presented example,
an analytical solution is employed to verify the accuracy of the numerical results. The resulting model can be used as
a base for more complex analysis (e.g., wellbore drilling, fluid injection and storage scenarios).
Objectives

1.4. Advanced Examples 245

GEOS Documentation

0 GEOSX result
10 Analytic

2 8

4 6
Radial stress (MPa)

Hoop stress (MPa)

6 4

8 2

10 0
0.100 0.125 0.150 0.175 0.200 0.225 0.250 0.275 0.300 0.100 0.125 0.150 0.175 0.200 0.225 0.250 0.275 0.300
r (m) r (m)

246 Chapter 1. Table of Contents

GEOS Documentation

At the end of this example you will know:

• how to construct meshes for wellbore problems with the internal mesh generator,
• how to specify initial and boundary conditions, such as in-situ stresses and variation of traction at the wellbore
wall,
• how to use a plastic model for mechanical problems in the near wellbore region.
Input file
This example uses no external input files and everything required is contained within two xml files that are located at:

inputFiles/solidMechanics/ExtendedDruckerPragerWellbore_base.xml

inputFiles/solidMechanics/ExtendedDruckerPragerWellbore_benchmark.xml

The Python scripts for post-processing GEOS results, analytical restuls and validation plots are also provided in this
example.

Description of the case

We simulate a drained wellbore problem subjected to isotropic horizontal stress (𝜎ℎ ) and vertical stress (𝜎𝑣 ). By
lowering the wellbore supporting pressure (𝑃𝑤 ), the wellbore contracts, and the reservoir rock experiences elastoplastic
deformation. A plastic zone develops in the near wellbore region, as shown below.

Fig. 1.42: Sketch of the wellbore problem (Chen and Abousleiman, 2017)

1.4. Advanced Examples 247

GEOS Documentation

To simulate this phenomenon, the strain hardening Extended Drucker-Prager model with an associated plastic flow rule
in GEOS is used in this example. Displacement and stress fields around the wellbore are numerically calculated. These
numerical predictions are then compared with the corresponding analytical solutions (Chen and Abousleiman, 2017)
from the literature.
All inputs for this case are contained inside a single XML file. In this example, we focus our attention on the Mesh
tags, the Constitutive tags, and the FieldSpecifications tags.

Mesh

Following figure shows the generated mesh that is used for solving this 3D wellbore problem

Fig. 1.43: Generated mesh for the wellbore problem

Let us take a closer look at the geometry of this wellbore problem. We use the internal mesh generator
InternalWellbore to create a rock domain (10 𝑚 × 10 𝑚 × 2 𝑚), with a wellbore of initial radius equal to 0.1
m. Coordinates of trajectory defines the wellbore trajectory, which represents a vertical well in this example. By
turning on autoSpaceRadialElems="{ 1 }", the internal mesh generator automatically sets number and spacing of
elements in the radial direction, which overrides the values of nr. In this way, a structured three-dimensional mesh is
created. All the elements are eight-node hexahedral elements (C3D8) and refinement is performed to conform with the
wellbore geometry. This mesh is defined as a cell block with the name cb1.

<Mesh>
<InternalWellbore
name="mesh1"
elementTypes="{ C3D8 }"
radius="{ 0.1, 10.0 }"
(continues on next page)

248 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

theta="{ 0, 90 }"
zCoords="{ -1, 1 }"
nr="{ 40 }"
nt="{ 40 }"
nz="{ 1 }"
trajectory="{ { 0.0, 0.0, -1.0 },
{ 0.0, 0.0, 1.0 } }"
autoSpaceRadialElems="{ 1 }"
cellBlockNames="{ cb1 }"/>
</Mesh>

Solid mechanics solver

For the drained wellbore problem, the pore pressure variation is omitted and can be subtracted from the analysis.
Therefore, we just need to define a solid mechanics solver, which is called mechanicsSolver. This solid mechanics
solver (see Solid Mechanics Solver) is based on the Lagrangian finite element formulation. The problem is run as
QuasiStatic without considering inertial effects. The computational domain is discretized by FE1, which is defined
in the NumericalMethods section. The material is named as rock, whose mechanical properties are specified in the
Constitutive section.

GEOS Documentation

Fig. 1.44: Validation of GEOS results.

1.4. Advanced Examples 253

GEOS Documentation

To go further

Feedback on this example

This concludes the example on Plasticity Model for Wellbore Problems. For any feedback on this example, please
submit a GitHub issue on the project’s GitHub page.
For more details
• More on plasticity models, please see Model: Extended Drucker-Prager.
• More on functions, please see Functions.

Drucker-Prager Model with Hardening for Wellbore Problems

Context
This is an alternative to the example Extended Drucker-Prager Model for Wellbore Problems, and the Drucker-Prager
constitutive with cohesion hardening (see Model: Drucker-Prager) is hereby considered. Analytical solutions to this
problem are not provided from literature work, however they can be derived following (Chen and Abousleiman 2017).
Details of those solutions are given in Python scripts associated to this example.
Input file
This example uses no external input files and everything required is contained within two xml files that are located at:

inputFiles/solidMechanics/DruckerPragerWellbore_base.xml

inputFiles/solidMechanics/DruckerPragerWellbore_benchmark.xml

The related integrated test is

inputFiles/solidMechanics/DruckerPragerWellbore_smoke.xml

The Drucker-Prager material properties are specified in the Constitutive section:

</Constitutive>

Here, rock is designated as the material in the computational domain. Drucker Prager model DruckerPrager
is used to simulate the elastoplastic behavior of rock. The material parameters, defaultFrictionAngle,
defaultDilationAngle and defaultCohesion denote the friction angle, the dilation angle, and the cohesion, re-
spectively. In this example, the hardening of the cohesion is described by a linear hardening law, which is governed by
the parameter defaultHardeningRate. The constitutive parameters such as the density, the bulk modulus, and the
shear modulus are specified in the International System of Units.
The parameters used in the simulation are summarized in the following table.

254 Chapter 1. Table of Contents

GEOS Documentation

Symbol Parameter Unit Value

𝐾 Bulk modulus [MPa] 500
𝐺 Shear Modulus [MPa] 300
𝑐 Cohesion [MPa] 0.1
𝜑 Friction Angle [degree] 15.27
𝜓 Dilation Angle [degree] 15.0
ℎ Hardening Rate [MPa] 10.0
𝜎ℎ Horizontal Stress [MPa] -11.25
𝜎𝑣 Vertical Stress [MPa] -15.0
𝑎0 Initial Well Radius [m] 0.1
𝑝𝑤 Mud Pressure [MPa] -2.0

For the drained wellbore problem, the pore pressure variation is omitted. Therefore, we just need to define a solid
mechanics solver, which is called mechanicsSolver. This solid mechanics solver (see Solid Mechanics Solver) is
based on the Lagrangian finite element formulation. The problem is run as QuasiStatic without considering inertial
effects. The computational domain is discretized by FE1, which is defined in the NumericalMethods section. The
material is named as rock, whose mechanical properties are specified in the Constitutive section.

Constitutive laws

For this drained wellbore problem, we simulate the elastoplastic deformation caused by wellbore expansion. A homo-
geneous domain with one solid material is assumed, whose mechanical properties are specified in the Constitutive
section:

Recall that in the SolidMechanics_LagrangianFEM section, rock is designated as the material in the computational
domain. Here, Modified Cam-Clay ModifiedCamClay is used to simulate the elastoplastic behavior of rock.
The following material parameters should be defined properly to reproduce the analytical example:

258 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ModifiedCamClay

Name Type De- Description

fault
defaultCslSlope real64 1 Slope of the critical state line
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLinearTEC real64 0 Default Linear Thermal Expansion Coefficient of the Solid
Rock Frame
defaultPreConsolidation- real64 -1.5 Initial preconsolidation pressure
Pressure
defaultRecompressionIn- real64 0.002 Recompresion Index
dex
defaultRefPressure real64 -1 Reference Pressure
defaultRefStrainVol real64 0 Reference Volumetric Strain
defaultShearModulus real64 -1 Elastic Shear Modulus Parameter
defaultVirginCompres- real64 0.005 Virgin compression index
sionIndex
name group- re- A name is required for any non-unique nodes
Name quired

The constitutive parameters such as the density, the bulk modulus, and the shear modulus are specified in the Interna-
tional System of Units.

Initial and boundary conditions

The next step is to specify fields, including:

<FieldSpecification
name="stressYY"
initialCondition="1"
setNames="{ all }"
(continues on next page)

1.4. Advanced Examples 259

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions"
fieldName="rock_stress"
component="1"
scale="-1.0e5"/>

With tractionType="normal", traction is applied to the wellbore wall rneg as a pressure specified from the product
of scale scale="-1.0e5" and the outward face normal. A table function timeFunction is used to define the time-
dependent traction ExternalLoad. The coordinates and values form a time-magnitude pair for the loading time
history. In this case, the loading magnitude increases linearly as the time evolves.

260 Chapter 1. Table of Contents

GEOS Documentation

You may note :

• All initial value fields must have initialCondition field set to 1;
• The setName field points to the previously defined set to apply the fields;
• nodeManager and faceManager in the objectPath indicate that the boundary conditions are applied to the
element nodes and faces, respectively;
• fieldName is the name of the field registered in GEOS;
• Component 0, 1, and 2 refer to the x, y, and z direction, respectively;
• And the non-zero values given by scale indicate the magnitude of the loading;
• Some shorthand, such as xneg and xpos, are used as the locations where the boundary conditions are applied
in the computational domain. For instance, xneg means the face of the computational domain located at the
left-most extent in the x-axis, while xpos refers to the face located at the right-most extent in the x-axis. Similar
shorthands include ypos, yneg, zpos, and zneg;
• The mud pressure loading has a negative value due to the negative sign convention for compressive stress in
GEOS.
The parameters used in the simulation are summarized in the following table.

Symbol Parameter Units Value

𝑃𝑟 Reference Pressure [kPa] 120
𝐺 Shear Modulus [kPa] 4302
𝑃𝑐 PreConsolidation Pressure [kPa] 169
𝑀 Slope of CSL [-] 1.2
𝑐𝑐 Virgin Compression Index [-] 0.072676
𝑐𝑟 Recompression Index [-] 0.014535
𝜎ℎ Horizontal Stress [kPa] -100
𝜎𝑣 Vertical Stress [kPa] -160
𝑎0 Initial Well Radius [m] 0.1
𝑃𝑤 Mud Pressure [kPa] -300

Inspecting results

In the above example, we requested silo-format output files. We can therefore import these into VisIt and use python
scripts to visualize the outcome. The following figure shows the distribution of 𝜎𝜃𝜃 in the near wellbore region.
The figure below shows the comparisons between the numerical predictions (marks) and the corresponding analyti-
cal solutions (solid curves) with respect to the distributions of normal stress components, stress path, the supporting
wellbore pressure and wellbore size. It is evident that the predictions well match the analytical results.

1.4. Advanced Examples 261

GEOS Documentation

Fig. 1.48: Simulation result of 𝜎𝜃𝜃

262 Chapter 1. Table of Contents

GEOS Documentation

500 500
r-Analytical p_Analytical
r-GEOSX p_GEOSX

Distribution of p and q (kPa)

o-Analytical q_Analytical
400 o-GEOSX 400 q_GEOSX
z-Analytical
z-GEOSX
300 300
(kPa)

200 200

100 100

0100 101 102 0100 101 102

rd rd
400 Analytical
1000 Analytical
350 GEOSX GEOSX
800
300
250 600

Pw (kPa)
q (kPa)

200
150 400
100
200
50
00 50 100 150 200 250 300 350 400 00.9 1.0 1.1 1.2 1.3 1.4 1.5
p (kPa) a/a0

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Deviated Poro-Elastic Wellbore Subjected to Fluid Injection

Problem description

This example aims to solve a typical injection problem of a deviated wellbore subjected to a fluid pressure loaded at
wellbore wall. The problem geometry is generated with the internal wellbore mesh generator. Open hole completion
and poroelastic deformation are assumed. The coupled poroelastic solver, which combines the solid mechanics solver
and the single phase flow solver, is hereby employed to solve this specific problem. In-situ stresses and gravity effect
are excluded from this example. Please refer to the case Deviated Poro-Elastic Wellbore Subjected to In-situ Stresses
and Pore Pressure for in-situ stresses and pore pressure effects.
Analytical solutions of the pore pressure, the radial and hoop stresses in the near wellbore region are expressed in the
Laplace space as (Detournay and Cheng, 1988) :
√
𝑘0 (𝑅 𝑠)
𝑝 = 𝑝0 √
𝑠𝑘0 ( 𝑠)
√ √
1 − 2𝜈 −𝑅𝑘1 (𝑅 𝑠) + 𝑘1 ( 𝑠)
𝜎𝑟𝑟 = −𝑏 𝑝0 √ √
1−𝜈 𝑅2 𝑠3 𝑘0 ( 𝑠)
1 − 2𝜈
𝜎𝜃𝜃 = −𝑏 𝑝 − 𝜎𝑟𝑟
1−𝜈
where 𝑠 is the Laplace variable normalized by the fluid diffusion coefficient, 𝑘0 and 𝑘1 are respectively the modified
Bessel functions of second kind of order 0 and 1, 𝑅 is the dimensionless radial coordinate that is defined by the radial
coordinate normalized by the wellbore radius, 𝜈 is the Poisson ratio and 𝑏 is the Biot coefficient. Fluid pressure and
stresses in time space are obtained from these analytical expressions by the inverse Laplace transform (see the attached
Python script for more details).

1.4. Advanced Examples 263

GEOS Documentation

Input file
Everything required is contained within two GEOS xml files that are located at:

inputFiles/wellbore/DeviatedPoroElasticWellbore_Injection_base.xml

inputFiles/wellbore/DeviatedPoroElasticWellbore_Injection_benchmark.xml

In this example, we would focus our attention on the Solvers and the Mesh tags.

Poroelastic solver

The coupled Poroelastic solver, that defines a coupling strategy between the solid mechanics solver
SolidMechanicsLagrangianSSLE and the single phase flow solver SinglePhaseFVM, is required for solving this
wellbore problem.

Deviated wellbore mesh

(continued from previous page)

</FieldSpecifications>

Results and benchmark

Result of the fluid pressure distribution after 78 s injection is shown in the figure below:

A good agreement between the GEOS results and the corresponding analytical solutions is shown in the figure below:

To go further

Feedback on this example

This concludes the deviated poro-elastic wellbore example. For any feedback on this example, please submit a GitHub
issue on the project’s GitHub page.

Deviated Poro-Elastic Wellbore Subjected to In-situ Stresses and Pore Pressure

Problem description

This example deals with the problem of drilling a deviated poro-elastic wellbore. This is an extension of the poroelastic
wellbore example Deviated Poro-Elastic Wellbore Subjected to Fluid Injection with the consideration of in-situ stresses
and in-situ pore pressure. Both pore pressure and mud pressure are supposed to be nil at the borehole wall following

1.4. Advanced Examples 267

GEOS Documentation

8
7
2.0
6

Effectve tangent stress (MPa)

Effectve radial stress (MPa)

5 1.5
4
3 1.0
2
0.5
1
0
0.0
0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0
r (m) r (m)

10 GEOSX result
Analytic
8
Pore pressure (MPa)

0
0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1.0

268 Chapter 1. Table of Contents

GEOS Documentation

the consideration of (Abousleiman and Cui, 1998). Also, the in-situ horizontal stresses are anisotropic, i.e. 𝜎ℎ𝑚𝑎𝑥 >
𝜎ℎ𝑚𝑖𝑛 . The wellbore trajectory is deviated from the directions of the in-situ stresses. Analytical solutions of the pore
pressure, the radial and hoop stresses in the near wellbore region are given by (Abousleiman and Cui, 1998). They are
hereby used to verify the modeling predictions.
Input file
Everything required is contained within two GEOS xml files that are located at:

inputFiles/wellbore/DeviatedPoroElasticWellbore_Drilling_base.xml

inputFiles/wellbore/DeviatedPoroElasticWellbore_Drilling_benchmark.xml

This case is nearly identical to another example Deviated Poro-Elastic Wellbore Subjected to Fluid Injection, except for
the FieldSpecifications tag. For this specific case, we need to consider following additional field specifications to
define the in-situ stresses, in-situ pore pressure, as well as the zero pore pressure at the borehole wall.

<FieldSpecification
name="innerPorePressure"
(continues on next page)

1.4. Advanced Examples 269

GEOS Documentation

(continued from previous page)

objectPath="faceManager"
fieldName="pressure"
scale="0e6"
setNames="{ rneg }"/>

Results and benchmark

Pore pressure distribution after 78 s injection is shown in the figure below:

A good agreement between the GEOS results and the corresponding analytical solutions (Abousleiman and Cui, 1998)
is shown in the figure below:

To go further

Feedback on this example

This concludes the deviated poro-elastic wellbore example with in-situ stresses and pore pressure effects. For any
feedback on this example, please submit a GitHub issue on the project’s GitHub page.

270 Chapter 1. Table of Contents

GEOS Documentation

0 GEOSX result 20

Effective tangent stress (MPa)

Analytic 25
Effective radial stress (MPa)

The two single-physics solvers are parameterized as explained in their corresponding documents.
In this example, let us focus on the coupling solver. This solver (PoromechanicsSolver) uses a set of attributes that
specifically describe the coupling process within a poromechanical framework. For instance, we must point this solver
to the designated fluid solver (here: SinglePhaseFlowSolver) and solid solver (here: mechanicsSolver). These
solvers are forced to interact through the porousMaterialNames="{porousRock}" with all the constitutive models.
We specify the discretization method (FE1, defined in the NumericalMethods section), and the target regions (here,
we only have one, Omega). More parameters are required to characterize a coupling procedure (more information at
Poromechanics Solver). In this way, the two single-physics solvers will be simultaneously called and executed for
solving the wellbore problem here.

Discretization methods for multiphysics solvers

1.4. Advanced Examples 275

GEOS Documentation

The finite volume method requires the specification of a discretization scheme. Here, we use a two-point flux ap-
proximation scheme (singlePhaseTPFA), as described in the dedicated documentation (found here: Finite Volume
Discretization).
<NumericalMethods>
<FiniteElements>
<FiniteElementSpace
name="FE1"
order="1"/>
</FiniteElements>
<FiniteVolume>
<TwoPointFluxApproximation
name="singlePhaseTPFA"
/>
</FiniteVolume>
</NumericalMethods>

Constitutive laws

For this test problem, the solid and fluid materials are named as rock and water respectively, whose mechanical
properties are specified in the Constitutive section. In this example, different material models, linear elastic isotropic
model (see Model: Elastic Isotropic) and Extended Drucker-Prager model (see Model: Extended Drucker-Prager), are
used to solve the mechanical deformation, which is the only difference between the poroelastic and poroplastic cases
in this example.
For the poroelastic case, PorousElasticIsotropic model is used to describe the linear elastic isotropic response
of rock to loading. And the single-phase fluid model CompressibleSinglePhaseFluid is selected to simulate the
flow of water upon injection:
<Constitutive>
<PorousElasticIsotropic
name="porousRock"
solidModelName="rock"
porosityModelName="rockPorosity"
permeabilityModelName="rockPerm"
/>
<ElasticIsotropic
name="rock"
defaultDensity="2700"
defaultBulkModulus="1.1111e10"
defaultShearModulus="8.3333e9"
/>
<CompressibleSinglePhaseFluid
name="water"
defaultDensity="1000"
defaultViscosity="0.001"
referencePressure="0e6"
referenceDensity="1000"
compressibility="2.09028227021e-10"
referenceViscosity="0.001"
viscosibility="0.0"
/>
<BiotPorosity
name="rockPorosity"
(continues on next page)

276 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

defaultGrainBulkModulus="1.0e27"
defaultReferencePorosity="0.3"
/>
<ConstantPermeability
name="rockPerm"
permeabilityComponents="{1.0e-20, 1.0e-20, 1.0e-20}"
/>
</Constitutive>

For the poroplastic case, PorousExtendedDruckerPrager model is used to simulate the elastoplastic behavior of
rock. And the single-phase fluid model CompressibleSinglePhaseFluid is employed to handle the storage and
flow of water:

As for the material parameters, defaultInitialFrictionAngle, defaultResidualFrictionAngle and

1.4. Advanced Examples 277

GEOS Documentation

defaultCohesion denote the initial friction angle, the residual friction angle, and cohesion, respectively, as de-
fined by the Mohr-Coulomb failure envelope. As the residual friction angle defaultResidualFrictionAngle is
larger than the initial one defaultInitialFrictionAngle, a strain hardening model is automatically chosen, whose
hardening rate is given as defaultHardening="0.01". If the residual friction angle is set to be less than the initial
one, strain weakening will take place. defaultDilationRatio="1.0" corresponds to an associated flow rule. If
using an incompressible fluid, the user can lower the fluid compressibility compressibility to 0. The constitutive
parameters such as the density, the bulk modulus, and the shear modulus are specified in the International System of
Units. A stress-dependent porosity model rockPorosity and constant permeability rockPerm model are defined in
this section.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (the in-situ stresses and pore pressure have to be initialized)
• The boundary conditions (traction and fluid loading at the wellbore wall and constraints of the outer boundaries
have to be set)
In this example, we need to specify anisotropic horizontal stress (𝜎ℎ = -9.0 MPa and 𝜎𝐻 = -11.0 MPa) and verti-
cal stress (𝜎𝑣 = -12.0 MPa). A compressive traction (InnerMechanicalLoad) 𝑃𝑤 = -10 MPa and fluid loading
(InnerFluidLoad) 𝑃𝑓 = 10 MPa are applied at the wellbore wall rneg. The remaining parts of the outer bound-
aries are subjected to roller constraints. These boundary conditions are set up through the FieldSpecifications
section.

<FieldSpecification
name="stressZZ"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/Omega/cb1"
fieldName="rock_stress"
component="2"
scale="-12.0e6"
/>
(continues on next page)

278 Chapter 1. Table of Contents

Problem description

This example uses the thermal single-phase flow solver to model a pure thermal diffusion problem around a wellbore.
To mimic this specific problem, thermal convection and fluid flow are neglected by setting fluid pressure and fluid heat
capacity to zero. With a uniform temperature applied on the inner surface of the wellbore, temperature field would
radially diffuse as shown in the figure below:
Analytical results of the temperature profile along the radial direction is given by (Wang and Papamichos, 1994) :
√︂
𝑅𝑖𝑛 𝑟 − 𝑅𝑖𝑛
𝑇 (𝑟) = 𝑇𝑖𝑛 𝑒𝑟𝑓 𝑐( √ )
𝑟 2 𝑐𝑇 𝑡

where 𝑟 is the radial coordinate, 𝑇𝑖𝑛 is the temperature applied on the surface of the wellbore at 𝑟 = 𝑅𝑖𝑛 , 𝑐𝑇 is the
thermal diffusion coefficient of rock, which is defined as the ratio between the thermal conductivity and the volumetric
heat capacity of rock.
Input file
This benchmark example uses no external input file and everything required is contained within two GEOS xml files
that are located at:

inputFiles/singlePhaseFlow/thermalCompressible_2d_base.xml

and

284 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.55: Sketch of the radial thermal diffusion around a wellbore

1.4. Advanced Examples 285

GEOS Documentation

inputFiles/singlePhaseFlow/thermalCompressible_2d_benchmark.xml

The corresponding integrated test is

inputFiles/singlePhaseFlow/thermalCompressible_2d_smoke.xml

In this example, we would focus our attention on the Constitutive and FieldSpecifications tags.

Constitutive

The volumetric heat capacity of the medium around the wellbore is defined in the SolidInternalEnergy XML block
as

The thermal conductivity of the medium around the wellbore is defined in the
SinglePhaseConstantThermalConductivity XML block as

The volumetric heat capacity of fluid is set to a negligible value to exclude thermal convection effect. It is defined in
the ThermalCompressibleSinglePhaseFluid XML block as

FieldSpecifications

The initial temperature, the imposed temperature at the curved wellbore surface as well as the far-field temperature are
defined as Dirichlet face boundary conditions using faceManager as

<FieldSpecification
name="initialTemperature"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/region/cb"
(continues on next page)

286 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

fieldName="temperature"
scale="100"/>

Although a pure thermal diffusion problem is considered, it is also required to define specifications for fluid pressure,
as thermal transfer is always coupled with fluid flow in GEOS. In this example, fluid pressure is set to zero everywhere
to mimic a pure thermal diffusion problem as

Results and benchmark

A good agreement between the GEOS results and analytical results is shown in the figure below:

To go further

Feedback on this example

This concludes the example of pure thermal diffusion problem around a wellbore. For any feedback on this example,
please submit a GitHub issue on the project’s GitHub page.

1.4. Advanced Examples 287

GEOS Documentation

t = 10000(s) t = 20000(s)
100 100
Temperature (°C)

50 50
GEOSX
0 0 Analytic, infinite domain
Steady State
0.0 0.2 0.4 0.6 0.8 1.0 0.0 0.2 0.4 0.6 0.8 1.0
t = 50000(s) t = 100000.0(s)
100 100
Temperature (°C)

50 50

0 0
0.0 0.2 0.4 0.6 0.8 1.0 0.0 0.2 0.4 0.6 0.8 1.0
Radial distance from well center Radial distance from well center

288 Chapter 1. Table of Contents

GEOS Documentation

Non-Linear Thermal Diffusion Around a Wellbore: The Case with Temperature Dependent Volumetric
Heat Capacity

Problem description

This example is an extension of the linear thermal diffusion problem presented in Pure Thermal Diffusion Around
a Wellbore. It uses the thermal single-phase flow solver to model a non-linear thermal diffusion problem around a
wellbore where the volumetric heat capacity of the solid rock depends linearly on the temperature.
Input file
This benchmark example uses no external input file and everything required is contained within two GEOS xml files
that are located at:

inputFiles/singlePhaseFlow/thermalCompressible_2d_base.xml

and

inputFiles/singlePhaseFlow/thermalCompressible_
˓→temperatureDependentVolumetricHeatCapacity_benchmark.xml

In this example, we focus on the Constitutive tag.

Constitutive

The reference value of the volumetric heat capacity of the medium around the wellbore and its derivative with respect
to temperature are defined in the SolidInternalEnergy XML block:

Results and benchmark

A good agreement between the results obtained using GEOS and the reference results that are obtained by the classical
finite difference method is shown in the figure below:

To go further

Feedback on this example

This concludes the example of a non-linear thermal diffusion problem around a wellbore due to temperature dependent
volumetric heat capacity of rock. For any feedback on this example, please submit a GitHub issue on the project’s
GitHub page.

Non-Linear Thermal Diffusion Around a Wellbore: The Case with Temperature Dependent Single
Phase Thermal Conductivity

Problem description

This example is an extension of the linear thermal diffusion problem presented in Pure Thermal Diffusion Around a
Wellbore to model wellbore cooling upon CO2 injection. It uses the thermal single-phase flow solver to model a non-

1.4. Advanced Examples 289

GEOS Documentation

t = 10000(s) t = 20000(s)
100 100
Temperature (°C)

50 50 GEOS
FDM Non-Linear
0 0 Analytic Linear
Steady State
0.0 0.1 0.2 0.3 0.4 0.5 0.0 0.1 0.2 0.3 0.4 0.5
t = 50000(s) t = 100000.0(s)
100 100
Temperature (°C)

50 50

0 0
0.0 0.1 0.2 0.3 0.4 0.5 0.0 0.1 0.2 0.3 0.4 0.5
Radial distance from well center Radial distance from well center

290 Chapter 1. Table of Contents

GEOS Documentation

linear thermal diffusion problem around a wellbore where the single phase thermal conductivity of the porous rock
depends linearly on the temperature.
Input file
This benchmark example uses no external input file and everything required is contained within two GEOS xml files
that are located at:

inputFiles/singlePhaseFlow/thermalCompressible_2d_base.xml

and

inputFiles/singlePhaseFlow/thermalCompressible_
˓→temperatureDependentSinglePhaseThermalConductivity_benchmark.xml

In this example, we focus on the Constitutive tag.

Constitutive

The reference value of the single phase thermal conductivity of the porous medium around the wellbore and its deriva-
tive with respect to temperature are defined in the SinglePhaseThermalConductivity XML block:

Results and benchmark

A good agreement between the results obtained using GEOS and the reference results that are obtained by the classical
finite difference method is shown in the figure below:

To go further

Feedback on this example

This concludes the example of a non-linear thermal diffusion problem around a wellbore due to temperature dependent
single phase thermal conductivity of porous rock. For any feedback on this example, please submit a GitHub issue on
the project’s GitHub page.

Cased ThermoElastic Wellbore Problem

Problem description

This example uses the thermal option of the SinglePhasePoromechanics solver to handle a cased wellbore problem
subject to a uniform temperature change on the inner surface of the casing. The wellbore is composed of a steel
casing, a cement sheath and rock formation. Isotropic linear thermoelastic behavior is assumed for all three materials.
No separation or thermal barrier is allowed for the casing-cement and cement-rock contact interfaces. Plane strain
condition is assumed.
Solution to this axisymmetric problem can be obtained in the cylindrical coordinate system by using an implicit 1D
finite difference method (Jane and Lee 1999). Results of such analysis will be considered as reference solutions to
validate GEOS results.
Input file

1.4. Advanced Examples 291

GEOS Documentation

t = 10000(s) t = 20000(s)
100 100 GEOS
Temperature (°C)

FDM Non-Linear
50 50 Analytic Linear
Steady State
0 0
0.10 0.15 0.20 0.25 0.30 0.10 0.15 0.20 0.25 0.30
t = 50000(s) t = 100000.0(s)
100 100
Temperature (°C)

50 50

0 0
0.10 0.15 0.20 0.25 0.30 0.10 0.15 0.20 0.25 0.30
Radial distance from well center Radial distance from well center

292 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.56: Sketch of a cased thermoelastic wellbore

1.4. Advanced Examples 293

GEOS Documentation

This benchmark example uses no external input files and everything required is contained within two GEOS XML files
located at:

inputFiles/wellbore/CasedThermoElasticWellbore_base.xml

and

inputFiles/wellbore/CasedThermoElasticWellbore_benchmark.xml

The corresponding integrated test is

inputFiles/wellbore/CasedThermoElasticWellbore_smoke.xml

Geometry and mesh

The internal wellbore mesh generator InternalWellbore is employed to create the mesh of this wellbore problem.
The radii of the casing cylinder, the cement sheath cylinder and the far-field boundary of the surrounding rock formation
are defined by a vector radius. In the tangent direction, theta angle is specified from 0 to 90 degrees to simulate
the problem on a quarter of the wellbore geometry. The problem is under plane strain condition and therefore we only
consider radial thermal diffusion on a single horizontal layer. The trajectory of the well is defined by trajectory,
which is vertical in this case. The autoSpaceRadialElems parameters allow for optimally increasing the element size
from the wellbore to the far-field zone. In this example, the auto spacing option is only applied to the rock formation.
The useCartesianOuterBoundary with a value 3 specified for the rock layer transforms the far-field boundary to a
circular shape. The cellBlockNames and elementTypes define the regions and related element types associated to
casing, cement sheath, and rock.

Material properties

The bulk and shear drained elastic moduli of the materials as well as its drained linear thermal expansion coefficient
relating stress change to temperature change are defined within the Constitutive tag as follows:

<ElasticIsotropic
name="casingSolid"
defaultDensity="7500"
defaultBulkModulus="159.4202899e9"
defaultShearModulus="86.61417323e9"
(continues on next page)

294 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.57: An optimized mesh for the cased wellbore.

1.4. Advanced Examples 295

GEOS Documentation

(continued from previous page)

defaultDrainedLinearTEC="1.2e-5"/>

Here the solid density is also defined but it is not used because the gravitational effect is ignored in this example. To
mimic a thermoelastic coupling without fluid flow, a negligible porosity and a zero Biot coefficient are defined as:

In this XML block, the Biot coefficient is defined using the elastic bulk modulus 𝐾𝑠 of the solid skeleton as 𝑏𝐵𝑖𝑜𝑡 =
1 − 𝐾/𝐾𝑠 . In this example, we define a skeleton bulk modulus that is identical to the drained bulk modulus 𝐾 defined
above to enforce the Biot coefficient to zero.
The thermal conductivities and the volumetric heat capacities of casing, cement, and rock are defined by following
XML blocks:

GEOS Documentation

(continued from previous page)

fieldName="casingSolid_stress"
component="2"
scale="573913043.5"/>

Zero pore pressure is set everywhere to simulate a thermoelastic problem in which fluid flow is ignored:
<FieldSpecification
name="zeroPressure"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="pressure"
scale="0e6"/>

Collecting output data

It is convenient to collect data in hdf5 format that can be easily post-processed using Python. To collect the temperature
field in the three layers for all the time steps, the following XML blocks need to be defined:
<PackCollection
name="temperatureCollection_casing"
objectPath="ElementRegions/casing/casing"
fieldName="temperature"/>
<PackCollection
name="temperatureCollection_cement"
objectPath="ElementRegions/cement/cement"
fieldName="temperature"/>
<PackCollection
name="temperatureCollection_rock"
objectPath="ElementRegions/rock/rock"
fieldName="temperature"/>

<TimeHistory
name="temperatureHistoryOutput_casing"
sources="{ /Tasks/temperatureCollection_casing }"
filename="temperatureHistory_casing"/>
<TimeHistory
name="temperatureHistoryOutput_cement"
sources="{ /Tasks/temperatureCollection_cement }"
(continues on next page)

300 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

filename="temperatureHistory_cement"/>
<TimeHistory
name="temperatureHistoryOutput_rock"
sources="{ /Tasks/temperatureCollection_rock }"
filename="temperatureHistory_rock"/>

Similarly, the following blocks are needed to collect the solid stress:

The displacement field can be collected for the whole domain using nodeManager as follows

Also, periodic events are required to trigger the collection of this data on the mesh. For example, the periodic events
for collecting the displacement field are defined as:

<PeriodicEvent
name="displacementHistoryCollection"
endTime="1e5"
(continues on next page)

1.4. Advanced Examples 301

GEOS Documentation

(continued from previous page)

forceDt="1e4"
target="/Tasks/displacementCollection"/>
<PeriodicEvent
name="displacementTimeHistoryOutput"
endTime="1e5"
forceDt="1e4"
target="/Outputs/displacementHistoryOutput"/>

Results and benchmark

A good agreement between the GEOS results and analytical results for temperature distribution around the cased well-
bore is shown in the figures below:

Fig. 1.58: Validation of the temperature.

and the validation for the radial displacement around the cased wellbore is shown below:
The validations of the total radial and hoop stress (tangent stress) components computed by GEOS against reference
results are shown in the figure below:

302 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.59: Validation of the displacement.

Fig. 1.60: Validation of the stresses.

1.4. Advanced Examples 303

GEOS Documentation

To go further

Feedback on this example

This concludes the cased wellbore example. For any feedback on this example, please submit a GitHub issue on the
project’s GitHub page.

ThermoPoroElastic Wellbore Problem

Problem description

This example uses the thermal option of the SinglePhasePoromechanics solver to handle an open wellbore prob-
lem subjected to a uniform temperature change on its inner surface. Isotropic linear thermoporoelastic behavior is
considered for the rock formation around the wellbore. Plane strain and axisymmetric conditions are assumed.

Fig. 1.61: Sketch of a thermoporoelastic wellbore

Analytical solutions to this problem were first derived by (Wang and Papamichos 1994) using a one-way coupling sim-
plification. They are also reformulated for the full coupling assumption in the book of (Cheng 2016). These solutions
will be considered to validate GEOS results.
Input file
This benchmark example uses no external input files and everything required is contained within two GEOS xml files
that are located at:

inputFiles/wellbore/ThermoPoroElasticWellbore_base.xml

and

304 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/wellbore/ThermoPoroElasticWellbore_benchmark.xml

The corresponding integrated test is

inputFiles/wellbore/ThermoPoroElasticWellbore_smoke.xml

Geometry and mesh

The internal wellbore mesh generator InternalWellbore is employed to create the mesh of this wellbore problem.
The radii of the open wellbore and the far-field boundary of the surrounding rock formation are defined by a vector
radius. In the tangent direction, theta angle is specified from 0 to 90 degrees to simulate the problem on a quarter of
the wellbore geometry. The problem is under plane strain condition and therefore we only consider thermal diffusion
along the radial direction within a single horizontal layer. The trajectory of the well is defined by trajectory, which
is vertical in this case. The autoSpaceRadialElems parameters allow for optimally increasing the element size from
the near wellbore zone to the far-field one.

Material properties

The bulk and shear drained elastic moduli of rock as well as its drained linear thermal expansion coefficient relating
stress change to temperature variation are defined within the Constitutive tag as follows:

Here the solid density is also defined, but it is not used as the gravitational effect is ignored in this example. The
porosity and the elastic bulk modulus 𝐾𝑠 of the solid skeleton are defined as:

1.4. Advanced Examples 305

GEOS Documentation

Fig. 1.62: An optimized mesh for the open wellbore.

306 Chapter 1. Table of Contents

GEOS Documentation

The thermal conductivities and the volumetric heat capacities of rock are defined by following XML blocks:

and

The permeability of rock is defined by:

Fluid properties such as viscosity, thermal expansion coefficient, etc. are defined by the XML block below. A negligible
volumetric heat capacity is defined for fluid to ignore the thermal convection effect. This way, only thermal transfer via
the diffusion phenomenon is considered.

Boundary conditions

The mechanical boundary conditions are applied to ensure the axisymmetric plane strain conditions such as:

<FieldSpecification
name="tPosConstraint"
objectPath="nodeManager"
fieldName="totalDisplacement"
component="0"
scale="0.0"
(continues on next page)

1.4. Advanced Examples 307

GEOS Documentation

(continued from previous page)

setNames="{ tpos }"/>

Besides, the far-field boundary is assumed to be fixed because the local changes on the wellbore must have negligible
effect on the far-field boundary.
<FieldSpecification
name="rPosConstraint_x"
objectPath="nodeManager"
fieldName="totalDisplacement"
component="0"
scale="0.0"
setNames="{ rpos }"/>

The traction-free condition on the inner surface of the wellbore is defined by:

The initial temperature (that is also the far-field boundary temperature) and the temperature applied on the inner surface
of the wellbore are defined as
<FieldSpecification
name="initialTemperature"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="temperature"
scale="0"/>

<FieldSpecification
name="farfieldTemperature"
setNames="{ rpos }"
objectPath="faceManager"
(continues on next page)

308 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

fieldName="temperature"
scale="0"/>

It is important to remark that the initial effective stress of rock must be set with accordance to the initial temperature
change: 𝜎0 = 3𝐾𝛼𝛿𝑇0 where 𝜎0 is the initial effective principal stress, 𝛿𝑇0 is the initial temperature change, 𝐾 is the
drained bulk modulus and 𝛼 is the drained linear thermal expansion coefficient of the materials. In this example, the
initial effective stresses are set to zero because the initial temperature change is set to zero.

The initial and boundary conditions for pore pressure are defined in the block below:

<FieldSpecification
name="innerPressure"
(continues on next page)

1.4. Advanced Examples 309

GEOS Documentation

(continued from previous page)

setNames="{ rneg }"
objectPath="faceManager"
fieldName="pressure"
scale="0e6"/>

Collecting output data

It is convenient to collect data in hdf5 format that can be easily post-processed using Python. To collect the temperature
field for all the time steps, the following XML blocks need to be defined:

Similarly, the following blocks are needed to collect the effective stress field across the domain:

The displacement field can be collected using nodeManager as follows

310 Chapter 1. Table of Contents

GEOS Documentation

Also, periodic events are required to trigger the collection of this data during the entire simulation. For example, the
periodic events for collecting the displacement field are defined as:

Results and benchmark

A good agreement between the GEOS results and analytical results for temperature and pore pressure distribution
around the wellbore is shown in the figures below:
and the validation for the radial displacement around the cased wellbore is shown below:
The validations of the total radial and hoop stress (tangent stress) components computed by GEOS against reference
results are shown in the figure below:

To go further

Feedback on this example

This concludes the cased wellbore example. For any feedback on this example, please submit a GitHub issue on the
project’s GitHub page.

Cased Elastic Wellbore with Imperfect Interfaces

Problem description

This example uses the LagrangianContact solver to handle a cased wellbore problem with imperfect contact in-
terfaces. The completed wellbore is composed of a steel casing, a cement sheath, and rock formation. All the three
materials are assumed to exhibit isotropic linear elastic behavior. The contact surfaces between these materials are
simulated using a Lagrangian contact model.
Under a compressional loading in the radial direction, the imperfect contact interfaces behave like the perfect ones (see
Cased Elastic Wellbore Problem). When a radial tension acting on the inner face of the wellbore, the casing debonds

1.4. Advanced Examples 311

GEOS Documentation

Fig. 1.63: Validation of temperature and pore pressure.

Fig. 1.64: Validation of the radial displacement.

312 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.65: Validation of the radial and tangent stresses.

from the cement layer. Analytical results of the radial displacement 𝑢𝑟 in the casing is expressed as (Hervé and Zaoui,
1995) :
𝐵
𝑢𝑟 = 𝐴𝑟 −
𝑟
where 𝑟 is the radial coordinate, 𝐴 and 𝐵 are constants that are obtained by solving the boundary conditions, as detailed
in the post-processing script. The outer face of the casing as well as the inner face of the cement layer are free of stress
because of the debonding at the casing-cement interface. Therefore, the displacement jump at the cement-rock interface
is nil, and the displacement jump across the casing-cement interface is equal to 𝑢𝑟 (𝑟 = 𝑟𝑜𝑢𝑡𝑐 𝑎𝑠𝑖𝑛𝑔 ), where 𝑟𝑜𝑢𝑡𝑐 𝑎𝑠𝑖𝑛𝑔
is the outer radius of the casing.
Input file
This benchmark example does not use any external input files and everything required is contained within two GEOS
XML files located at:

inputFiles/wellbore/CasedElasticWellbore_ImperfectInterfaces_base.xml

and

inputFiles/wellbore/CasedElasticWellbore_ImperfectInterfaces_benchmark.xml

The corresponding integrated test is

inputFiles/wellbore/CasedElasticWellbore_ImperfectInterfaces_smoke.xml

In this example, we should focus on following XML blocks:

1.4. Advanced Examples 313

GEOS Documentation

Fig. 1.66: A cased wellbore with imperfect casing-cement and cement-rock interfaces

314 Chapter 1. Table of Contents

GEOS Documentation

Cylinder geometry

The nodesets that define the casing-cement and cement-rock interfaces are curved. In this example, we use the
Cylinder geometry to select these nodesets. This geometry is defined by the centers of the two plane faces,
firstFaceCenter and secondFaceCenter, and its inner and outer radii, innerRadius and outerRadius. Note
that the inner radius is optional as it is only needed for defining a hollow cylinder (i.e. an annulus). The inner radius is
required in this example to select only the nodes on the casing-cement and the cement-rock interfaces.

Events

In this example, we need to define a solo event for generating the imperfect contact surfaces as shown below:

where the surface generation solver is defined as follows:

Here, rockToughness is defined by default but has been omitted in this simulation.
To collect the displacement jump across the imperfect interfaces, we also define two periodic events as shown below:

<PeriodicEvent
name="displacementJumpHistoryCollection"
endTime="2.0"
forceDt="0.1"
target="/Tasks/displacementJumpCollection"/>
<PeriodicEvent
name="displacementJumpTimeHistoryOutput"
(continues on next page)

1.4. Advanced Examples 315

GEOS Documentation

(continued from previous page)

endTime="2.0"
forceDt="0.1"
target="/Outputs/displacementJumpHistoryOutput"/>

The corresponding Tasks and Outputs targets must be defined in conjunction with these events.

Numerical Methods

The stabilizationName that is required in the LagrangianContact solver is defined by:

Contact region and material

The imperfect contact surfaces between casing, cement, and rock layers are defined as Fracture as shown below:

Here, the faceBlock name, faceElementSubRegion, is needed to define Tasks for collecting displacement jumps
across the contact surfaces. The defaultAperture defined in this block is the default hydraulic aperture that should
not be confused with the mechanical aperture. For this purely mechanical problem, the default hydraulic aperture
parameter is omitted. The fracture material given in the materialList is defined as follows:

For this purely mechanical problem, without fluid flow and shearing stress acting on the contact surface, all the param-
eters defined in this block are omitted.

Results and benchmark

The GEOS results of displacement jump across the casing-cement and cement-rock interfaces are shown in the figure
below:
As expected, we observe a zero-displacement jump at the cement-rock interface under a tension stress on the inner
surface of the casing. Indeed, the stress applied here does not cause any strain on the cement and rock layers after
debonding has occurred at the casing-cement interface. The displacement jump at the casing-cement interface is ho-
mogeneous and varies over time because the tension stress on the inner surface of the casing varies with time, as defined
in the XML file. A perfect comparison between GEOS results and theoretical results is shown in the figure below:

316 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.67: Displacement jumps across the casing-cement and cement-rock interfaces

1.4. Advanced Examples 317

GEOS Documentation

GEOS
70 Analytical
60
Normal displacement jump [ m]

0
0.00 0.25 0.50 0.75 1.00 1.25 1.50 1.75 2.00
Time [s]

318 Chapter 1. Table of Contents

GEOS Documentation

To go further

Feedback on this example

This concludes the cased wellbore example. For any feedback on this example, please submit a GitHub issue on the
project’s GitHub page.

Cased ThermoElastic Wellbore Problem with Imperfect Contact Interfaces

Problem description

This example uses the coupled THM solver in GEOS to handle a cased wellbore problem subject to a temperature
reduction at the casing surface due to cold CO2 injection. The wellbore consists of a steel casing, a cement sheath, and
a rock formation. We assume an isotropic linear thermo-elastic behavior for all three materials.
In this example, we do not model any fluid flow. All heat transfers between the casing, cement layer, and rock formation
are due only to conduction, and no heat convection is not considered. While GEOS could also simulate convection, we
chose to simulate a simplified conduction-only case because semi-analytical solutions exist for this problem. Debonding
(separation) is allowed for the casing-cement and cement-rock contact interfaces.
This example is an extension of the pure mechanical debonding example:ref:AdvancedExampleCasedElasticWellbore
and the THM problem without debonding Cased ThermoElastic Wellbore Problem. A large portion of the XML files
are inherited from those two examples.
Analytical results for the temperature field, the radial displacement, and the radial and hoop stresses can be derived
for the axisymmetric plane strain problem with assumptions of debonding at casing-cement or cement-rock interfaces.
Note that solutions to this problem are not available in the literature for citation, as it is newly derived by the GEOS
team for verifying the numerical results.
Input file
This benchmark example uses no external input files and everything required is contained within two GEOS XML files
located at:

inputFiles/wellbore/CasedThermoElasticWellbore_ImperfectInterfaces_base.xml

and

inputFiles/wellbore/CasedThermoElasticWellbore_ImperfectInterfaces_benchmark.xml

The corresponding integrated test is

inputFiles/wellbore/CasedThermoElasticWellbore_ImperfectInterfaces_smoke.xml

Geometry and mesh

The geometry and mesh are defined similarly to the ones in the example Cased ThermoElastic Wellbore Problem. To
define the imperfect interfaces between the casing, cement and rock layers, we added the following blocks:

<Geometry>
<Cylinder
name="casingCementInterface"
firstFaceCenter="{ 0.0, 0.0, -0.001 }"
secondFaceCenter="{ 0.0, 0.0, 0.101 }"
outerRadius="0.17781"
innerRadius="0.17779"
/>
(continues on next page)

1.4. Advanced Examples 319

GEOS Documentation

(continued from previous page)

Here, we use the Cylinder geometry to select these nodesets. A detailed explanation of the inputs in this block is
given in the example Cased Elastic Wellbore Problem.

Material properties

Besides the THM properites of casing, cement and rock as defined in the example Cased ThermoElastic Wellbore
Problem, we define properties for the contact interfaces. The mechanical properties of the contact surfaces are defined
similarly to the example Cased Elastic Wellbore Problem. Additionally, following blocks define the thermal conduc-
tivity of the contact interface.

These properties are used for defining the imperfect contact surfaces as follows:

<SurfaceElementRegion
name="Fracture"
faceBlock="faceElementSubRegion"
materialList="{ fluid, fractureFilling, frictionLaw, contactThermalCond,␣
˓→hApertureModel }"

defaultAperture="5.0e-4"/>

As we are using the fully coupled THM solver to solve the thermo-elastic coupled problem, it is also required to define
the flow properties for the contact surfaces as follows:

(continues on next page)

320 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Boundary and initial conditions

The boundary condition at the casing inner surface and in the far-field are defined identically to the ones of the example
Cased ThermoElastic Wellbore Problem. The in-situ initial conditions are also defined in the same way as described in
that example. The additional specifications for the contact surfaces are defined identically to the example Cased Elastic
Wellbore Problem.

Solvers

The solver for simulating this THM problem with imperfect contact interfaces is defined as follows:

Fig. 1.71: The stress field.

324 Chapter 1. Table of Contents

GEOS Documentation

Viscoplasticity
Drucker-Prager Model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate an elasto-plastic triaxial compression test of a Drucker-Prager solid.
Constant lateral confining stress together with loading/unloading axial strain periods are imposed. Imposed axial strain
range are high enough for allowing plastic yield in both loading and unloading period. This complicated scenario is
used for verifying the numerical convergence and accuracy of the Drucker-Prager constitutive model implemented in
GEOS.
Semi-analytical results for axial stress variations ∆𝜎𝑉 and lateral strain variations ∆𝜀𝑉 can be established for the
imposed triaxial boundary conditions:

∆𝜎𝑉 = ∆𝜀𝑉 𝐸𝑒𝑝

∆𝜎𝑉
∆𝜀𝐻 = ∆𝜀𝑉 − ′
𝐸𝑒𝑝
where 𝐸𝑒𝑝 and 𝐸𝑒𝑝 ′
are elasto-plastic Young moduli that can be obtained from the elastic Young and shear moduli (𝐸
and 𝜇), the frictional parameter 𝑏, the dilation parameter 𝑏′ and the hardening rate ℎ of the Drucker-Prager model by:

1 1 (𝑏′ − 3)(𝑏 − 3)
= +
𝐸𝑒𝑝 𝐸 9ℎ

1 1 𝑏−3
′
= −
𝐸𝑒𝑝 2𝜇 2ℎ
These solutions are applied only when the plastic yield condition is satisfied. The cohesion parameter defining the
plastic yield surface is updated with stress changes as

𝑏−3
∆𝑎 = ∆𝜎𝑉
3
These solutions were established for a positive shear stress 𝑞 = −(𝜎𝑉 − 𝜎𝐻 ) (negative sign convention for compres-
sional stress). For the case when the plastic yield occurs at a negative shear stress, we have:

1 1 (𝑏′ + 3)(𝑏 + 3)
= +
𝐸𝑒𝑝 𝐸 9ℎ

1 1 𝑏+3
′
= +
𝐸𝑒𝑝 2𝜇 2ℎ
and
𝑏+3
∆𝑎 = ∆𝜎𝑉
3
These solutions are implemented in a Python script associated to this example for verifying GEOS results.
Input files
This validation example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

1.4. Advanced Examples 325

GEOS Documentation

inputFiles/triaxialDriver/triaxialDriver_DruckerPrager.xml

It also uses a set of table files located at:

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/DruckerPrager/
˓→TriaxialDriver_vs_SemiAnalytic_DruckerPrager.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the constant lateral confining stress, and the initial stress are defined
in the Task block as:

Constitutive laws

The elasto-plastic parameters are defined as:

All constitutive parameters such as density, viscosity, and bulk and shear moduli are specified in the International
System of Units.

326 Chapter 1. Table of Contents

GEOS Documentation

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named DruckerPragerResults.txt. A perfect comparison between
the results given by the TriaxialDriver solver in GEOS and the semi-analytical results presented above is shown below.

8 8
0.00
6 6
Deviatoric Stress (MPa)

Deviatoric Stress (MPa)

Volumetric Strain (%)
0.02
4 4
2 0.04 2
0 0.06 0
2 0.08 2
4 4 Triaxial Driver
0.10
6 6 Semi-Analytical
0.25 0.00 0.25 0.50 0.0 0.2 0.4 0.6 8 10 12
Strain (%) Axial Strain (%) Mean stress (MPa)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Visco Drucker-Prager Model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate a triaxial compression test of a Visco Drucker-Prager solid. Constant
lateral confining stress together with loading/unloading axial strain periods are imposed. Imposed axial strain range are
high enough for allowing visco-plastic yield in both loading and unloading period. This complicated scenario is used
for verifying the numerical convergence and accuracy of the Visco Drucker-Prager constitutive model implemented in
GEOS.
Semi analytical result for axial stress variation ∆𝜎𝑉 and lateral strain variation ∆𝜀𝑉 can be established for the im-
posed triaxial boundary conditions following the theoretical basis of the Perzyna time dependent approach presented
by (Runesson et al. 1999) as:
𝑏′ − 3
)𝐸∆𝜎𝑉 = (∆𝜀𝑉 − ∆𝜆
3
∆𝜎𝑉 3
∆𝜀𝐻 = ∆𝜀𝑉 − + ∆𝜆
2𝜇 2
where 𝐸 and 𝜇 are the elastic Young and shear moduli. The visco-plastic multiplier ∆𝜆 can be approximated by:
∆𝑡 𝐹
∆𝜆 =
𝑡* 3𝜇 + 𝐾𝑏𝑏′ + ℎ
in which ∆𝑡 is the time increment, 𝑡* is the relaxation time, 𝐹 is the stress function defining the visco-plastic yield
surface, 𝐾 is the elastic bulk modulus, 𝑏 is the frictional parameter defining the visco-plastic yield surface, 𝑏′ is the
dilation parameter defining the plastic potential and ℎ is the hardening rate. These solutions are applied only when
plastic yield condition is satisfied. The cohesion parameter defining the plastic yield surface is updated with stress
change as
∆𝑎 = ℎ∆𝜆
These solutions were established for a positive shear stress 𝑞 = −(𝜎𝑉 −𝜎𝐻 ) (negative sign convention for compression
stress). For the case when the plastic yield occurs at a negative shear stress, we have
𝑏′ + 3
∆𝜎𝑉 = (∆𝜀𝑉 − ∆𝜆 )𝐸
3

1.4. Advanced Examples 327

GEOS Documentation

∆𝜎𝑉 3
∆𝜀𝐻 = ∆𝜀𝑉 − − ∆𝜆
2𝜇 2
These solutions are implemented in a Python script associated to this example for verifying GEOS results.
Input files
This benchmark example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

inputFiles/triaxialDriver/triaxialDriver_ViscoDruckerPrager.xml

It also uses a set of table files located at:

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/ViscoDruckerPrager/
˓→TriaxialDriver_vs_SemiAnalytic_ViscoDruckerPrager.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the constant lateral confining stress as well as the initial stress are
defined in the Task block as

Constitutive laws

The elasto-visco-plastic parameters are defined as

<ViscoDruckerPrager
name="ViscoDruckerPrager"
defaultDensity="2700"
defaultBulkModulus="10.0e9"
defaultShearModulus="6.0e9"
defaultCohesion="0.1e6"
defaultFrictionAngle="6.0"
defaultDilationAngle="3.0"
(continues on next page)

328 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

defaultHardeningRate="0.5e9"
relaxationTime="0.1"
/>

All constitutive parameters such as density, viscosity, and bulk and shear moduli are specified in the International
System of Units.

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named ViscoDruckerPragerResults.txt. A comparison between
the results given by the TriaxialDriver solver in GEOS and the approximated semi-analytical results presented above
is shown below. Interestingly we observed that the Duvaut-Lions approach implemented in GEOS can fit perfectly
with the Perzyna approach that was considered for deriving the analytical results. This consistency between these time
dependence approaches is because of the linear hardening law of the considered constitutive model as already discussed
by (Runesson et al. 1999) .

0.02
10 10
Deviatoric Stress (MPa)

Deviatoric Stress (MPa)

0.00
Volumetric Strain (%)

5 0.02 5
0.04
0 0
0.06
5 0.08 5
Triaxial Driver
0.10 Semi-Analytical
0.25 0.00 0.25 0.50 0.0 0.2 0.4 0.6 8 10 12 14
Strain (%) Axial Strain (%) Mean stress (MPa)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Extended Drucker-Prager Model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate an elasto-plastic triaxial compression test of an Extended Drucker-
Prager solid. Constant lateral confining stress together with loading/unloading axial strain periods are imposed. Im-
posed axial strain range are high enough for allowing plastic yield in both loading and unloading period. This compli-
cated scenario is used for verifying the numerical convergence and accuracy of the Extended Drucker-Prager constitu-
tive model implemented in GEOS.
Semi-analytical results for axial stress variations ∆𝜎𝑉 and lateral strain variations ∆𝜀𝑉 can be established for the
imposed triaxial boundary conditions:
∆𝜎𝑉 = ∆𝜀𝑉 𝐸𝑒𝑝
∆𝜎𝑉
∆𝜀𝐻 = ∆𝜀𝑉 − ′
𝐸𝑒𝑝
where 𝐸𝑒𝑝 and 𝐸𝑒𝑝 ′
are elasto-plastic Young moduli that can be obtained from the elastic Young and shear moduli (𝐸
and 𝜇), the frictional parameter 𝑏 and the dilation ratio 𝜃 of the Extended Drucker-Prager model by:
1 1 (𝜃𝑏 − 3)(𝑏 − 3)
= +
𝐸𝑒𝑝 𝐸 9ℎ

1.4. Advanced Examples 329

GEOS Documentation

1 1 𝑏−3
′
= −
𝐸𝑒𝑝 2𝜇 2ℎ
The hardening rate ℎ is defined by

𝜕𝐹 𝜕𝑏
ℎ=
𝜕𝑏 𝜕𝜆
These solutions are applied only when the plastic yield condition is satisfied. The cohesion parameter defining the
plastic yield surface is updated with stress changes as:

𝑏−3
∆𝜆 = ∆𝜎𝑉
3ℎ
These solutions were established for a positive shear stress 𝑞 = −(𝜎𝑉 − 𝜎𝐻 ) (negative sign convention for compres-
sional stress). For the case when the plastic yield occurs at a negative shear stress, we have:

1 1 (𝜃𝑏 + 3)(𝑏 + 3)
= +
𝐸𝑒𝑝 𝐸 9ℎ

1 1 𝑏+3
′
= +
𝐸𝑒𝑝 2𝜇 2ℎ
and
𝑏+3
∆𝜆 = ∆𝜎𝑉
3ℎ
These solutions are implemented in a Python script associated to this example for verifying GEOS results.
Input files
This validation example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

inputFiles/triaxialDriver/triaxialDriver_ExtendedDruckerPrager.xml

It also uses a set of table files located at:

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/ExtendedDruckerPrager/
˓→TriaxialDriver_vs_SemiAnalytic_ExtendedDruckerPrager.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the constant lateral confining stress, and the initial stress are defined
in the Task block as:

330 Chapter 1. Table of Contents

GEOS Documentation

Constitutive laws

The elasto-plastic parameters are defined as:

All constitutive parameters such as density, viscosity, and bulk and shear moduli are specified in the International
System of Units.

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named ExtendedDruckerPragerResults.txt. A perfect comparison
between the results given by the TriaxialDriver solver in GEOS and the semi-analytical results presented above is shown
below

4 0.00 4
Deviatoric Stress (MPa)

Deviatoric Stress (MPa)

3 3
Volumetric Strain (%)

2 0.05 2
1 1
0 0.10 0
1 1
0.15
2 2
Triaxial Driver
3 3 Semi-Analytical
0.20
0.25 0.00 0.25 0.50 0.0 0.2 0.4 0.6 9 10 11
Strain (%) Axial Strain (%) Mean stress (MPa)

1.4. Advanced Examples 331

GEOS Documentation

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Visco Extended Drucker-Prager Model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate a triaxial compression test of a Visco Extended Drucker-Prager solid.
Constant lateral confining stress together with loading/unloading axial strain periods are imposed. Imposed axial strain
range are high enough for allowing plastic yield in both loading and unloading period. This complicated scenario is
used for verifying the numerical convergence and accuracy of the Visco Extended Drucker-Prager constitutive model
implemented in GEOS.
Semi analytical result for axial stress variation ∆𝜎𝑉 and lateral strain variation ∆𝜀𝑉 can be established for the im-
posed triaxial boundary conditions following the theoretical basis of the Perzyna time dependent approach presented
by (Runesson et al. 1999) as:

𝜃𝑏 − 3
∆𝜎𝑉 = (∆𝜀𝑉 − ∆𝜆 )𝐸
3
∆𝜎𝑉 3
∆𝜀𝐻 = ∆𝜀𝑉 − + ∆𝜆
2𝜇 2
where 𝐸 and 𝜇 are the elastic Young and shear moduli. The visco-plastic multiplier ∆𝜆 can be approximated by:

∆𝑡 𝐹
∆𝜆 =
𝑡* 3𝜇 + 𝐾𝜃𝑏2 + ℎ
in which ∆𝑡 is the time increment, 𝑡* is the relaxation time, 𝐹 is the stress function defining the visco-plastic yield
surface, 𝐾 is the elastic bulk modulus, 𝑏 is the frictional parameter defining the visco-plastic yield surface, 𝜃 is the
dilation ratio defining the plastic potential and ℎ is the hardening rate. The hardening rate ℎ is defined by

𝜕𝐹 𝜕𝑏
ℎ=
𝜕𝑏 𝜕𝜆
These solutions were established for a positive shear stress 𝑞 = −(𝜎𝑉 −𝜎𝐻 ) (negative sign convention for compression
stress). For the case when the plastic yield occurs at a negative shear stress, we have

𝜃𝑏 + 3
∆𝜎𝑉 = (∆𝜀𝑉 − ∆𝜆 )𝐸
3
∆𝜎𝑉 3
∆𝜀𝐻 = ∆𝜀𝑉 − − ∆𝜆
2𝜇 2
These solutions are implemented in a Python script associated to this example for verifying GEOS results.
Input files
This validation example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

inputFiles/triaxialDriver/triaxialDriver_ViscoExtendedDruckerPrager.xml

It also uses a set of table files located at:

332 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/
˓→ViscoExtendedDruckerPrager/TriaxialDriver_vs_SemiAnalytic_ViscoExtendedDruckerPrager.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the constant lateral confining stress as well as the initial stress are
defined in the Task block as

Constitutive laws

The elasto-visco-plastic parameters are defined as

All constitutive parameters such as density, viscosity, and bulk and shear moduli are specified in the International
System of Units.

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named ViscoExtendedDruckerPragerResults.txt. A comparison
between the results given by the TriaxialDriver solver in GEOS and the approximated semi-analytical results presented
above is shown below. Interestingly we observed that the Duvaut-Lions approach implemented in GEOS can fit perfectly
with the Perzyna approach that was considered for deriving the analytical results. This consistency between these time

1.4. Advanced Examples 333

GEOS Documentation

dependence approaches is because of the linear hardening law of the considered constitutive model as already discussed
by (Runesson et al. 1999) .

12.5 0.025 12.5

10.0 0.000 10.0
Deviatoric Stress (MPa)

Deviatoric Stress (MPa)

Volumetric Strain (%)
7.5 0.025 7.5
5.0 0.050 5.0
2.5 0.075 2.5
0.0 0.100 0.0
2.5 0.125 2.5
5.0 5.0 Triaxial Driver
0.150 Semi-Analytical
7.5 0.25 0.00 0.25 0.50 0.0 0.2 0.4 0.6 7.5 8 10 12 14
Strain (%) Axial Strain (%) Mean stress (MPa)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Modified CamClay Model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate an elasto-plastic oedometric compression test of a Modified CamClay
solid. Oedometric condition with zero lateral strain together with loading/unloading axial strain periods are imposed.
Semi-analytical results for the mean and shear stress variations ∆𝑝 and ∆𝑞 can be derived from the imposed vertical
strain variation by solving the following equation system:

1 1 𝜕𝐹 𝜕𝐺 1 𝜕𝐹 𝜕𝐺
∆𝜀𝑉 = ∆𝑝( + ) + ∆𝑞
𝐾 ℎ 𝜕𝑝 𝜕𝑝 ℎ 𝜕𝑞 𝜕𝑝
3 𝜕𝐹 𝜕𝐺 1 1 𝜕𝐹 𝜕𝐺
∆𝜀𝑉 = ∆𝑝 + ∆𝑞( + )
2ℎ 𝜕𝑝 𝜕𝑞 2𝜇 ℎ 𝜕𝑞 𝜕𝑞
where 𝐾 and 𝜇 are elastic bulk and shear moduli, 𝐹 and 𝐺 are the plastic yield surface and the plastic potential, and ℎ
the is hardening rate defined by:

𝜕𝐹 𝜕𝐺
ℎ=−
𝜕𝜀𝑣𝑝
𝑣𝑜𝑙 𝜕𝑝

in which 𝜀𝑣𝑝
𝑣𝑜𝑙 is the volumetric visco-plastic strain. These solutions are implemented in a Python script associated to
this example for verifying GEOS results.
Input files
This validation example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

inputFiles/triaxialDriver/triaxialDriver_ModifiedCamClay.xml

It also uses a set of table files located at:

334 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/ModifiedCamClay/
˓→TriaxialDriver_vs_SemiAnalytic_ModifiedCamClay.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the zero lateral strain as well as the initial stress are defined in the
Task block as

Constitutive laws

The elasto-plastic parameters are defined as

All constitutive parameters such as density, viscosity, bulk and shear moduli are specified in the International System
of Units.

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named ModifiedCamClayResults.txt. A perfect comparison between
the results given by the TriaxialDriver solver in GEOS and the semi-analytical results presented above is shown below:

1.4. Advanced Examples 335

GEOS Documentation

700 350
1000
600 300

Deviatoric Stress (kPa)

800

Radial stress (kPa)

250

Axial Stress (kPa)

500
200
600 400
150
400 300 100
200 50
200 Triaxial Driver
100 0 Semi-Analytical
0.0 0.2 0.4 0.6 0.0 0.2 0.4 0.6 200 400 600 800
Axial Strain (%) Axial Strain (%) Mean stress (kPa)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Visco Modified CamClay model: Triaxial Driver versus Semi-Analytical Solution

Problem description

This example uses the Triaxial Driver to simulate a visco-elasto-plastic oedometric compression test of a Visco Modified
CamClay solid. Oedometric condition with zero lateral strain together with loading/unloading axial strain periods are
imposed. Semi-analytical results for the mean and shear stress variations ∆𝑝 and ∆𝑞 can be established, considering
the Perzyna approach, for the imposed oedometric boundary conditions as (Runesson et al. 1999) :
𝜕𝐺
∆𝑝 = 𝐾(∆𝜀𝑉 − ∆𝜆 )
𝜕𝑝
3 𝜕𝐺
∆𝑞 = 2𝜇(∆𝜀𝑉 − ∆𝜆 )
2 𝜕𝑞
where 𝐾 and 𝜇 are elastic bulk and shear moduli, 𝐺 is the plastic potential and ∆𝜆 is the visco-plastic multiplier that
can be approximated by:
∆𝑡 𝐹
∆𝜆 =
𝑡* 3𝜇 𝜕𝐹
𝜕𝑞
𝜕𝐺
𝜕𝑞 + 𝐾 𝜕𝐹
𝜕𝑝
𝜕𝐺
𝜕𝑝 +ℎ

in which ∆𝑡 is the time increment, 𝑡* is the relaxation time, 𝐹 is the stress function defining the visco-plastic yield
surface and ℎ is the hardening rate defined by:
𝜕𝐹
ℎ=−
𝜕𝜆
These solutions are implemented in a Python script associated to this example for verifying GEOS results.
Input files
This validation example uses two GEOS xml files that are located at:

inputFiles/triaxialDriver/triaxialDriver_base.xml

and

inputFiles/triaxialDriver/triaxialDriver_ViscoModifiedCamClay.xml

It also uses a set of table files located at:

336 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/triaxialDriver/tables/

A Python script for the semi-analytical solutions presented above as well as for post-processing the GEOS results is
provided at:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/ViscoModifiedCamClay/
˓→TriaxialDriver_vs_SemiAnalytic_ViscoModifiedCamClay.py

For this example, we focus on the Task and the Constitutive tags.

Task

The imposed axial strain loading/unloading periods, the lateral zero strain, and the initial stress are defined in the Task
block as:

Constitutive laws

The elasto-visco-plastic parameters are defined as:

All constitutive parameters such as density, viscosity, and the bulk and shear moduli are specified in the International
System of Units.

A comparison between GEOS results and semi-analytical results

The simulation results are saved in a text file, named ViscoModifiedCamClayResults.txt. A comparison between
the results given by the TriaxialDriver solver in GEOS and the semi-analytical results presented above is shown below.
The discrepancy between these results may due to the difference between the Duvaut-Lions approach and the Perzyna
approach for time dependant behavior when applying for the Modified CamClay model as discussed by Runesson et al.
(1999).

1.4. Advanced Examples 337

GEOS Documentation

800
700 350
1000

Deviatoric Stress (kPa)

600 300

Radial stress (kPa)

Axial Stress (kPa)
800 250
500
600 200
400
150
400 300 100
200 50 Triaxial Driver
200
100 0 Semi-Analytical
0.0 0.2 0.4 0.6 0.0 0.2 0.4 0.6 200 400 600 800
Axial Strain (%) Axial Strain (%) Mean stress (kPa)

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Verification of a Relaxation Test with Visco Extended Drucker-Prager Model

Context
In this example, we simulate a relaxation test with a Visco Extended Drucker-Prager solid. This problem is solved using
a viscoplastic solver (see Model: Viscoplasticity) in GEOS to predict the time-dependent deformation of the sample
when subject to loading conditions. We verify the numerical results obtained by GEOS against a semi-analytical
solution (see Visco Extended Drucker-Prager Model: Triaxial Driver versus Semi-Analytical Solution).
Input file
The xml input files for the test case are located at:

inputFiles/solidMechanics/viscoExtendedDruckerPrager_relaxation_base.xml
inputFiles/solidMechanics/viscoExtendedDruckerPrager_relaxation_benchmark.xml

A Python script for post-processing the simulation results is provided:

src/docs/sphinx/advancedExamples/validationStudies/viscoplasticity/RelaxationTest/
˓→relaxationTestFigure.py

Description of the case

We model the mechanical response of a viscoplastic slab subject to a displacement-controlled uniaxial loading and a
constant confining stress, as shown below. The domain is homogeneous, isotropic, and isothermal. Before loading,
the domain is initialized with isotropic stresses. Longitudinal compression is induced and governed by the normal
displacement applied uniformly over the top surface. This compressive displacement is initially elevated to allow plastic
hardening and then kept as a constant to mimic stress relaxation tests. In this example, fluid flow is not considered.
We set up and solve a Visco Extended Drucker-Prager model to obtain the spatial and temporal solutions of stresses
and displacements across the domain upon loading. These numerical predictions are compared with the corresponding
semi-analytical solutions derived from Runesson et al. (1999) (see Visco Extended Drucker-Prager Model: Triaxial
Driver versus Semi-Analytical Solution).
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

338 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.72: Sketch of the problem

1.4. Advanced Examples 339

GEOS Documentation

Mesh

The following figure shows the mesh used for solving this mechanical problem:

Fig. 1.73: Generated mesh

The mesh was created with the internal mesh generator and parametrized in the InternalMesh XML tag. It con-
tains 10x10x10 eight-node brick elements in the x, y, and z directions respectively. Such eight-node hexahedral ele-
ments are defined as C3D8 elementTypes, and their collection forms a mesh with one group of cell blocks named here
cellBlockNames.
<Mesh>
<InternalMesh
name="mesh"
elementTypes="{ C3D8 }"
xCoords="{ 0, 0.9, 1.0 }"
yCoords="{ 0, 0.9, 1.0 }"
zCoords="{ 0, 0.9, 1.0 }"
nx="{ 9, 1 }"
ny="{ 9, 1 }"
nz="{ 9, 1 }"
cellBlockNames="{ cb-0_0_0, cb-1_0_0, cb-0_1_0, cb-1_1_0,
cb-0_0_1, cb-1_0_1, cb-0_1_1, cb-1_1_1 }"/>
(continues on next page)

340 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

</Mesh>

Solid mechanics solver

For the relaxation tests, pore pressure variations are neglected and subtracted from the analysis. Therefore, we define
a solid mechanics solver, called here mechanicsSolver. This solid mechanics solver (see Solid Mechanics Solver)
is based on the Lagrangian finite element formulation. The problem is run as QuasiStatic without considering
inertial effects. The computational domain is discretized by FE1, defined in the NumericalMethods section. We
use the targetRegions attribute to define the regions where the solid mechanics solver is applied. Here, we only
simulate mechanical deformation in one region named as Domain, whose mechanical properties are specified in the
Constitutive section.

Constitutive laws

A homogeneous domain with one solid material is assumed, and its mechanical properties are specified in the
Constitutive section:

Recall that in the SolidMechanics_LagrangianFEM section, rock is designated as the material in the com-
putational domain. Here, Visco Extended Drucker Prager model ViscoExtendedDruckerPrager is used to
simulate the viscoplastic behavior of rock. As for the material parameters, defaultInitialFrictionAngle,
defaultResidualFrictionAngle and defaultCohesion denote the initial friction angle, the residual friction

1.4. Advanced Examples 341

GEOS Documentation

angle, and cohesion, respectively, as defined by the Mohr-Coulomb failure envelope. As the residual friction angle
defaultResidualFrictionAngle is larger than the initial one defaultInitialFrictionAngle, a strain harden-
ing model is adopted, with a hardening rate given as defaultHardening="0.0005". Finally, relaxationTime is a
key parameter for characterizing the viscoplastic behavior of the solid called rock.
Constitutive parameters such as density, bulk modulus, and shear modulus are specified in the International System of
Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from several property
fields (time-series). We can collect either the entire collection of field properties or specified named sets. In this
example, stressCollection is specified to output the time history of stresses fieldName="rock_stress for the
selected subdomain objectPath="ElementRegions/Domain/cb8". And displacementCollection is defined to
output the time history of displacement fieldName="totalDisplacement" for the subset setNames="{ topPoint
}".

These two tasks are triggered using the Event management where PeriodicEvent are defined for these recurring
tasks. GEOS writes two files named after the string defined in the filename keyword and formatted as HDF5 files
(displacement_history.hdf5 and stress_history.hdf5). The TimeHistory file contains the collected time history infor-
mation from each specified time history collector. This information includes datasets for the simulation time, element
center or nodal position, and the time history information. We use a Python script to read and plot any specified subset
of the time history data for verification and visualization.

Initial and boundary conditions

The next step is to specify fields, including:

• The initial value (the stresses have to be initialized),
• The boundary conditions (the displacement control, lateral confining stress, and constraints of the outer bound-
aries have to be set).
In this example, we specify isotropic stresses (𝜎𝑥𝑥 = -10.0 MPa, 𝜎𝑦𝑦 = -10.0 MPa, and 𝜎𝑧𝑧 = -10.0 MPa,).
A compressive traction (𝑃𝑤 = -10.0 MPa) is applied on the domain laterals xpos (all faces on the x-side of the domain,
positive side) and ypos (all faces on the y-side of the domain, positive side).
The normal displacement (axialload) is instantaneously applied at the top surface zpos (all surfaces on the top) at
time 𝑡 = 0 s, and will gradually increase to a higher absolute value (-0.001) in 0.5 days to let the rock slab contract.
Then, it remains constant for 1.5 days to allow stress relaxation.
The remaining outer boundaries of the domain are subjected to roller constraints.
These boundary conditions are set up through the FieldSpecifications section.

342 Chapter 1. Table of Contents

GEOS Documentation

The lateral traction and compressive displacement have negative values due to the negative sign convention for com-
pressive stresses in GEOS.

<FieldSpecification
name="stressZZ"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/Domain"
(continues on next page)

1.4. Advanced Examples 343

Description of the case

We simulate the consolidation of a poroelastic slab between two rigid and impermeable plates subjected to a constant
normal force. The slab is assumed to be fully saturated, homogeneous, isotropic, and infinitely long in the y-direction.
We apply a uniform compressive load in the vertical direction. This force leads to a change of pore pressure and
mechanical deformations of the sample, evolving with time due to fluid diffusion and coupling effects. The numerical
model represents a plane strain deformation and lateral drainage without confinement, showing only a quarter of the
computational domain in the x-z plane (the rest follows by symmetry).
In this example, we set up and solve a poroelastic model to obtain the temporal and spatial solutions of pore pressure
(𝑝(𝑥, 𝑧, 𝑡)) and displacement field (𝑢𝑧 (𝑥, 𝑧, 𝑡)) for Mandel’s problem. These modeling predictions are validated against
corresponding analytical solution (Cheng and Detournay, 1988).
∞
sin𝛼𝑛 𝛼𝑛 2 𝑐𝑡
(︁ 𝛼 𝑥 )︁ (︂ )︂
𝑛
∑︁
𝑝(𝑥, 𝑧, 𝑡) = 2𝑝0 cos − cos𝛼𝑛 exp − 2
𝑛=1 𝑛
𝛼 − sin𝛼𝑛 cos𝛼𝑛 𝑎 𝑎
∞
[︃ )︂]︃
sin𝛼𝑛 cos𝛼𝑛 𝛼𝑛 2 𝑐𝑡
(︂
𝐹 (1 − 𝜈) 𝐹 (1 − 𝜈𝑢 ) ∑︁
𝑢𝑧 (𝑥, 𝑧, 𝑡) = − + exp − 2 𝑧
2𝐺𝑎 𝐺𝑎 𝑛=1 𝑛
𝛼 − sin𝛼𝑛 cos𝛼𝑛 𝑎
with 𝛼𝑛 denoting the positive roots of the following equation:
1−𝜈
tan𝛼𝑛 = 𝛼𝑛
𝜈𝑢 − 𝜈
Upon sudden application of the vertical load, the instantaneous overpressure (𝑝0 (𝑥, 𝑧)) and settlement (𝑢𝑧,0 (𝑥, 𝑧) and
𝑢𝑥,0 (𝑥, 𝑧)) across the sample are derived from the Skempton effect:
1
𝑝0 (𝑥, 𝑧) = 𝐵 (1 + 𝜈𝑢 ) 𝐹
3𝑎

346 Chapter 1. Table of Contents

GEOS Documentation

Deviatoric Stress (MPa)

10
8
6
4
2 GEOS
Analytical
0 0.10 0.05 0.00 0.05 0.10
Strain (%)

15.0
GEOS
12.5 Analytical
10.0 Initial Yield Surface
Residual Yield Surface
q (MPa)

7.5
5.0
2.5
0.00 2 4 6 8 10 12 14
p (MPa)

0.20 25.0
Axial Strain_GEOS
Axial Strain_Analytical 22.5
0.15
Axial Strain (%)

The two single-physics solvers are parameterized as explained in their corresponding documentation pages. We fo-
cus on the coupling solver in this example. The solver poroSolve uses a set of attributes that specifically describe
the coupling process within a poromechanical framework. For instance, we must point this solver to the desig-
nated fluid solver (here: SinglePhaseFlow) and solid solver (here: lagsolve). These solvers interact through the
porousMaterialNames="{ shale }" with all the constitutive models. We specify the discretization method (FE1,
defined in the NumericalMethods section), and the target regions (here, we only have one, Domain). More parameters
are required to characterize a coupling procedure (more information at Poromechanics Solver). In this way, the two
single-physics solvers will be simultaneously called and executed for solving Mandel’s problem here.

350 Chapter 1. Table of Contents

GEOS Documentation

Constitutive laws

For this problem, we simulate the poroelastic deformation of a slab under uniaxial compression. A homogeneous and
isotropic domain with one solid material is assumed, and its mechanical properties and associated fluid rheology are
specified in the Constitutive section. PorousElasticIsotropic model is used to describe the mechanical behav-
ior of shaleSolid when subjected to loading. The single-phase fluid model CompressibleSinglePhaseFluid is
selected to simulate the response of water upon consolidation.

All constitutive parameters such as density, viscosity, bulk modulus, and shear modulus are specified in the International
System of Units.

Time history function

In the Tasks section, PackCollection tasks are defined to collect time history information from fields. Either the
entire field or specified named sets of indices in the field can be collected. In this example, pressureCollection and
displacementCollection tasks are specified to output the time history of pore pressure fieldName="pressure"
and displacement field fieldName="totalDisplacement" across the computational domain.

<Tasks>
<PackCollection
name="pressureCollection"
(continues on next page)

1.4. Advanced Examples 351

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions/Domain/cb1"
fieldName="pressure"/>

These two tasks are triggered using the Event manager with a PeriodicEvent defined for these recurring tasks.
GEOS writes two files named after the string defined in the filename keyword and formatted as HDF5 files (displace-
ment_history.hdf5 and pressure_history.hdf5). The TimeHistory file contains the collected time history information
from each specified time history collector. This information includes datasets for the simulation time, element center,
and the time history information. A Python script is prepared to read and plot any specified subset of the time history
data for verification and visualization.

Initial and boundary conditions

Next, we specify two fields:

• The initial value (the displacements, effective stress, and pore pressure have to be initialized, corresponding to
the undrained response),
• The boundary conditions (the vertical displacement applied at the loaded boundary and the constraints of the
outer boundaries have to be set).
In this example, the analytical z-displacement is applied at the top surface (zpos) of computational domain to en-
force the rigid plate condition. The lateral surface (xpos) is traction-free and allows drainage. The remaining
parts of the outer boundaries are subjected to roller constraints. These boundary conditions are set up through the
FieldSpecifications section.
<FieldSpecifications>
<FieldSpecification
name="initialPressure"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/Domain/cb1"
fieldName="pressure"
scale="4934.86"/>

<FieldSpecification
name="initial_sigma_x"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="shaleSolid_stress"
component="0"
scale="4934.86"/>
<FieldSpecification
name="initial_sigma_y"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="shaleSolid_stress"
(continues on next page)

352 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

component="1"
scale="4934.86"/>
<FieldSpecification
name="initial_sigma_z"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="shaleSolid_stress"
component="2"
scale="4934.86"/>

<FieldSpecification
name="yconstraint"
objectPath="nodeManager"
fieldName="totalDisplacement"
(continues on next page)

1.4. Advanced Examples 353

GEOS Documentation

(continued from previous page)

component="1"
scale="0.0"
setNames="{ yneg, ypos }"/>

The parameters used in the simulation are summarized in the following table. Note that traction has a negative value,
due to the negative sign convention for compressive stresses in GEOS.

Symbol Parameter Unit Value

𝐾 Bulk Modulus [MPa] 66.667
𝐺 Shear Modulus [MPa] 40.0
𝐹 Force per Unit Length [N/m] -104
𝜑 Porosity [-] 0.375
𝐾𝑠 Grain Bulk Modulus [Pa] 1027
𝜌𝑓 Fluid density [kg/m3 ] 103
𝑐𝑓 Fluid compressibility [Pa-1 ] 4.4x10-10
𝜅 Permeability [m2 ] 10-12
𝜇 Fluid viscosity [Pa s] 10-3
2𝑎 Slab Length [m] 2.0
2𝑏 Slab Height [m] 2.0

Inspecting results

We request VTK-format output files and use Paraview to visualize the results. The following figure shows the distribu-
tion of pore pressure (𝑝(𝑥, 𝑧, 𝑡)) at 𝑡 = 10𝑠 within the computational domain.
The next figure shows the distribution of vertical displacement (𝑢𝑧 (𝑥, 𝑧, 𝑡)) at 𝑡 = 10𝑠.

354 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.77: Simulation result of pore pressure at 𝑡 = 10𝑠

1.4. Advanced Examples 355

GEOS Documentation

Fig. 1.78: Simulation result of vertical displacement at 𝑡 = 10𝑠

356 Chapter 1. Table of Contents

GEOS Documentation

The figure below compares the results from GEOS (marks) and the corresponding analytical solution (lines) for the pore
pressure along the x-direction and vertical displacement along the z-direction. GEOS reliably captures the short-term
Mandel-Cryer effect and shows excellent agreement with the analytical solution at various times.

1.2 t = 0.05s - Analytical Solution

1.4 t = 0.05s - Numerical Solution

Normalized Displacement, uz/uz = b, 0

t = 0.5s - Analytical Solution
1.0 1.2 t = 0.5s - Numerical Solution
Normalized Pressure, p/p0

t = 0.05s - Analytical Solution t = 5.0s - Analytical Solution

t = 0.05s - Numerical Solution t = 5.0s - Numerical Solution
0.8 t = 0.5s - Analytical Solution
t = 0.5s - Numerical Solution
1.0 t = 10.0s - Analytical Solution
t = 10.0s - Numerical Solution
t = 5.0s - Analytical Solution
0.6
t = 5.0s - Numerical Solution 0.8
t = 10.0s - Analytical Solution
t = 10.0s - Numerical Solution
0.6
0.4
0.4
0.2 0.2
0.00.0 0.2 0.4 0.6 0.8 1.0 0.00.0 0.2 0.4 0.6 0.8 1.0
Normalized Distance, x/a Normalized Distance, z/b

ò Note

The python script included above is used to generate the figure shown here. If you want to run this script to
verify your results, you will need to run the script from your output directory, and modify the path to the variables
xmlFile1Path and xmlFile1Path in the script to point to the location of the input files on your system.

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Thermoporomechanics
Thermoporoelastic Consolidation

Context
Thermoporoelastic consolidation is a typical fully coupled problem which involves solid deformation, fluid flow and
heat transfer in saturated porous media. In this example, we use the GEOS coupled solvers to solve a one-dimensional
thermoporoelastic consolidation problem with a non-isothermal boundary condition, and we verify the accuracy of the
results using the analytical solution provided in (Bai, 2005)
InputFile
This example uses no external input files and everything required is contained within two GEOS input files located at:

inputFiles/thermoPoromechanics/ThermoPoroElastic_consolidation_base.xml

inputFiles/thermoPoromechanics/ThermoPoroElastic_consolidation_benchmark_fim.xml

1.4. Advanced Examples 357

GEOS Documentation

Description of the case

We simulate the consolidation of 1D thermoporoelastic column subjected to a surface traction stress of 1 Pa applied on
the top surface, with a surface temperature of 50 degrees Celsius and a pore pressure of 0 Pa. The initial temperature
of the saturated soil is 0 degrees Celsius. The soil column is insulated and sealed everywhere, except at the top surface.
The problem setup is illustrated below.

Fig. 1.79: Sketch of the problem (taken from (Gao and Ghassemi, 2019)).

The coupled dynamics experienced by the system are described in (Gao and Ghassemi, 2019) and summarized below.
The model first experiences continuous settlement (contraction). Initially, the settlement caused by the drainage of the
fluid (effective stress increase) and the compression of the solid matrix is larger than the expansion due to the increase
of temperature in the region close to the surface on which a higher temperature is applied. As the temperature diffuses
further into the domain, it gradually rebounds (expansion) and reaches a final status.
For this example, we focus on the Solvers, the Constitutive, and the FieldSpecifications tags of the GEOS
input file.

Solvers

As demonstrated in this example, to setup a thermoporomechanical coupling, we need to define three different solvers
in the Solvers part of the XML file:
• the mechanics solver, a solver of type SolidMechanicsLagrangianSSLE called here solidMechSolver (more
information here: Solid Mechanics Solver),

358 Chapter 1. Table of Contents

GEOS Documentation

• the single-phase flow solver, a solver of type SinglePhaseFVM called here flowSolver (more information on
these solvers at Singlephase Flow Solver),

• the coupling solver (SinglePhasePoromechanics) that will bind the two single-physics solvers above, which
is named as thermoPoroSolver (more information at Poromechanics Solver).

To request the simulation of the temperature evolution, we set the isThermal flag of the coupling solver to 1. With
this choice, the degrees of freedom are the cell-centered pressure, the cell-centered temperature, and the mechanical
displacements at the mesh nodes. The governing equations consist of a mass conservation equation, an energy balance
equation, and a linear momentum balance equation. In the latter, the total stress includes both a pore pressure and a
temperature contribution. Note that in the coupling solver, we set the couplingType to FullyImplicit to require a
fully coupled, fully implicit solution strategy.

1.4. Advanced Examples 359

GEOS Documentation

Constitutive laws

A homogeneous and isotropic domain with one solid material is assumed, and its mechanical properties and associated
fluid rheology are specified in the Constitutive section. We use the constitutive parameters specified in (Bai, 2005)
listed in the following table.

Symbol Parameter Unit Value

𝐸 Young’s modulus [Pa] 6000.0
𝜈 Poisson’s ratio [-] 0.4
𝛼 Thermal expansion coef. [T^(-1)] 9.0x10-7
𝜑 Porosity [-] 0.20
𝑏 Biot’s coefficient [-] 1.0
𝜌𝐶 Heat capacity [J/(m^3.K)] 167.2x103
𝜇 Fluid viscosity [Pa.s] 1-3
𝑘𝑇 Thermal conductivity [J/(m.s.K)] 836
𝑘 Permeability [m^2] 4.0x10-9

The bulk modulus, the Young’s modulus, and the thermal expansion coefficient are specified in the ElasticIsotropic
solid model. Note that for now the solid density is constant and does not depend on temperature. Given that the gravity
vector has been set to 0 in the XML file, the value of the solid density is not used in this simulation.

The porosity and Biot’s coefficient (computed from the grainBulkModulus) appear in the BiotPorosity model. In
this model, the porosity is updated as a function of the strain increment, the change in pore pressure, and the change in
temperature.

The heat capacity is provided in the SolidInternalEnergy model. In the computation of the internal energy, the
referenceTemperature is set to the initial temperature.

The fluid density and viscosity are given in the ThermalCompressibleSinglePhaseFluid. Here, they are assumed
to be constant and do not depend on pressure and temperature.

<ThermalCompressibleSinglePhaseFluid
name="water"
defaultDensity="1000"
(continues on next page)

360 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

defaultViscosity="1e-3"
referencePressure="0.0"
referenceTemperature="0.0"
compressibility="0.0"
thermalExpansionCoeff="0.0"
viscosibility="0.0"
specificHeatCapacity="1.672e2"
referenceInternalEnergy="0.001"/>

Finally, the permeability and thermal conductivity are specified in the ConstantPermeability and
SinglePhaseConstantThermalConductivity, respectively.

Initial and boundary conditions

To complete the specification of the problem, we specify two types of fields:

• The initial values (the displacements, effective stress, and pore pressure have to be initialized),
• The boundary conditions at the top surface (traction, pressure, and temperature) and at the other boundaries
(zero-displacement).
This is done in the FieldSpecifications part of the XML file. The attribute initialCondition is set to 1 for the
blocks specifying the initial pressure, temperature, and effective stress.

<FieldSpecification
name="initialSigma_x"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/Domain/cb1"
(continues on next page)

1.4. Advanced Examples 361

GEOS Documentation

(continued from previous page)

fieldName="rockSolid_stress"
component="0"
scale="2.457"/>
<FieldSpecification
name="initialSigma_y"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/Domain/cb1"
fieldName="rockSolid_stress"
component="1"
scale="2.457"/>
<FieldSpecification
name="initialSigma_z"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions/Domain/cb1"
fieldName="rockSolid_stress"
component="2"
scale="2.457"/>

For the zero-displacement boundary conditions, we use the pre-defined set names xneg and xpos, yneg, zneg and zpos
to select the boundary nodes. Note that here, we have considered a slab in the y-direction, which is why a displacement
boundary condition is applied on zpos and not applied on ypos.

On the top surface, we impose the traction boundary condition and the non-isothermal boundary condition specified in
(Bai, 2005). We also fix the pore pressure to 0 Pa.

<Traction
name="traction"
objectPath="faceManager"
tractionType="normal"
(continues on next page)

362 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

scale="-1.0"
setNames="{ ypos }"
functionName="timeFunction"/>

Inspecting results

We request an output of the displacements, pressure, and temperature using the TimeHistory feature of GEOS. The
figures below compare the results from GEOS (dashed line) and the corresponding analytical solution (solid line) as a
function of time at different locations of the slab. We obtain a very good match, confirming that GEOS can accurately
capture the thermo-poromechanical coupling on this example. The first figure illustrates this good agreement for the
pressure evolution.
The second figure confirms the good match with the analytical solution for the temperature.
The third figure shows that GEOS is also able to match the vertical displacement (settlement) analytical solution.

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

1.4.2 Performance Benchmarks

Wellbore problem scaling on Frontier
The wellbore problem described here was used to test the weak scaling of GEOS on the Frontier supercomputer
<https://www.olcf.ornl.gov/frontier/> at Oak Ridge National Laboratory. The hardware details of the Frontier sys-
tem are described in the Frontier User Guide.
The wellbore problem consists of a single wellbore with an internal radius of 0.057m, a casing thickness of 0.006m,
with varying length and number elements depending level in the scaling study. There are 6 levels of scaling summarized
in the table below. The number of ranks used for each level is dependent on the physics solver applied, as the number
of degrees of freedom in the problem changes.

1.4. Advanced Examples 363

GEOS Documentation

1.0

0.8

0.6
Pressure [Pa]

0.4
GEOSX: z = 0.0 m
GEOSX: z = 4.2 m
0.2 GEOSX: z = 5.6 m
Analytical: z = 0.0 m
Analytical: z = 4.2 m
0.0 Analytical: z = 5.6 m
10 2 10 1 100 101 102 103 104 105
Time [s]

364 Chapter 1. Table of Contents

GEOS Documentation

320 GEOSX: z = 0.0 m

GEOSX: z = 4.2 m
GEOSX: z = 5.6 m
Analytical: z = 0.0 m
310 Analytical: z = 4.2 m
Analytical: z = 5.6 m
Temperature [K]

300

290

280

10 2 10 1 100 101 102 103 104 105

Time [s]

1.4. Advanced Examples 365

GEOS Documentation

GEOSX: z = 1.4 m
0.0004 GEOSX: z = 4.2 m
GEOSX: z = 5.6 m
Analytical: z = 1.4 m
Analytical: z = 4.2 m
0.0003 Analytical: z = 7 m
Displacement [m]

0.0002

0.0001

0.0000
10 2 10 1 100 101 102 103 104 105
Time [s]

366 Chapter 1. Table of Contents

GEOS Documentation

Level nr nt nz nelem
1 33 64 391 825,792
2 33 64 3125 6,600,000
3 66 128 6250 52,800,000
4 132 256 12500 422,400,000
5 264 512 25000 3,379,200,000
6 528 1024 50000 27,033,600,000

An image of the wellbore geometry is give below:

The scaling results for the wellbore problem applied to different physics models on the Frontier supercomputer are
shown below:

Mechanics

Fig. 1.80: Weak scaling results for the mechanics model on Frontier.

Single Phase Flow

Compositional Multiphase Flow

Running the Performance Study

To execute a performance study across different GPU configurations and problem levels for the wellbore problem on
the Frontier supercomputer, follow these steps:

Prerequisites

Ensure you have access to the Frontier system and that you have access to a valid job allocation account. For detailed
instructions on system access and environment setup, refer to the Frontier User Guide.

1.4. Advanced Examples 367

GEOS Documentation

Fig. 1.81: Weak scaling results for the single phase flow model on Frontier.

Fig. 1.82: Weak scaling results for the compositional multiphase flow model on Frontier.

368 Chapter 1. Table of Contents

GEOS Documentation

Directory Structure

The input files for different problem levels and configurations are organized under ${GEOS_DIR}/inputFiles/
wellboreECP/. Each physical problem (e.g., mechanics, compositionalMultiphaseFlow, singlePhaseFlow)
has its own directory containing multiple levels of problem refinement as described in the table above.

Dispatching Jobs

Use the dispatch.py script to automate the setup and submission of jobs for different levels of problem refinement
and physics models.
Usage:

python3 dispatch.py --acount [account_id] --binary [path_to_binary] --model [model_type]␣

˓→--levels

[specific_levels_to_run] --caliper [def]

• –account: Account name for running jobs on compute nodes.

• –binary: Path to the geos executable.
• –model: Physics model type, such as mechanics, singlePhaseFlow or compositionalMultiphaseFlow.
• –levels: (optional) Specific levels to run, e.g., 1 3 5. If omitted, all levels are run.
• –caliper: (optional) Turn on profiling with caliper.
Example:

python3 dispatch.py --binary /path/to/geos --model mechanics --levels 1 2 3

This command launches jobs for levels 1, 2, and 3 under the mechanics problem configuration.

Analyzing Output

After job completion, utilize the postprocess.py script to extract and plot performance metrics from the output files.
Usage:

python3 postprocess.py --model [model_type] --levels [specific_levels_to_plot]

• –model: Physics model type, such as mechanics, singlePhaseFlow or compositionalMultiphaseFlow.

• –levels: (optional) Specific levels to plot, e.g., 2 3 4 5. If omitted, results for all available levels are plotted.
Example:

python3 postprocess.py --model mechanics --levels 2 3 4 5

This command parses the latest output files in the mechanics directory, selected by the highest [jobID]. It matches
files with the pattern [machine_name]-[jobID]-[model_type]-geom[level].out, extracting average execution
times per non-linear step for the following phases: GEOS, matrix creation, Hypre setup, and Hypre solve.

Note

The job scripts designed for Frontier are likely compatible with other Slurm-based systems, making them reusable
across different high-performance computing environments with minimal adjustments.

1.4. Advanced Examples 369

GEOS Documentation

1.4.3 Application Studies

1.4.4 pygeosx Examples
The pygeosx — GEOS in Python enables users to query and/or manipulate the GEOS datastructure with python in
real-time. The following examples show how to use pygeosx interface and the supplemental pygeosx_tools_package.
A quick warning: these examples are recommended for advanced users only. The pygeosx interface requires users
to be familiar with the GEOS datastructure, and can trigger the code to crash if an object/variable is inappropriately
modified.

In Situ Data Monitor

Objectives
At the end of this example you will know:
• how to run a problem using the pygeosx interface,
• how to process advanced xml features using pygeosx,
• how to extract and monitor values within the GEOS datastructure in real-time
Input files
This example requires two input xml files and one python script located at:

GEOS/examples/pygeosxExamples/hydraulicFractureWithMonitor

Description of the case

This example is derived from this basic example: Hydraulic Fracturing, which solves for the propagation of a single
hydraulic fracture within a heterogeneous reservoir. The pygeosx interface is used to monitor the maximum hydraulic
aperture and fracture extents over time.

XML Configuration

The input xml file for this example requires some modification in order to work with pygeosx. First, we use the advanced
xml input features to include the base problem and override the table_root parameter that points to the table files. Note
that these paths will need to be updated if you run this problem outside of the example directory.

</Included>

Next, we add a new entry to the output block Python and an entry in the Events block. Whenever the python event is
triggered, GEOS will pause and return to the controlling python script (in this case, every 10 cycles).

370 Chapter 1. Table of Contents

GEOS Documentation

Python Script

Problems that use the pygeosx interface are driven by a custom python script. To begin, we import a number of packages
and check whether this is a parallel run. The custom packages include pygeosx, which provides an interface to GEOS,
and pygeosx_tools, which provides a number of common tools for working with the datastructure and dealing with
parallel communication.

from mpi4py import MPI

import pygeosx
from pygeosx_tools import wrapper
from geosx_xml_tools.main import preprocess_parallel
import matplotlib.pyplot as plt

In the next step, we apply the xml preprocessor to resolve the advanced xml features. Note that this step will modify
the input arguments to reflect the location of the compiled xml file, which is processed directly by GEOS. The script
then initializes GEOS and receives the problem handle, which is the scripts view into the datastructure. There is an
opportunity to interact with the GEOS before the initial conditions are set, which we do not use in this example.

# Get the MPI rank

comm = MPI.COMM_WORLD
rank = comm.Get_rank()

# Initialize the code and set initial conditions

args = preprocess_parallel()
problem = pygeosx.initialize(rank, args)
pygeosx.apply_initial_conditions()

To extract information from the problem, you need to know the full path (or ‘key’) to the target object. These keys can
be quite long, and can change depending on the xml input. In the next step, we use a method from the pygeosx_tools
package to search for these keys using a list of keywords. If the keys are known beforehand, then this step could be
skipped. Note that these functions will throw an error if they do not find a matching key, or if they find multiple
matching keys.

# Rather than specifying the wrapper paths explicitly,

# search for them using a set of filters
fracture_location_key = wrapper.get_matching_wrapper_path(problem, ['Fracture',
˓→'elementCenter'])

fracture_aperture_key = wrapper.get_matching_wrapper_path(problem, ['Fracture',

˓→'effectiveAperture'])

Next, we setup a dictionary that will allow us to use pygeosx_tools to automatically query the problem. The root level
of this dictionary contains the target keys (fracture location and aperture) and the required time key. These each point to

1.4. Advanced Examples 371

GEOS Documentation

a sub-dictionary that holds an axis label, a scale factor, and an empty list to hold the time history. The target dictionaries
also hold an entry fhandle, which contains a matplotlib figure handle that we can use to display the results.

# Setup values to record

records = {fracture_location_key: {'label': 'Fracture Extents (m)',
'scale': 1.0,
'history': [],
'fhandle': plt.figure()},
fracture_aperture_key: {'label': 'Aperture (mm)',
'scale': 1e3,
'history': [],
'fhandle': plt.figure()},
'time': {'label': 'Time (min)',
'scale': 1.0 / 60.0,
'history': []}}

After setting up the problem, we enter the main problem loop. Upon calling pygeosx.run(), the code will execute until
a Python event is triggered in the Event loop. At those points, we have the option to interact with the problem before
continuing processing. Here, we use pygeosx_tools to query the datastructure and occasionaly plot the results to the
screen.

# Setup values to record

Manual Query

To obtain and manually inspect an object in the problem, you can use the methods in pygeosx_tools.wrapper. These are
designed to handle any parallel communication that may be required in your analysis. For example, to get the fracture
aperture as a numpy array, you could call:

from pygeosx_tools import wrapper

# (problem initialization / configuration)

# Grab aperture as a numpy array, using three different approaches

# Local copy (the write flag indicates that we do not plan to modify the result)
aperture_local = wrapper.get_wrapper(problem, fracture_aperture_key, write_flag=False)

# Global copy on the root rank

aperture_global = wrapper.gather_wrapper(problem, fracture_aperture_key)

# Global copy on the all ranks

aperture_global = wrapper.allgather_wrapper(problem, fracture_aperture_key)

372 Chapter 1. Table of Contents

GEOS Documentation

Running the Problem

To run the problem, you must use the specific version of python where pygeosx is installed. This is likeley located here:

GEOS/[build_dir]/lib/PYGEOSX/bin/python

Note that you may need to manually install the pygeosx_tools package (and its pre-requisites) into this python distribu-
tion. To do so, you can run the following:

cd GEOS/[build_dir]/lib/PYGEOSX/bin
pip install --upgrade ../../../../src/coreComponents/python/modules/pygeosx_tools_
˓→package/

To run the code, you will call the pygeosx run script with python, and supply the typical geosx command-line arguments
and any parallel arguments. For example:

# Load the correct python environment

# If you are not using a bash shell, you may need to target one of
# the other activation scripts
source GEOS/[build_dir]/lib/PYGEOSX/bin/activate

# Move to the correct directory and run

cd /path/to/problem
srun -n 36 -ppdebug python hydraulicFractureWithMonitor.py -i hydraulicFracture.xml -x 6␣
˓→-y 2 -z 3 -o hf_results

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.
For more details
• More on advanced xml features, please see Advanced XML Features.
• More on the pygeosx interface, please see pygeosx — GEOS in Python.

Initial Condition Modification

Objectives
At the end of this example you will know:
• how to modify GEOS arrays using pygeosx
• handle parallel communication with pygeosx_tools
Input files
This example requires an input xml and python script located at:

GEOS/examples/pygeosxExamples/sedovWithStressFunction

1.4. Advanced Examples 373

GEOS Documentation

Description of the case

This example is derived from the sedov integrated test (GEOS/src/coreComponents/physicsSolvers/solidMechanics/integratedTests/sedov.x

which looks at the propagation of elastic waves due to an initial stress field. The pygeosx interface is used to modify
the initial conditions of the problem to something of our choosing.

XML Configuration

As before, the basic sedov input xml file for this example requires some modification in order to work with pygeosx.
First, we use the advanced xml input features to include the base problem (this path may need to be updated, depending
on where you run the problem).

Next, we add a new entry to the output block Python and an entry in the Events block. Whenever the python event is
triggered, GEOS will pause and return to the controlling python script.

Python Script

Similar to the previous example, the python script begins by importing the required packages, applying the xml pre-
processor, GEOS initialization, and key search.

# Get the MPI rank

comm = MPI.COMM_WORLD
rank = comm.Get_rank()

# Initialize the code and set initial conditions

args = preprocess_parallel()
problem = pygeosx.initialize(rank, args)
pygeosx.apply_initial_conditions()

# Rather than specifying the wrapper paths explicitly,

# search for them using a set of filters
location_key = wrapper.get_matching_wrapper_path(problem, ['Region2', 'elementCenter
˓→'])

stress_key = wrapper.get_matching_wrapper_path(problem, ['Region2', 'shale', 'stress

˓→'])

ghost_key = wrapper.get_matching_wrapper_path(problem, ['Region2', 'cb1', 'ghostRank

˓→'])

374 Chapter 1. Table of Contents

GEOS Documentation

The next steps rely on a python function that we use to set stress. The argument to this function, x, is assumed to be a
numpy array of element centers:

def stress_fn(x):
"""
Function to set stress values

Args:
x (np.ndarray) the element centers

Returns:
np.ndarray: stress values
"""
R = x[:, 0]**2 + x[:, 1]**2 + x[:, 2]**2
return np.sin(2.0 * np.pi * R / np.amax(R))

In the following section, we zero out the initial stress and then set it based on stress_fn. While doing this, we use
wrapper.print_global_value_range to check on the process.

# Print initial stress

wrapper.print_global_value_range(problem, stress_key, 'stress')

# Zero out stress

wrapper.set_wrapper_to_value(problem, stress_key, 0.0)
wrapper.print_global_value_range(problem, stress_key, 'stress')

# Set stress via a function

wrapper.set_wrapper_with_function(problem, stress_key, location_key, stress_fn,␣
˓→target_index=0)

wrapper.set_wrapper_with_function(problem, stress_key, location_key, stress_fn,␣

˓→target_index=1)

wrapper.set_wrapper_with_function(problem, stress_key, location_key, stress_fn,␣

˓→target_index=2)

wrapper.print_global_value_range(problem, stress_key, 'stress')

Finally, we run the simulation. As an optional step, we extract numpy arrays from the datastructure using different
parallel approaches:

# Run the code

while pygeosx.run() != pygeosx.COMPLETED:
wrapper.print_global_value_range(problem, stress_key, 'stress')

# Gather/allgather tests
tmp = wrapper.gather_wrapper(problem, stress_key)
print(wrapper.rank, 'gather', np.shape(tmp), flush=True)

tmp = wrapper.allgather_wrapper(problem, stress_key)

print(wrapper.rank, 'allgather', np.shape(tmp), flush=True)

tmp = wrapper.allgather_wrapper(problem, stress_key, ghost_key=ghost_key)

print(wrapper.rank, 'allgather_ghost_filtered', np.shape(tmp), flush=True)

1.4. Advanced Examples 375

GEOS Documentation

Running the Problem

To run the problem, you must use the specific version of python where pygeosx is installed. This is likeley located here:

GEOS/[build_dir]/lib/PYGEOSX/bin/python

Note that you may need to manually install the pygeosx_tools package (and its pre-requisites) into this python distribu-
tion. To do so, you can run the following:

cd GEOS/[build_dir]/lib/PYGEOSX/bin
pip install --upgrade ../../../../src/coreComponents/python/modules/pygeosx_tools_
˓→package/

To run the code, you will call the pygeosx run script with python, and supply the typical geosx command-line arguments
and any parallel arguments. For example:

# Load the correct python environment

# If you are not using a bash shell, you may need to target one of
# the other activation scripts
source GEOS/[build_dir]/lib/PYGEOSX/bin/activate

# Move to the correct directory and run

cd /path/to/problem
python run_sedov_problem.py -i modified_sedov.xml -o results

To go further

Feedback on this example

1.5 User Guide

Welcome to the GEOS user guide.

1.5.1 Input Files

XML
GEOS is configured via one (or more) Extensible Markup Language (XML) files. These files contain a set of elements
and attributes that closely follow the internal datastructure of GEOS. When running GEOS, these files are specified
using the -i argument:

geosx -i input.xml

XML Components

The following illustrates some of the key features of a GEOS-format xml file:

376 Chapter 1. Table of Contents

GEOS Documentation

<?xml version="1.0" ?>

The two basic components of an xml file are blocks, which are specified using angle brackets (“<BlockA> </BlockA>”),
and attributes that are attached to blocks (attributeName=”attributeValue”). Block and attributes can use any ASCII
character aside from <, &, ‘, and “ (if necessary, use <, &, ', or "). Comments are indicated as
follows: <!– Some comment –>.
At the beginning of a GEOS input file, you will find an optional xml declaration (<?xml version=”1.0” ?>) that is used
to indicate the format to certain text editors. You will also find the root Problem block, where the GEOS configuration
is placed. Note that, aside from these elements and commented text, the xml format requires that no other objects exist
at the first level.
In the example above, there is a single element within the Problem block: BlockA. BlockA has an attribute someAttribute,
which has a value of 1.234, and has three children: a commented string “Some comment” and two instances of BlockB.
The name attribute is required for blocks that allow multiple instances, and should include a unique string to avoid
potential errors. Where applicable these blocks will be executed in the order in which they are specified in input file.

Input Validation
The optional xmlns:xsi and xsi:noNamespaceSchemaLocation attributes in the Problem block can be used to indicate
the type of document and the location of the xml schema to the text editor:

The schema contains a list of xml blocks and attributes that are supported by GEOS, indicates whether a given object is
optional or required, and defines the format of the object (string, floating point number, etc.). A copy of the schema is
included in the GEOS source code (/path/to/GEOS/src/coreComponents/schema/schema.xsd). It can also be generated
using GEOS: geosx -s schema.xsd
Many text editors can use the schema to help in the construction of an xml file and to indicate whether it is valid. Using
a validation tool is highly recommended for all users. The following instructions indicate how to turn on validation for
a variety of tools:

xmllint

xmllint is a command-line tool that is typically pre-installed on UNIX-like systems. To check whether an input file is
valid, run the following command:
xmllint –schema /path/to/schema.xsd input_file.xml

1.5. User Guide 377

GEOS Documentation

Sublime Text

We recommend using the Exalt or SublimeLinter_xmllint plug-ins to validate xml files within sublime. If you have not
done so already, install the sublime Package Control. To install the package, press ctrl + shift + p, type and select
Package Control: Install Package, and search for exalt or SublimeLinter / SublimeLinter-xmllint.
Note that, depending on the circumstances, these tools may indicate only a subset of the validation errors at a given
time. Once resolved, the tools should re-check the document to look for any additional errors.
As an additional step for SublimLinter-xmllint, you will need to add a linter configuration. To do so, go to Prefer-
ences/Package Settings/SublimeLinter/Settings. In the right-hand side of the new window, add the xmllint configura-
tion:

{
"linters": {
"xmllint":
{
"args": "--schema /path/to/schema.xsd",
"styles": [
{
"mark_style": "fill",
"scope": "region.bluish",
"types": ["error"],
"icon": "stop",
}
]
},
}
}

VS Code

We recommend using the XML for validating xml files. After installing this extension, you can associate GEOS format
xml files by adding the following entry to the user settings file (replacing systemId with the correct path to the schema
file):

{
"xml.fileAssociations": [

{
"pattern": "**.xml",
"systemId": "/path/to/GEOS/src/coreComponents/schema/schema.xsd"
}
]
}

Eclipse

The Eclipse Web Develop Tools includes features for validating xml files. To install them, go to Help -> Eclipse Mar-
ketplace, search for the Eclipse Web Developer Tools, install the package, and restart Eclipse. Finally, configure the
xml validation preferences under Window -> Preferences -> XML -> XML Files -> Validation. Eclipse will automat-
ically fetch the schema, and validate an active xml file. The editor will highlight any lines with errors, and underline
the specific errors.

378 Chapter 1. Table of Contents

GEOS Documentation

GEOS XML Tools

The geosx_xml_tools package, which is used to enable advanced features such as parameters, symbolic math, etc.,
contains tools for validating xml files. To do so, call the command-line script with the -s argument, i.e.: preprocess_xml
input_file.xml -s /path/to/schema.xsd. After compiling the final xml file, pygeosx will fetch the designated schema,
validate, and print any errors to the screen.
Note: Attributes that are using advanced xml features will likely contain characters that are not allowed by their cor-
responding type pattern. As such, file editors that are configured to use other validation methods will likely identify
errors in the raw input file.

XML Schema
An XML schema definition (XSD) file lays out the expected structure of an input XML file. During the build process,
GEOS automatically constructs a comprehensive schema from the code’s data structure, and updates the version in the
source (GEOS/src/coreComponents/schema/schema.xsd).

Schema Components

The first entry in the schema are a set of headers the file type and version. Following this, the set of available simple
types for attributes are laid out. Each of these includes a variable type name, which mirrors those used in the main
code, and a regular expression, which is designed to match valid inputs. These patterns are defined and documented in
rtTypes (in DataTypes.hpp. The final part of the schema is the file layout, beginning with the root Problem. Each
complex type defines an element, its children, and its attributes. Each attribute defines the input name, type, default
value, and/or usage. Comments preceding each attribute are used to relay additional information to the users.

Automatic Schema Generation

A schema may be generated by calling the main code with the -s argument , e.g.: geosx -s schema.xsd (Note: this
is done automatically during the bulid process). To do this, GEOS does the following:
1) Initialize the GEOS data structure.
2) Initialize objects that are registered to catalogs via ManagedGroup::ExpandObjectCatalogs().
3) Recursively write element and attribute definitions to the schema using information stored in GEOS groups and
wrappers.
4) Define any expected deviations from the schema via ManagedGroup::SetSchemaDeviations().

Advanced XML Features

The geosx_xml_tools python package adds a set of advanced features to the GEOS xml format: units, param-
eters, and symbolic expressions. See`Python Tools Setup <https://geosx-geosx.readthedocs-hosted.com/projects/
geosx-geospythonpackages/en/latest/>`_ for details on setup instructions, and XML Parser Documentation for package
API details.

Usage

An input file that uses advanced xml features requires preprocessing before it can be used with GEOS. The preprocessor
writes a compiled xml file to the disk, which can be read directly by GEOS and serves as a permanent record for the
simulation. There are three ways to apply the preprocessor:
1) Automatic Preprocessing: Substituting geosx for geosx_preprocessed when calling the code will automatically
apply the preprocessor to the input xml file, and then pass the remaining arguments to GEOS. With this method,
the compiled xml files will have the suffix ‘.preprocessed’. Before running the code, the compiled xml file will
also be validated against the xml schema.

1.5. User Guide 379

GEOS Documentation

# Serial example
geosx_preprocessed -i input.xml

# Parallel example
srun -n 2 geosx_preprocessed -i input.xml -x 2

2) Manual Preprocessing: For this approach, xml files are preprocessed manually by the user with the prepro-
cess_xml script. These files can then be submitted to GEOS separately:

# The -c argument is used to manually specify the compiled name

preprocess_xml -i input.xml -c input.xml.processed
geosx -i input.xml.processed

# Otherwise, a random name will be chosen by the tool

compiled_input=$(preprocess_xml input.xml)
geosx -i $compiled_input

3) Python / pygeosx: The preprocessor can also be applied directly in python or in pygeosx simulations. An example
of this is method is provided here: GEOS/examples/pygeosxExamples/hydraulicFractureWithMonitor/.
Each of these options support specifying multiple input files via the command line (e.g. geosx_preprocessed
-i input_a.xml -i input_b.xml). They also support any number of command-line parameter overrides (e.g.
geosx_preprocessed -i input_a.xml -p parameter_a alpha -p parameter_b beta).

Included Files

Both the XML preprocessor and GEOS executable itself provide the capability to build complex multi-file input decks
by including XML files into other XML files.
The files to be included are listed via the <Included> block. There maybe any number of such blocks. Each block
contains a list of <File name=”. . . ”/> tags, each indicating a file to include. The name attribute must contain either
an absolute or a relative path to the included file. If the path is relative, it is treated as relative to the location of the
referring file. Included files may also contain includes of their own, i.e. it is possible to have a.xml include b.xml which
in turn includes c.xml.

ò Note

When creating multi-file input decks, it is considered best practice to use relative file paths. This applies both to
XML includes, and to other types of file references (for example, table file names). Relative paths keep input decks
both relocatable within the file system and sharable between users.

XML preprocessor’s merging capabilities are more advanced than GEOS built-in ones. Both are outlined below.

XML preprocessor

The merging approach is applied recursively, allowing children to include their own files. Any potential conflicts are
handled via the following scheme:
• Merge two objects if:
– At the root level an object with the matching tag exists.
– If the “name” attribute is present and an object with the matching tag and name exists.
– Any preexisting attributes on the object are overwritten by the donor.

380 Chapter 1. Table of Contents

GEOS Documentation

• Otherwise append the XML structure with the target.

GEOS

GEOS’s built-in processing simply inserts the included files’ content (excluding the root node) into the XML element
tree, at the level of <Included> tag. Partial merging is handled implicitly by GEOS’s data structure, which treats
repeated top-level XML blocks as if they are one single block. This is usually sufficient for merging together top-level
input sections from multiple files, such as multiple <FieldSpecifications> or <Events> sections, but more complex
cases may require the use of preprocessor.

ò Note

While GEOS’s XML processing is capable of handling any number of <Included> block at any level, the XML
schema currently produced by GEOS only allows a single such block, and only directly within the <Problem> tag.
Inputs that use multiple blocks or nest them deeper may run but will fail to validate against the schema. This is a
known discrepancy that may be fixed in the future.

Parameters

Parameters are a convenient way to build a configurable and human-readable input XML. They are defined via a block
in the XML structure. To avoid conflicts with other advanced features, parameter names can include upper/lower case
letters and underscores. Parameters may have any value, including:
• Numbers (with or without units)
• A path to a file
• A symbolic expression
• Other parameters
• Etc.
They can be used as part of any input xml attribute as follows:
• $x_par$ (preferred)
• $x_par
• $:x_par
• $:x_par$
Attributes can be used across Included files, but cannot be used to set the names of included files themselves. The
following example uses parameters to set the root path for a table function, which is then scaled by another parameter:

<FieldSpecifications>
<SourceFlux
name="sourceTerm"
(continues on next page)

1.5. User Guide 381

GEOS Documentation

(continued from previous page)

objectPath="ElementRegions/Region1/block1"
scale="$flow_scale$"
functionName="flow_rate"
setNames="{ source }"/>
</FieldSpecifications>

Any number of parameter overrides can be issued from the command line using the -p name value argument in the
preprocessor script. Note that if the override value contains any spaces, it may need to be surrounded by quotation
marks (-p name “paramter with spaces”).

Units

The units for any input values to GEOS can be in any self-consistent system. In many cases, it is useful to override
this behavior by explicitly specifying the units of the input. These are specified by appending a valid number with a
unit definition in square braces. During pre-processing, these units are converted into base-SI units (we plan to support
other unit systems in the future).
The unit manager supports most common units and SI prefixes, using both long- and abbreviated names (e.g.: c, centi,
k, kilo, etc.). Units may include predefined composite units (dyne, N, etc.) or may be built up from sub-units using a
python syntax (e.g.: [N], [kg*m/s**2]). Any (or no) amount of whitespace is allowed between the number and the unit
bracket. The following shows a set of parameters with units specified:

Please note that the preprocessor currently does not check whether any user-specified units are appropriate for a given
input or symbolic expression.

Symbolic Expressions

Input XML files can also include symbolic mathematical expressions. These are placed within pairs of backticks (`),
and use a limited python syntax. Please note that parameters and units are evaluated before symbolic expressions.
While symbolic expressions are allowed within parameters, errors may occur if they are used in a way that results in
nested symbolic expressions. Also, note that residual alpha characters (e.g. sin() are removed before evaluation for
security. The following shows an example of symbolic expressions:

<Parameters>
<Parameter name="a" value="2[m]"/>
<Parameter name="b" value="1.2 [cm]"/>
<Parameter name="c" value="3"/>
(continues on next page)

382 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Validation

Unmatched special characters ($, [, `, etc.) in the final xml file indicate that parameters, units, or symbolic math were
not specified correctly. If the prepreprocessor detects these, it will throw an error and exit. Additional validation of the
compiled files can be completed with preprocess_xml by supplying the -s argument and the path to the GEOS schema.

1.5.2 Meshes
The purpose of this document is to explain how users and developers interact with mesh data. This section describes
how meshes are handled and stored in GEOS.
There are two possible methods for generating a mesh: either by using GEOS’s internal mesh generator (for Cartesian
meshes only), or by importing meshes from various common mesh file formats. This latter options allows one to
work with more complex geometries, such as unstructured meshes comprised of a variety of element types (polyhedral
elements).

Internal Mesh Generation

Basic Example

The Internal Mesh Generator allows one to quickly build simple cartesian grids and divide them into several regions.
The following attributes are supported in the input block for InternalMesh:

1.5. User Guide 383

GEOS Documentation

XML Element: InternalMesh

Name Type De- Description

fault
cell- group- re- Names of each mesh block
Block- NameRef_array
quired
Names
ele- string_array
re- Element types of each mesh block. Use “C3D8” for linear brick element. Possible values
ment- quired are: Vertex, BEAM, C2D3, C2D4, Polygon, C3D4, C3D5, C3D6, C3D8, PentagonalPrism,
Types HexagonalPrism, HeptagonalPrism, OctagonalPrism, NonagonalPrism, DecagonalPrism,
HendecagonalPrism, Polyhedron.
name group- re- A name is required for any non-unique nodes
Name quired
nx inte- re- Number of elements in the x-direction within each mesh block
ger_arrayquired
ny inte- re- Number of elements in the y-direction within each mesh block
ger_arrayquired
nz inte- re- Number of elements in the z-direction within each mesh block
ger_arrayquired
posi- real64 1e- A position tolerance to verify if a node belong to a nodeset
tion- 10
Tol-
er-
ance
tri- inte- 0 Pattern by which to decompose the hex mesh into wedges
an- ger
glePat-
tern
xBias real64_array{1} Bias of element sizes in the x-direction within each mesh block (dx_left=(1+b)*L/N,
dx_right=(1-b)*L/N)
xCo- real64_array re- x-coordinates of each mesh block vertex
ords quired
yBias real64_array{1} Bias of element sizes in the y-direction within each mesh block (dy_left=(1+b)*L/N,
dx_right=(1-b)*L/N)
yCo- real64_array re- y-coordinates of each mesh block vertex
ords quired
zBias real64_array{1} Bias of element sizes in the z-direction within each mesh block (dz_left=(1+b)*L/N,
dz_right=(1-b)*L/N)
zCo- real64_array re- z-coordinates of each mesh block vertex
ords quired
In- node XML Element: InternalWell
ter-
nal-
Well
Re- node XML Element: Region
gion
VTK- node XML Element: VTKWell
Well

The following is an example XML <mesh> block, which will generate a vertical beam with two CellBlocks (one in
red and one in blue in the following picture).

384 Chapter 1. Table of Contents

GEOS Documentation

• name the name of the mesh body

• elementTypes the type of the elements that will be generated.
• xCoord List of x coordinates of the boundaries of the CellBlocks
• yCoord List of y coordinates of the boundaries of the CellBlocks
• zCoord List of z coordinates of the boundaries of the CellBlocks
• nx List containing the number of cells in x direction within the CellBlocks
• ny List containing the number of cells in y direction within the CellBlocks
• nz List containing the number of cells in z direction within the CellBlocks
• cellBlockNames List containing the names of the CellBlocks

1.5. User Guide 385

GEOS Documentation

Mesh Bias

The internal mesh generator is capable of producing meshes with element sizes that vary smoothly over space. This is
achieved by specifying xBias, yBias, and/or zBias fields. (Note: if present, the length of these must match nx, ny,
and nz, respectively, and each individual value must be in the range (-1, 1).)
For a given element block, the average element size will be
𝑥𝐶𝑜𝑜𝑟𝑑𝑠[𝑖 + 1] − 𝑥𝐶𝑜𝑜𝑟𝑑𝑠[𝑖]
𝑑𝑥𝑎𝑣𝑒𝑟𝑎𝑔𝑒 [𝑖] = ,
𝑛𝑥[𝑖]
the element on the left-most side of the block will have size

𝑑𝑥𝑙𝑒𝑓 𝑡 [𝑖] = (1 + 𝑥𝐵𝑖𝑎𝑠[𝑖]) · 𝑑𝑥𝑎𝑣𝑒𝑟𝑎𝑔𝑒 [𝑖],

materialList="{fluid1, rock, relperm}"/>

<CellElementRegion name="Barrier"
cellBlocks="{cb-0_1_0, cb-1_1_0, cb-1_1_1, cb-1_0_1, cb-1_0_2, cb-0_0_
˓→2, cb-0_0_3, cb-0_1_3}"

materialList="{}"/>
</ElementRegions>

Thus, the generated mesh will be :

Note that CellBlocks are ordered following the natural IJK logic, with indices increasing first in I (x-direction), then
in J (y-direction) and last in K (z-direction).

Using an External Mesh

Supported Formats

GEOS provides features to run simulations on unstructured meshes. It uses VTK to read the external meshes and its
API to write it into the GEOS mesh data structure.
The supported mesh elements for volume elements consist of the following:
• 4-node tetrahedra,
• 5-node pyramids,
• 6-node wedges,
• 8-node hexahedra,
• n-gonal prisms (n = 7, . . . , 11).
The mesh can be divided in several regions. These regions are intended to support different physics or to define different
constitutive properties. By default, we use the attribute field to define the regions.

Importing the Mesh

Importing regions

Several blocks are involved to import an external mesh into GEOS, defined in the XML input file. These are the <Mesh>
block and the <CellElementRegions> block.
The mesh block has the following syntax:

<Mesh>
<VTKMesh
name="MyMeshName"
logLevel="1"
(continues on next page)

1.5. User Guide 389

GEOS Documentation

(continued from previous page)

file="/path/to/the/mesh/file.vtk"
regionAttribute="myAttribute" />
</Mesh>

..note::
We advise users to use absolute path to the mesh file, and recommend the use of a logLevel of 1 or more to
obtain some information about the mesh import, including the list of regions that are imported with their names,
which is particularly useful to fill the field of the CellElementRegions block (see below). Some information
about the imported surfaces is also provided.
GEOS uses ElementRegions to support different physics or to define different constitutive properties. The
ElementRegions block can contain several CellElementRegion blocks. A CellElementRegion is defined as a
set of cell-blocks, which are sets of elements with the same element geometry, defined within the cellBlocks at-
tribute.
The naming of cell-blocks depends on if the mesh contains a data array which has the same value as the
regionAttribute of the VTKMesh (which is attribute by default). This attribute is used to define regions in the
vtu file and assign the cells to a given region.
For now, loaded regions has the following limitations: - The regionAttribute can only refer to integer values (no
texts), - Each element can belong to only one region.

In GEOS, there are three different ways to select cellBlocks in a CellElementRegion:

• Using a list of the desired regionAttribute values. I.e. "{ 1, 2 }" selects all the cell-blocks of the
regionAttribute 1 and 2.
• Using a list of the exact cell-blocks names from the mesh to contain in this CellElementRegion. I.e. {
1_tetrahedra, 1_pyramid, 1_hexahedra, 2_tetrahedra, 2_pyramid, 2_hexahedra }
• Using a list of fnmatch patterns to match cell-block names to add them in this CellElementRegion. I.e. { *
} selects every elements, { 1_* } selects the { 1_tetrahedra, 1_pyramid, 1_hexahedra } cell-blocks.
In the example presented above, the mesh is is composed of two regions. Each region contains 4 element types.

390 Chapter 1. Table of Contents

GEOS Documentation

• If the vtu file contains an attribute equals to the regionAttribute of the VTKMesh, then all cellBlock are
named with this convention: regionAttribute_elementType. Let’s assume that the top region of the exemple
above has myAttribute to 1, and that the bottom region has myAttribute to 2,
– If we want the CellElementRegion to contain all the cells, we write:

<!-- Method one: Use `*` to match all cellBlock names automatically.
"{ [1-2]_* }" would have an equivalent result (range selection). --
˓→>

<ElementRegions>
<CellElementRegion
name="MyRegion"
cellBlocks="{ 1, 2 }"
materialList="{ water, rock }" />
</ElementRegions>

<ElementRegions>
<CellElementRegion
name="MyRegion"
cellBlocks="{ 1_hexahedra, 1_wedges, 1_tetrahedra, 1_pyramids, 2_hexahedra, 2_
˓→wedges, 2_tetrahedra, 2_pyramids }"

materialList="{ water, rock }" />

</ElementRegions>

– If we want two CellElementRegion with the top and bottom regions separated, we write:

<ElementRegions>
<CellElementRegion
name="Top"
cellBlocks="{ 1_* }"
(continues on next page)

1.5. User Guide 391

GEOS Documentation

(continued from previous page)

materialList="{ water, rock }"/>
<CellElementRegion
name="Bot"
cellBlocks="{ 2_* }"
materialList="{ water, rock }" />
</ElementRegions>

<ElementRegions>
<CellElementRegion
name="Top"
cellBlocks="{ 1_hexahedra, 1_wedges, 1_tetrahedra, 1_pyramids }"
materialList="{ water, rock }"/>
<CellElementRegion
name="Bot"
cellBlocks="{ 2_hexahedra, 2_wedges, 2_tetrahedra, 2_pyramids }"
materialList="{ water, rock }" />
</ElementRegions>

• If the vtu file does not contain any region attribute field, then all the cells are grouped in a single region, and
cellBlock names consist of just the cell types (hexahedra, wedges, tetrahedra, etc). Then in the exemple above,
the ElementRegions can be defined as bellow:

<ElementRegions>
<CellElementRegion
name="MyRegion"
cellBlocks="{ * }"
materialList="{ water, rock }" />
</ElementRegions>

. Warning

All the imported cellBlocks must be included in one (and only one) of the CellElementRegion. Even if some

392 Chapter 1. Table of Contents

GEOS Documentation

cells are meant to be inactive during the simulation, they still have to be included in a CellElementRegion (this
CellElementRegion should simply not be included as a targetRegion of any of the solvers involved in the simu-
lation).

The cellBlocks element types are :

• hexahedra
• tetrahedra
• wedges
• pyramids
• pentagonalPrisms
• hexagonalPrisms
• heptagonalPrisms
• octagonalPrisms
• nonagonalPrisms
• decagonalPrisms
• hendecagonalPrisms
• polyhedra
An example of a vtk file with all the physical regions defined is used in Tutorial 3: Regions and Property Specifications.

Importing surfaces

Surfaces are imported through point sets in GEOS. This feature is only supported using the vtk file format. In the
same way than the regions, the surfaces of interests can be defined using the physical entity names. The surfaces are
automatically imported in GEOS if they exist in the vtk file. Within GEOS, the point set will have the same name than
the one given in the file. This name can be used again to impose boundary condition.
For instance, if a surface is named “Bottom” and the user wants to impose a Dirichlet boundary condition of 0 on it, it
can be easily done using this syntax:

The name of the surface of interest appears under the keyword setNames. Again, an example of a vtk file with the
surfaces fully defined is available within Tutorial 3: Regions and Property Specifications or CO2 Plume Evolution With
Hysteresis Effect on Relative Permeability.

1.5. User Guide 393

GEOS Documentation

1.5.3 Physics Solvers

The <Solvers> section of the input file specifies one or several physics solvers to be included in the simulation.

Solution Strategy
All physics solvers share a common solution strategy for nonlinear time-dependent problems. Here, we briefly describe
the nonlinear solver and the timestepping strategy employed.

Nonlinear Solver

At each time-step, the nonlinear system of discrete residual equations, i.e.

𝑟(𝑥) = 0
is solved by employing the Newton-Raphson method. Here, 𝑥 is the vector of primary unknowns. Thus, each physics
solver is responsible for assembling the Jacobian matrix 𝐽 containing the analytical derivatives of the residual vector 𝑟
with respect to the primary variables. Then, at each Newton iteration 𝜈, the following linear system is solved
𝐽 𝜈 𝛿𝑥𝜈+1 = −𝑟𝜈 ,
where, 𝛿𝑥𝜈+1 is the Newton update. This linear system can be solved with a variety of different linear solvers described
in Linear Solvers. The Newton update, 𝛿𝑥𝜈+1 is then applied to the primary variables:
𝑥𝜈+1 = 𝑥𝜈 + 𝛿𝑥𝜈+1 .
This procedure is repeated until convergence is achieved or until the maximum number of iterations is reached.

Line Search

A line search method can be applied along with the Newton’s method to facilitate Nonlinear convergence. After the
Newton update, if the residual norm has increased instead of decreased, a line search algorithm is employed to correct
the Newton update.
The user can choose between two different behaviors in case the line search fails to provide a reduced residual norm:
1. accept the solution and move to the next Newton iteration;
2. reject the solution and request a timestep cut;

Timestepping Strategy

The actual timestep size employed is determined by a combination of several factors. In particular, specific output
events may have timestep requirements that force a specific timestep to be used. However, physics solvers do have the
possibility of requesting a specific timestep size to the event manager based on their specific requirements. In particular,
in case of fast convergence indicated by a small number of Newton iterations, i.e.
numIterations < dtIncIterLimit · newtonMaxIter,
the physics solver will require to double the timestep size. On the other hand, if a large number of nonlinear iterations
are necessary to find the solution at timestep 𝑛
numIterations > dtCutIterLimit · newtonMaxIter,
the physics solver will request the next timestep, 𝑛 + 1, to be half the size of timestep 𝑛. Here,
Additionally, in case the nonlinear solver fails to converge with the timestep provided by the event manager, the timestep
size is cut, i.e.
dt = timestepCutFactor · dt,
and the nonlinear loop is repeated with the new timestep size.

394 Chapter 1. Table of Contents

GEOS Documentation

Parameters

All parameters defining the behavior of the nonlinear solver and determining the timestep size requested by the physics
solver are defined in the NonlinearSolverParameters and are presented in the following table.

1.5. User Guide 395

GEOS Documentation

XML Element: NonlinearSolverParameters

Name Type Default Description

allowNonConverged integer 0 Allow non-converged so-
lution to be accepted. (i.e.
exit from the Newton loop
without achieving the de-
sired tolerance)
configurationTolerance real64 0 Configuration tolerance
couplingType geos_NonlinearSolverParameters_CouplingType
FullyImplicit
Type of coupling. Valid
options:
* FullyImplicit
* Sequential

lineSearchAction geos_NonlinearSolverParameters_LineSearchAction
Attempt
How the line search is to
be used. Options are:
* None - Do not use
line search.
* Attempt - Use line
search. Allow exit from
line search without
achieving smaller residual
than starting residual.
* Require - Use line
search. If smaller residual
than starting resdual is not
achieved, cut time-step.

lineSearchCutFactor real64 0.5 Line search cut factor. For

instance, a value of 0.5
will result in the effective
application of the last so-
lution by a factor of (0.5,
0.25, 0.125, . . . )
lineSearchInterpolation- geos_NonlinearSolverParameters_LineSearchInterpolationType
Linear
Type
Strategy to cut the
solution update during the
line search. Options are:
* Linear
* Parabolic

lineSearchMaxCuts integer 4 Maximum number of line

search cuts.
lineSearchResidualFactor real64 1 Factor to determine
residual increase (rec-
ommended values: 1.1
(conservative), 2.0 (re-
laxed), 10.0 (aggressive)).
lineSearchStartingItera- integer 0 Iteration when line search
tion starts.
logLevel
396 integer 0 Log1.level
Chapter Table of Contents
maxAllowedResidual- real64 1e+09 Maximum value of resid-
Norm ual norm that is allowed in
a Newton loop
GEOS Documentation

Solid Mechanics Solver

List of Symbols

𝑖, 𝑗, 𝑘 ≡ indices over spatial dimensions

𝑎, 𝑏, 𝑐 ≡ indices over nodes
𝑙 ≡ indices over volumetric elements
𝑞, 𝑟, 𝑠 ≡ indices over faces
𝑛 ≡ indices over time
𝑘𝑖𝑡𝑒𝑟 ≡ iteration count for non-linear solution scheme
Ω ≡ Volume of continuum body
Ω𝑐𝑟𝑎𝑐𝑘 ≡ Volume of open crack
Γ ≡ External surface of Ω
Γ𝑡 ≡ External surface where tractions are applied
Γ𝑢 ≡ External surface where kinematics are specified
Γ𝑐𝑟𝑎𝑐𝑘 ≡ entire surface of crack
Γ𝑐𝑜ℎ𝑒𝑠𝑖𝑣𝑒 ≡ surface of crack subject to cohesive tractions
𝜂0 ≡ set of all nodes
𝜂𝑓 ≡ set of all nodes on flow mesh
𝑚 ≡ mass
𝜅𝑘 ≡ all elements connected to element k
𝜑 ≡ porosity
𝑝𝑓 ≡ fluid pressure
u ≡ displacement
q ≡ volumetric flow rate
T ≡ Cauchy stress
𝜌 ≡ density in the current configuration
x ≡ current position
w ≡ aperture, or gap vector

Introduction

The SolidMechanics_LagrangianFEM solver applies a Continuous Galerkin finite element method to solve the linear
momentum balance equation. The primary variable is the displacement field which is discretized at the nodes.

Theory

Governing Equations

The SolidMechanics_LagrangianFEM solves the equations of motion as given by

𝑇𝑖𝑗,𝑗 + 𝜌(𝑏𝑖 − 𝑥
¨𝑖 ) = 0,

which is a 3-dimensional expression for the well known expression of Newtons Second Law (𝐹 = 𝑚𝑎). These equations
of motion are discretized using the Finite Element Method, which leads to a discrete set of residual equations:
∫︁ ∫︁ ∫︁
(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 = Φ𝑎 𝑡𝑖 𝑑𝐴 − Φ𝑎,𝑗 𝑇𝑖𝑗 𝑑𝑉 + Φ𝑎 𝜌(𝑏𝑖 − Φ𝑏 𝑥 ¨𝑖𝑏 )𝑑𝑉 = 0
Γ𝑡 Ω Ω

1.5. User Guide 397

GEOS Documentation

Quasi-Static Time Integration

The Quasi-Static time integration option solves the equation of motion after removing the inertial term, which is ex-
pressed by

𝑇𝑖𝑗,𝑗 + 𝜌𝑏𝑖 = 0,

which is essentially a way to express the equation for static equilibrium (Σ𝐹 = 0). Thus, selection of the Quasi-Static
option will yield a solution where the sum of all forces at a given node is equal to zero. The resulting finite element
discretized set of residual equations are expressed as
∫︁ ∫︁ ∫︁
(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 = Φ𝑎 𝑡𝑖 𝑑𝐴 − Φ𝑎,𝑗 𝑇𝑖𝑗 𝑑𝑉 + Φ𝑎 𝜌𝑏𝑖 𝑑𝑉 = 0,
Γ𝑡 Ω Ω

Taking the derivative of these residual equations wrt. the primary variable (displacement) yields
𝑒 ∫︁
𝜕(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 𝜕𝑇𝑖𝑘
= − Φ𝑎,𝑘 𝑑𝑉,
𝜕𝑢𝑏𝑗 𝜕𝑢𝑏𝑗
Ω𝑒

And finally, the expression for the residual equation and derivative are used to express a non-linear system of equations
(︂ 𝑒
)︂⃒𝑛+1 (︁
𝜕(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 ⃒⃒ 𝑛+1 𝑛+1
)︁
𝑛+1
(𝑢 )|
𝑏𝑗 𝑘𝑖𝑡𝑒𝑟+1 − (𝑢𝑏𝑗 𝑘𝑖𝑡𝑒𝑟 = −(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 |𝑘𝑖𝑡𝑒𝑟 ,
)|
𝜕𝑢𝑏𝑗 ⃒
𝑘𝑖𝑡𝑒𝑟

which are solved via the solver package.

Implicit Dynamics Time Integration (Newmark Method)

For implicit dynamic time integration, we use an implementation of the classical Newmark method. This update
method can be posed in terms of a simple SDOF spring/dashpot/mass model. In the following, 𝑀 represents the mass,
𝐶 represent the damping of the dashpot, 𝐾 represents the spring stiffness, and 𝐹 represents some external load.

𝑀 𝑎𝑛+1 + 𝐶𝑣 𝑛+1 + 𝐾𝑢𝑛+1 = 𝐹𝑛+1 ,

and a series of update equations for the velocity and displacement at a point:

𝑢𝑛+1 = 𝑢𝑛 + 𝑣 𝑛+1/2 ∆𝑡,

(︂ )︂
𝑛+1 𝑛 𝑛 1 [︀ 𝑛 𝑛+1
]︀
𝑢 =𝑢 + 𝑣 + (1 − 2𝛽)𝑎 + 2𝛽𝑎 ∆𝑡 ∆𝑡,
2
𝑣 𝑛+1 = 𝑣 𝑛 + (1 − 𝛾)𝑎𝑛 + 𝛾𝑎𝑛+1 ∆𝑡.
[︀ ]︀

As intermediate quantities we can form an estimate (predictor) for the end of step displacement and midstep velocity
by assuming zero end-of-step acceleration.
(︂ )︂
𝑛+1 1 ˆ˜
𝑢
˜ = 𝑢 + 𝑣 + (1 − 2𝛽)𝑎 ∆𝑡 ∆𝑡 = 𝑢𝑛 + 𝑢
𝑛 𝑛 𝑛
2
𝑣˜𝑛+1 = 𝑣 𝑛 + (1 − 𝛾)𝑎𝑛 ∆𝑡 = 𝑣 𝑛 + 𝑣˜ˆ

This gives the end of step displacement and velocity in terms of the predictor with a correction for the end step accel-
eration.
𝑢𝑛+1 = 𝑢
˜𝑛+1 + 𝛽𝑎𝑛+1 ∆𝑡2
𝑣 𝑛+1 = 𝑣˜𝑛+1 + 𝛾𝑎𝑛+1 ∆𝑡

398 Chapter 1. Table of Contents

GEOS Documentation

The acceleration and velocity may now be expressed in terms of displacement, and ultimately in terms of the incremental
displacement.
1 (︀ 𝑛+1 1 (︁ ˆ˜
)︁
𝑎𝑛+1 = 𝑛+1
)︀
𝑢 − 𝑢
˜ = 𝑢
ˆ − 𝑢
𝛽∆𝑡2 𝛽∆𝑡2
𝛾 𝛾 (︁ ˆ˜
)︁
𝑣 𝑛+1 = 𝑣˜𝑛+1 + 𝑢𝑛+1 − 𝑢 ˜𝑛+1 = 𝑣˜𝑛+1 +
(︀ )︀
𝑢ˆ−𝑢
𝛽∆𝑡 𝛽∆𝑡
plugging these into equation of motion for the SDOF system gives:
(︂ )︁)︂ (︂ )︁)︂
1 (︁ ˆ 𝑛+1 𝛾 (︁ ˆ˜
𝑀 𝑢
ˆ − 𝑢
˜ + 𝐶 𝑣
˜ + 𝑢
ˆ − 𝑢 + 𝐾𝑢𝑛+1 = 𝐹𝑛+1
𝛽∆𝑡2 𝛽∆𝑡

Finally, we assume Rayliegh damping for the dashpot.

𝐶 = 𝑎𝑚𝑎𝑠𝑠 𝑀 + 𝑎𝑠𝑡𝑖𝑓 𝑓 𝐾

Of course we know that we intend to model a system of equations with many DOF. Thus the representation for the
mass, spring and dashpot can be replaced by our finite element discretized equation of motion. We may express the
system in context of a nonlinear residual problem
∫︁
𝑒
(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 = Φ𝑎 𝑡𝑖 𝑑𝐴
Γ𝑒𝑡
(︃ (︃ )︃ )︃
𝜕𝑇𝑖𝑗𝑛+1
∫︁ (︂ )︁)︂
𝛾 (︁ ˆ
− Φ𝑎,𝑗 𝑇𝑖𝑗𝑛+1
+ 𝑎𝑠𝑡𝑖𝑓 𝑓 𝑛+1
𝑣˜𝑏𝑘 + ˆ𝑏𝑘 − 𝑢
𝑢 ˜𝑏𝑘 𝑑𝑉
𝜕𝑢 ˆ𝑏𝑘 𝛽∆𝑡
Ω𝑒 𝑒𝑙𝑎𝑠𝑡𝑖𝑐
∫︁ (︂ (︂ (︂ )︁)︂ )︁)︂)︂
𝑛+1 𝛾 (︁ ˆ 1 (︁ ˆ
+ Φ𝑎 𝜌 𝑏𝑖 − Φ𝑏 𝑎𝑚𝑎𝑠𝑠 𝑣˜𝑏𝑖 + ˆ𝑏𝑖 − 𝑢
𝑢 ˜𝑏𝑖 + ˆ𝑏𝑖 − 𝑢
𝑢 ˜𝑏𝑖 𝑑𝑉,
𝛽∆𝑡 𝛽∆𝑡2
Ω𝑒
𝑒 ∫︁ (︂ 𝑛+1 (︂ 𝑛+1 )︂ )︂
𝜕(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 𝜕𝑇𝑖𝑘 𝛾 𝜕𝑇𝑖𝑘
= − Φ𝑎,𝑘 + 𝑎𝑠𝑡𝑖𝑓 𝑓 𝑑𝑉
𝜕𝑢ˆ𝑏𝑗 𝜕𝑢
ˆ𝑏𝑗 𝛽∆𝑡 𝜕𝑢
ˆ𝑏𝑗 𝑒𝑙𝑎𝑠𝑡𝑖𝑐
Ω𝑒
(︂ )︂ ∫︁
𝛾𝑎𝑚𝑎𝑠𝑠 1 𝜕𝑢ˆ𝑐𝑖
− + 2
𝜌Φ𝑎 Φ𝑐 𝑑𝑉.
𝛽∆𝑡 𝛽∆𝑡 𝜕𝑢ˆ𝑏𝑗
Ω𝑒

Again, the expression for the residual equation and derivative are used to express a non-linear system of equations
(︂ 𝑒
)︂⃒𝑛+1 (︁
𝜕(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 ⃒⃒ 𝑛+1 𝑛+1
)︁
𝑛+1
(𝑢𝑏𝑗 )|𝑘𝑖𝑡𝑒𝑟+1 − (𝑢𝑏𝑗 )|𝑘𝑖𝑡𝑒𝑟 = −(𝑅𝑠𝑜𝑙𝑖𝑑 )𝑎𝑖 |𝑘𝑖𝑡𝑒𝑟 ,
𝜕𝑢𝑏𝑗 ⃒
𝑘𝑖𝑡𝑒𝑟

which are solved via the solver package. Note that the derivatives involving 𝑢 and 𝑢
ˆ are interchangable, as are differences
between the non-linear iterations.

Explicit Dynamics Time Integration (Special Implementation of Newmark Method with gamma=0.5,
beta=0)

For the Newmark Method, if gamma=0.5, beta=0, and the inertial term contains a diagonalized “mass matrix”, the
update equations may be carried out without the solution of a system of equations. In this case, the update equations
simplify to a non-iterative update algorithm.
First the mid-step velocity and end-of-step displacements are calculated through the update equations
(︂ )︂
∆𝑡
𝑣 𝑛+1/2 = 𝑣 𝑛 + 𝑎𝑛 , and
2
𝑢𝑛+1 = 𝑢𝑛 + 𝑣 𝑛+1/2 ∆𝑡.

1.5. User Guide 399

GEOS Documentation

Then the residual equation/s are calculated, and acceleration at the end-of-step is calculated via
(︂ )︂
∆𝑡
𝑀+ 𝐶 𝑎𝑛+1 = 𝐹𝑛+1 − 𝐶𝑣 𝑛+1/2 − 𝐾𝑢𝑛+1 .
2

Note that the mass matrix must be diagonal, and damping term may not include the stiffness based damping coeffi-
cient for this method, otherwise the above equation will require a system solve. Finally, the end-of-step velocities are
calculated from the end of step acceleration:
(︂ )︂
𝑛+1 𝑛+1/2 𝑛+1 ∆𝑡
𝑣 =𝑣 +𝑎 .
2

Note that the velocities may be stored at the midstep, resulting one less kinematic update. This approach is typically
referred to as the “Leapfrog” method. However, in GEOS we do not offer this option since it can cause some confusion
that results from the storage of state at different points in time.

Parameters

In the preceding XML block, The SolidMechanics_LagrangianFEM is specified by the title of the subblock of the
Solvers block. The following attributes are supported in the input block for SolidMechanics_LagrangianFEM:

400 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SolidMechanics_LagrangianFEM

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
contactPenaltyStiffness real64 0 Value of the penetration
penalty stiffness. Units of
Pressure/length
contactRelationName groupNameRef NOCONTACT Name of contact relation
to enforce constraints on
fracture boundary.
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
1.5. User Guide information 401
- Nonlinear solver
information
- Solver timers
GEOS Documentation

The following data are allocated and used by the solver:

Datastructure: SolidMechanics_LagrangianFEM

Name Type Description

max- real64 The maxi-
Force mum force
contribution
in the problem
domain.
maxStableDt
real64 Value of
the Maxi-
mum Stable
Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, std___1_char_traits<char>, Mesh-
gets std___1_allocator<char>>, std___1_basic_string<char, std___1_char_traits<char>, Body/Region
std___1_allocator<char>>>, LvArray_Array<std___1_basic_string<char, combinations
std___1_char_traits<char>, std___1_allocator<char>>, 1, camp_int_seq<long, 0l>, that the solver
int, LvArray_ChaiBuffer>, std___1_integral_constant<bool, true>> will be applied
to.
Lin- node Datastruc-
ear- ture: Linear-
Solver- SolverParam-
Pa- eters
rame-
ters
Non- node Datastruc-
lin- ture: Nonlin-
ear- earSolverPa-
Solver- rameters
Pa-
rame-
ters
Solver- node Datastruc-
Statis- ture: Solver-
tics Statistics

Example

An example of a valid XML block is given here:

402 Chapter 1. Table of Contents

GEOS Documentation

Contact Mechanics Solver

Governing Equations

GEOS contact solvers solve the the balance of linear momentum within a fractured solid, accounting for the continuity
of stress across surfaces (i.e., fractures), i.e.

∇·𝜎 =0

[[𝜎]] · n = 0

Where:
• 𝜎 is the stress tensor in the solid,
• n is the outward unit normal to the surface,
• [[𝜎]] is the stress jump across the surface.
On each fracture surface, a no-interpenetration constraint is enforced. Additionally, tangential tractions can also be
generated, which are modeled using a regularized Coulomb model to describe frictional sliding.

Solvers

There exist two broad classes of discretization methods that model fractures as lower dimensional entities (eg, 2D
surfaces in a 3D domain): conforming grid methods and nonconforming (or embedded) methods. Both approaches
have been implemented in GEOS in the following solvers:

Solid mechanics conforming fractures solver

Introduction

Theory

Under construction

Governing Equations

Under construction

Parameters

In the preceding XML block, The SolidMechanicsLagrangeContact is specified by the title of the subblock of the
Solvers block. The following attributes are supported in the input block for SolidMechanicsLagrangeContact:

1.5. User Guide 403

GEOS Documentation

404 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SolidMechanicsLagrangeContact

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
contactPenaltyStiffness real64 0 Value of the penetration
penalty stiffness. Units of
Pressure/length
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
1.5. User Guide - Solver timers 405
information
2
GEOS Documentation

The following data are allocated and used by the solver:

Datastructure: SolidMechanicsLagrangeContact

Name Type Description

con- groupNameRef Name of con-
tac- tact relation
tRe- to enforce
la- constraints
tion- on fracture
Name boundary.
max- real64 The maxi-
Force mum force
contribution in
the problem
domain.
maxStableDt
real64 Value of the
Maximum Sta-
ble Timestep
for this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, std___1_char_traits<char>, Mesh-
gets std___1_allocator<char>>, std___1_basic_string<char, std___1_char_traits<char>, Body/Region
std___1_allocator<char>>>, LvArray_Array<std___1_basic_string<char, combinations
std___1_char_traits<char>, std___1_allocator<char>>, 1, camp_int_seq<long, 0l>, int, that the solver
LvArray_ChaiBuffer>, std___1_integral_constant<bool, true>> will be applied
to.
sur- string Name of the
face- surface gener-
Gen- ator to use
era-
tor-
Name
Lin- node Datastructure:
ear- LinearSolver-
Solver- Parameters
Pa-
rame-
ters
Non- node Datastructure:
lin- Nonlinear-
ear- SolverParame-
Solver- ters
Pa-
rame-
ters
Solver- node Datastructure:
Statis- SolverStatis-
tics tics

406 Chapter 1. Table of Contents

GEOS Documentation

Solid mechanics embedded fractures solver

Introduction

Discretization & soltuion strategy

The linear momentum balance equation is discretized using a low order finite element method. Moreover, to account
for the influence of the fractures on the overall behavior, we utilize the enriched finite element method (EFEM) with a
piece-wise constant enrichment. This method employs an element-local enrichment of the FE space using the concept
of assumedenhanced strain [1-6].

Example

An example of a valid XML block is given here:

Parameters

In the preceding XML block, The SolidMechanicsEmbeddedFractures is specified by the title of the subblock of the
Solvers block. Note that the SolidMechanicsEmbeddedFractures always relies on the existance of a The following
attributes are supported in the input block for SolidMechanicsEmbeddedFractures:

1.5. User Guide 407

GEOS Documentation

408 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SolidMechanicsEmbeddedFractures

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
contactPenaltyStiffness real64 required Value of the penetration
penalty stiffness. Units of
Pressure/length
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
1.5. User Guide - Solver timers 409
information
2
GEOS Documentation

The following data are allocated and used by the solver:

Datastructure: SolidMechanicsEmbeddedFractures

Name Type Description

410 Chapter 1. Table of Contents

GEOS Documentation

References

1. Simo JC, Rifai MS. A class of mixed assumed strain methods and the method of incompatible modes. Int J
Numer Methods Eng. 1990;29(8):1595-1638. Available at: http://arxiv.org/abs/https://onlinelibrary.wiley.com/
doi/pdf/10.1002/nme.1620290802.
2. Foster CD, Borja RI, Regueiro RA. Embedded strong discontinuity finite elements for fractured geomaterials
with variable friction. Int J Numer Methods Eng. 2007;72(5):549-581. Available at: http://arxiv.org/abs/https:
//onlinelibrary.wiley.com/doi/pdf/10.1002/nme.2020.
3. Wells G, Sluys L. Three-dimensional embedded discontinuity model for brittle fracture. Int J Solids Struct.
2001;38(5):897-913. Available at: https://doi.org/10.1016/S0020-7683(00)00029-9.
4. Oliver J, Huespe AE, Sánchez PJ. A comparative study on finite elements for capturing strong discontinuities:
E-fem vs x-fem. Comput Methods Appl Mech Eng. 2006;195(37-40):4732-4752. Available at: https://doi.org/
10.1002/nme.4814.
5. Borja RI. Assumed enhanced strain and the extended finite element methods: a unification of concepts. Comput
Methods Appl Mech Eng. 2008;197(33):2789-2803. Available at: https://doi.org/10.1016/j.cma.2008.01.019.
6. Wu J-Y. Unified analysis of enriched finite elements for modeling cohesive cracks. Comput Methods Appl Mech
Eng. 2011;200(45-46):3031-3050. Available at: https://doi.org/10.1016/j.cma.2011.05.008.

Singlephase Flow Solver

Introduction

Here, we describe the single-phase flow solver. The role of this solver is to implement the fully implicit finite-volume
discretization (mainly, accumulation and source terms, boundary conditions) of the equations governing compressible
single-phase flow in porous media. This solver can be combined with the SinglePhaseWell class which handles the
discrete multi-segment well model and provides source/sink terms for the fluid flow solver.

Theory

Governing Equations

This is a cell-centered Finite Volume solver for compressible single-phase flow in porous media. Fluid pressure as the
primary solution variable. Darcy’s law is used to calculate fluid velocity from pressure gradient. The solver currently
only supports Dirichlet-type boundary conditions (BC) applied on cells or faces and Neumann no-flow type BC.
The following mass balance equation is solved in the domain:
𝜕
(𝜑𝜌) + ∇ · (𝜌𝑢) + 𝑞 = 0,
𝜕𝑡
where
1
𝑢 = − 𝑘(∇𝑝 − 𝜌𝑔)
𝜇
and 𝜑 is porosity, 𝜌 is fluid density, 𝜇 is fluid viscosity, 𝑘 is the permeability tensor, 𝑔 is the gravity vector, and 𝑞 is the
source function (currently not supported). The details on the computation of the density and the viscosity are given in
Compressible single phase fluid model.
When the entire pore space is filled by a single phase, we can substitute the Darcy’s law into the mass balance equation
to obtain the single phase flow equation
𝜕 𝜌𝑘
(𝜑𝜌) − ∇ · (∇𝑝 − 𝛾∇𝑧) + 𝑞 = 0,
𝜕𝑡 𝜇
with 𝛾∇𝑧 = 𝜌𝑔.

1.5. User Guide 411

GEOS Documentation

Discretization

Space Discretization

Let Ω ⊂ R𝑛 , 𝑛 = 1, 2, 3 be an open set defining the computational domain. We consider Ω meshed by element such
that Ω = ∪𝑖 𝑉𝑖 and integrate the single phase flow equation, described above, over each element 𝑉𝑖 :
∫︁ ∫︁ ∫︁
𝜕 𝜌𝑘
(𝜑𝜌)𝑑𝑉 − ∇· (∇𝑝 − 𝛾∇𝑧)𝑑𝑉 + 𝑞𝑑𝑉 = 0.
𝑉𝑖 𝜕𝑡 𝑉𝑖 𝜇 𝑉𝑖

Applying the divergence theorem to the second term leads to

∫︁ ∮︁ (︂ )︂ ∫︁
𝜕 𝜌𝑘
(𝜑𝜌)𝑖 − (∇𝑝 − 𝛾∇𝑧) · 𝑛𝑑𝑆 + 𝑞𝑑𝑉 = 0.
𝑉𝑖 𝜕𝑡 𝑆𝑖 𝜇 𝑉𝑖

where 𝑆𝑖 represents the surface area of the element 𝑉𝑖 and 𝑛 is a outward unit vector normal to the surface.
For the flux term, the (static) transmissibility is currently computed with a Two-Point Flux Approximation (TPFA) as
described in Finite Volume Discretization.
The pressure-dependent mobility 𝜆 = 𝜌
𝜇 at the interface is approximated using a first-order upwinding on the sign of
the potential difference.

Time Discretization

Let 𝑡0 < 𝑡1 < · · · < 𝑡𝑁 = 𝑇 be a grid discretization of the time interval [𝑡0 , 𝑇 ], 𝑡0 , 𝑇 ∈ R+ . We use the backward
Euler (fully implicit) method to integrate the single phase flow equation between two grid points 𝑡𝑛 and 𝑡𝑛+1 , 𝑛 < 𝑁
to obtain the residual equation:
)︂𝑛+1
(𝜑𝜌)𝑛+1 − (𝜑𝜌)𝑛𝑖
∫︁ ∮︁ (︂ ∫︁
𝜌𝑘
𝑖
− (∇𝑝 − 𝛾∇𝑧) · 𝑛𝑑𝑆 + 𝑞 𝑛+1 𝑑𝑉 = 0
𝑉𝑖 ∆𝑡 𝑆𝑖 𝜇 𝑉𝑖

where ∆𝑡 = 𝑡𝑛+1 − 𝑡𝑛 is the time-step. The expression of this residual equation and its derivative are used to form a
linear system, which is solved via the solver package.

Parameters

The solver is enabled by adding a <SinglePhaseFVM> node in the Solvers section. Like any solver, time stepping is
driven by events, see Event Management.
The following attributes are supported:

412 Chapter 1. Table of Contents

GEOS Documentation

1.5. User Guide 413

GEOS Documentation

XML Element: SinglePhaseFVM

Name Type Default Description

allowNegativePressure integer 1 Flag indicating if negative
pressure is allowed
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0
Flag indicating whether
the problem is thermal or
not.
SourceFluxes application
if isThermal is enabled :
- negative value
(injection): the mass
balance equation is
modified to considered
the additional source
term,
- positive value
(production): both the
mass balance and the
energy balance equations
are modified to
considered the additional
source term.
For the energy balance
equation, the mass flux is
multipied by the enthalpy
in the cell from which the
fluid is being produced.

logLevel integer 0
414 Sets1.theTable
Chapter level of
of Contents
information to write in the
standard output (the
console typically).
GEOS Documentation

Example

We refer the reader to this page for a complete tutorial illustrating the use of this solver.

Compositional Multiphase Flow Solver

Introduction

This flow solver is in charge of implementing the finite-volume discretization (mainly, accumulation and flux terms,
boundary conditions) of the equations governing compositional multiphase flow in porous media. The present solver
can be combined with the Compositional Multiphase Well Solver which handles the discrete multi-segment well model
and provides source/sink terms for the fluid flow solver.
Below, we first review the set of Governing Equations, followed by a discussion of the choice of Primary Variables
used in the global variable formulation. Then we give an overview of the Discretization and, finally, we provide a list
of the solver Parameters and an input Example.

Theory

Governing Equations

1.5. User Guide 415

GEOS Documentation

Mass Conservation Equations

Mass conservation for component 𝑐 is expressed as:

(︂ )︂ (︂ ∑︁ )︂ ∑︁
𝜕 ∑︁
𝜑 𝜌ℓ 𝑦𝑐ℓ 𝑆ℓ + ∇ · 𝜌ℓ 𝑦𝑐ℓ 𝑢ℓ − 𝜌ℓ 𝑦𝑐ℓ 𝑞ℓ = 0,
𝜕𝑡
ℓ ℓ ℓ

where 𝜑 is the porosity of the medium, 𝑆ℓ is the saturation of phase ℓ, 𝑦𝑐ℓ is the mass fraction of component 𝑐 in phase
ℓ, 𝜌ℓ is the phase density, and 𝑡 is time. We note that the formulation currently implemented in GEOS is isothermal.

Darcy’s Law

Using the multiphase extension of Darcy’s law, the phase velocity 𝑢ℓ is written as a function of the phase potential
gradient ∇Φℓ :
(︀ )︀
𝑢ℓ := −𝑘𝜆ℓ ∇Φℓ = −𝑘𝜆ℓ ∇(𝑝 − 𝑃𝑐,ℓ ) − 𝜌ℓ 𝑔∇𝑧 .

In this equation, 𝑘 is the rock permeability, 𝜆ℓ = 𝑘𝑟ℓ /𝜇ℓ is the phase mobility, defined as the phase relative permeability
divided by the phase viscosity, 𝑝 is the reference pressure, 𝑃𝑐,ℓ is the the capillary pressure, 𝑔 is the gravitational ac-
celeration, and 𝑧 is depth. The evaluation of the relative permeabilities, capillary pressures, and viscosities is reviewed
in the section about Constitutive Models.
Combining the mass conservation equations with Darcy’s law yields a set of 𝑛𝑐 equations written as:
(︂ )︂ (︂ ∑︁ )︂ ∑︁
𝜕 ∑︁
𝜑 𝜌ℓ 𝑦𝑐ℓ 𝑆ℓ − ∇ · 𝑘 𝜌ℓ 𝑦𝑐ℓ 𝜆ℓ ∇Φℓ − 𝜌ℓ 𝑦𝑐ℓ 𝑞ℓ = 0.
𝜕𝑡
ℓ ℓ ℓ

Constraints and Thermodynamic Equilibrium

The volume constraint equation states that the pore space is always completely filled by the phases. The constraint can
be expressed as:
∑︁
𝑆ℓ = 1.
ℓ

The system is closed by the following thermodynamic equilibrium constraints:

𝑓𝑐ℓ − 𝑓𝑐𝑚 = 0.

where 𝑓𝑐ℓ is the fugacity of component 𝑐 in phase ℓ. The flash calculations performed to enforce the thermodynamical
equilibrium are reviewed in the section about Constitutive Models.
To summarize, the compositional multiphase flow solver assembles a set of 𝑛𝑐 + 1 equations in each element, i.e.,
𝑛𝑐 mass conservation equations and one volume constraint equation. A separate module discussed in the Constitutive
Models is responsible for the enforcement of the thermodynamic equilibrium at each nonlinear iteration.

Number of equations Equation type

𝑛𝑐 Mass conservation equations
1 Volume constraint

Primary Variables

The variable formulation implemented in GEOS is a global variable formulation based on 𝑛𝑐 + 1 primary variables,
namely, one pressure, 𝑝, and 𝑛𝑐 component densities, 𝜌𝑐 . By default, we use molar component densities. A flag dis-
cussed in the section Parameters can be used to select mass component densities instead of molar component densities.

416 Chapter 1. Table of Contents

GEOS Documentation

Number of primary variables Variable type

1 Pressure
𝑛𝑐 Component densities

Assembling the residual equations and calling the Constitutive Models requires computing the molar component frac-
tions and saturations. This is done with the relationship:
𝜌𝑐
𝑧𝑐 := ,
𝜌𝑇
where
∑︁
𝜌𝑇 := 𝜌𝑐 .
𝑐

These secondary variables are used as input to the flash calculations. After the flash calculations, the saturations are
computed as:
𝜌𝑇
𝑆ℓ := 𝜈ℓ ,
𝜌ℓ
where 𝜈ℓ is the global mole fraction of phase ℓ and 𝜌ℓ is the molar density of phase ℓ. These steps also involve computing
the derivatives of the component fractions and saturations with respect to the pressure and component densities.

Discretization

Spatial Discretization

The governing equations are discretized using standard cell-centered finite-volume discretization.
In the approximation of the flux term at the interface between two control volumes, the calculation of the pressure
stencil is general and will ultimately support a Multi-Point Flux Approximation (MPFA) approach. The current imple-
mentation of the transmissibility calculation is reviewed in the section about Numerical Methods.
The approximation of the dynamic transport coefficients multiplying the discrete potential difference (e.g., the phase
mobilities) is performed with a first-order phase-per-phase single-point upwinding based on the sign of the phase
potential difference at the interface.

Temporal Discretization

The compositional multiphase solver uses a fully implicit (backward Euler) temporal discretization.

Solution Strategy

The nonlinear solution strategy is based on Newton’s method. At each Newton iteration, the solver assembles a residual
vector, 𝑅, collecting the 𝑛𝑐 discrete mass conservation equations and the volume constraint for all the control volumes.

Parameters

The following attributes are supported:

XML Element: CompositionalMultiphaseFVM

Table 1.1 – continued from previous page

solutionChangeScaling- real64 0.5 Damping factor for solu-

Factor tion change targets
targetFlowCFL real64 -1 Target CFL condition CFL
condition when comput-
ing the next timestep.
targetPhaseVolFraction- real64 0.2 Target (absolute) change
ChangeInTimeStep in phase volume fraction
in a time step
continues on next page

420 Chapter 1. Table of Contents

GEOS Documentation

Table 1.1 – continued from previous page

Name Type Default Description
targetRegions groupNameRef_array required Allowable regions that the
solver may be applied to.
Note that this does not in-
dicate that the solver will
be applied to these re-
gions, only that allocation
will occur such that the
solver may be applied to
these regions. The de-
cision about what regions
this solver will beapplied
to rests in the EventMan-
ager.
targetRelativeCompDen- real64 1.79769e+308 Target (relative) change in
sChangeInTimeStep component density in a
time step
targetRelativePres- real64 0.2 Target (relative) change in
sureChangeInTimeStep pressure in a time step
(expected value between 0
and 1)
targetRelativeTempera- real64 0.2 Target (relative) change in
tureChangeInTimeStep temperature in a time step
(expected value between 0
and 1)
temperature real64 required Temperature
useDBC integer 0 Enable Dissipation-based
continuation flux
useMass integer 0 Use mass formulation in-
stead of molar. Warning
: Affects SourceFlux rates
units.
useNewGravity integer 0 Flag indicating whether
new gravity treatment is
used
useSimpleAccumulation integer 1 Flag indicating whether
simple accumulation form
is used
useTotalMassEquation integer 1 Flag indicating whether
total mass equation is used
writeLinearSystem integer 0 Write matrix, rhs, solution
to screen ( = 1) or file ( =
2).
LinearSolverParameters node unique XML Element: Linear-
SolverParameters
NonlinearSolverParame- node unique XML Element: Nonlinear-
ters SolverParameters

1.5. User Guide 421

GEOS Documentation

Example

We refer the reader to Multiphase Flow for a complete tutorial illustrating the use of this solver.

Compositional Multiphase Well Solver

Introduction

Here, we present a description of the well solvers. These solvers are designed to be coupled with the flow solvers. Their
specific task is to implement the multi-segment well discretization using the fluid model used in the corresponding flow
solver – i.e., either single-phase flow or compositional multiphase flow. In particular, the perforation terms computed
by the well solvers are a source/sink term for the discrete reservoir equations assembled by the flow solvers.
In the present description, we focus on the compositional multiphase well solver. The structure of the single-phase well
solver is analogous and will not be described here for brevity.

Theory

Here, we give an overview of the well formulation implemented in GEOS. We review the set of Discrete Equations,
and then we describe the Primary variables used the well solvers.

Discrete Equations

We assume that the well is discretized into segments denoted by the index 𝑖.

Mass Conservation

In well segment 𝑖, mass conservation for component 𝑐 reads:

𝑢𝑝𝑤 𝑢𝑝𝑤 𝑝𝑒𝑟𝑓
𝑧𝑐,(𝑖−1,𝑖) 𝑞(𝑖−1,𝑖) − 𝑧𝑐,(𝑖,𝑖+1) 𝑞(𝑖,𝑖+1) + 𝑞𝑐,𝑖 = 0,
𝑢𝑝𝑤
where we have neglected the accumulation term. In the previous equation, 𝑧𝑐,(𝑖,𝑗) is the upwinded mass fraction of
𝑝𝑒𝑟𝑓
component 𝑐 at the interface between segments 𝑖 and 𝑗, 𝑞(𝑖,𝑗) is the total mass flux between segments 𝑖 and 𝑗, and 𝑞𝑐,𝑖
is the source/sink term generated by the perforations – i.e., the connections between the well and the reservoir. The
upwinded mass fractions are computed as:
⎧
⎨ 𝑧𝑐,𝑖 if 𝑞(𝑖,𝑗) > 0
𝑢𝑝𝑤
𝑧𝑐,(𝑖,𝑗) =
⎩ 𝑧
𝑐,𝑗 otherwise.

422 Chapter 1. Table of Contents

GEOS Documentation

The perforation terms are obtained with:

⎧
⎨ 𝑊 𝐼𝑧𝑐,𝑖 𝜌𝑚,𝑖 𝜆𝑟𝑒𝑠
𝑇 ∆Φ if the well is upstream (i.e., ∆Φ > 0)
𝑝𝑒𝑟𝑓
𝑞𝑐,𝑖 =
⎩ 𝑊 𝐼𝑥𝑟𝑒𝑠 𝜌𝑟𝑒𝑠 𝜆𝑟𝑒𝑠 ∆Φ
𝑐,ℓ ℓ ℓ otherwise,

where ∆Φ = 𝑝𝑖 − 𝑝𝑟𝑒𝑠 + 𝜌𝑚,𝑖 𝑔∆𝑑𝑖,𝑝𝑒𝑟𝑓 is the potential difference between the segment center∑︀ and the reservoir center.
In the expression of the potential difference, the mixture density is computed as 𝜌𝑚,𝑖 = ℓ 𝑆ℓ,𝑖 𝜌ℓ,𝑖 . The well index,
𝑊 𝐼, is currently an input of the simulator. The superscript 𝑟𝑒𝑠 means that the variable is evaluated at the center of the
reservoir element.

Volume Constraint Equation

As in the Compositional Multiphase Flow Solver, the system is closed with a volume constraint equation.

Pressure Relations

In the current implementation of the well solver, we assume a hydrostatic equilibrium:

𝑝𝑖+1 − 𝑝𝑖 = 𝜌𝑚,(𝑖,𝑖+1) 𝑔∆𝑑𝑖,𝑖+1 ,

where 𝜌𝑚,(𝑖,𝑖+1) is the arithmetic average of the mixture densities evaluated in segments 𝑖 and 𝑖 + 1. Pressure drop
components due to friction and acceleration are not implemented at the moment.

Pressure and Rate Controls

The well solver supports two types of control, namely, pressure control and rate control.
If pressure control is chosen, we add the following constraint for the pressure of the top segment of the well:

𝑝0 − 𝑝𝑡𝑎𝑟𝑔𝑒𝑡 = 0

In this case, we check that at each iteration of the Newton solver, the rate at the top of the first segment is smaller than
the maximum rate specified by the user. If this is not the case, we switch to rate control.
If rate control is used, we add the following constraint for the rate at the top of the first segment, denoted by 𝑞(−1,0) :

𝑞(−1,0) − 𝑞 𝑡𝑎𝑟𝑔𝑒𝑡 = 0

For an injector well, if the pressure at the top segment becomes larger than the target pressure specified by the user,
then we switch to pressure control. Similarly for a producer well, if the pressure at the top segment becomes smaller
than the target pressure specified by the user, then we switch to pressure control.
To summarize, the compositional multiphase flow solver assembles a set of 𝑛𝑐 + 2 equations, i.e., 𝑛𝑐 mass conservation
equations and 1 volume constraint equation in each segment, plus 1 pressure relation at the interface between a segment
and the next segment in the direction of the well head. For the top segment, the pressure relation is replaced with the
control equation.

Number of equations Equation type

𝑛𝑐 Mass conservation equations
1 Pressure relation or control equation
1 Volume constraint

1.5. User Guide 423

GEOS Documentation

Primary variables

The well variable formulation is the same as that of the Compositional Multiphase Flow Solver. In a well segment, in
addition to the 𝑛𝑐 + 1 primary variables of the Compositional Multiphase Flow Solver, namely, one pressure, 𝑝, and
𝑛𝑐 component densities, 𝜌𝑐 , we also treat the total mass flux at the interface with the next segment, denoted by 𝑞, as a
primary variable.

Number of primary variables Variable type

1 Pressure
1 Total mass flux at the interface with next segment
𝑛𝑐 Component densities

Parameters

The following attributes are supported:

424 Chapter 1. Table of Contents

GEOS Documentation

XML Element: CompositionalMultiphaseWell

Name Type Default Description

allowLocalCompDensity- integer 1 Flag indicating whether
Chopping local (cell-wise) chopping
of negative compositions
is allowed
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Well control
information
- Crossflow
information
2
- The summary of
1.5. User Guide declared fields and
425
coupling

maxAbsolutePres- real64 -1 Maximum (absolute) pres-

GEOS Documentation

Example

Poromechanics Solver
Introduction

This section describes the use of the poroelasticity models implemented in GEOS.

Theory

Governing Equations

In our model, the geomechanics (elasticity) equation is expressed in terms of the total stress 𝜎:

∇𝜎 + 𝜌𝑏 g = 0

where it relates to effective stress 𝜎′ and pore pressure 𝑝 through Biot’s coefficient 𝑏:

𝜎 = 𝜎′ − 𝑏𝑝I

The fluid mass conservation equation is expressed in terms of pore pressure and volumetric (mean) total stress:

𝑏2
(︂ )︂
1 𝜕𝑝 𝑏 𝜕𝜎𝑣
+ + + ∇ · v𝑓 = 𝑓
𝑀 𝐾𝑑𝑟 𝜕𝑡 𝐾𝑑𝑟 𝜕𝑡

426 Chapter 1. Table of Contents

GEOS Documentation

where 𝑀 is the Biot’s modulus and 𝐾𝑑𝑟 is the drained bulk modulus.
Unlike the conventional reservoir model that uses Lagranges porosity, in the coupled geomechanics and flow model,
Eulers porosity 𝜑 is adopted so the porosity variation is derived as:
(︂ )︂
𝑏−𝜑
𝜕𝜑 = 𝜕𝑝 + (𝑏 − 𝜑) 𝜕𝜖𝑣
𝐾𝑠

where 𝐾𝑠 is the bulk modulus of the solid grain and 𝜖𝑣 is the volumetric strain.

Parameters

The poroelasticity model is implemented as a main solver listed in <Solvers> block of the input XML file that calls
both SolidMechanicsLagrangianSSLE and SinglePhaseFlow solvers. In the main solver, it requires the specification of
solidSolverName, flowSolverName, and couplingTypeOption.
The following attributes are supported:

1.5. User Guide 427

GEOS Documentation

XML Element: SinglePhasePoromechanics

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
flowSolverName groupNameRef required Name of the flow solver
used by the coupled solver
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not. Set isThermal=”1”
to enable the thermal cou-
pling
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
2
- The summary of
declared fields and
coupling
428 Chapter 1. Table of Contents
name groupName required A name is required for any
non-unique nodes
solidSolverName groupNameRef required Name of the solid solver
GEOS Documentation

• couplingTypeOption: defines the coupling scheme.

The solid constitutive model used here is PoroLinearElasticIsotropic, which derives from ElasticIsotropic and includes
an additional parameter: Biot’s coefficient. The fluid constitutive model is the same as SinglePhaseFlow solver. For
the parameter setup of each individual solver, please refer to the guideline of the specific solver.
An example of a valid XML block for the constitutive model is given here:
<Constitutive>
<PorousElasticIsotropic
name="porousRock"
solidModelName="skeleton"
porosityModelName="skeletonPorosity"
permeabilityModelName="skeletonPerm"/>

Example

(continues on next page)

1.5. User Guide 429

GEOS Documentation

(continued from previous page)

Proppant Transport Solver

Introduction

The ProppantTransport solver applies the finite volume method to solve the equations of proppant transport in hydraulic
fractures. The behavior of proppant transport is described by a continuum formulation. Here we briefly outline the
usage, governing equations and numerical implementation of the proppant transport model in GEOS.

Theory

The following mass balance and constitutive equations are solved inside fractures,

Proppant-fluid Slurry Flow

𝜕
(𝜌𝑚 ) + ∇ · (𝜌𝑚 𝑢𝑚 ) = 0,
𝜕𝑡
where the proppant-fluid mixture velocity 𝑢𝑚 is approximated by the Darcy’s law as,

𝐾𝑓
𝑢𝑚 = − (∇𝑝 − 𝜌𝑚 𝑔),
𝜇𝑚
and 𝑝 is pressure, 𝜌𝑚 and 𝜇𝑚 are density and viscosity of the mixed fluid , respectively, and 𝑔 is the gravity vector.
The fracture permeability 𝐾𝑓 is determined based on fracture aperture 𝑎 as

𝑎2
𝐾𝑓 =
12

Proppant Transport

𝜕
(𝑐) + ∇ · (𝑐𝑢𝑝 ) = 0,
𝜕𝑡
in which 𝑐 and 𝑢𝑝 represent the volume fraction and velocity of the proppant particles.

430 Chapter 1. Table of Contents

GEOS Documentation

Multi-component Fluid Transport

𝜕
[𝜌𝑖 𝜔𝑖 (1 − 𝑐)] + ∇ · [𝜌𝑖 𝜔𝑖 (1 − 𝑐)𝑢𝑓 ] = 0.
𝜕𝑡
Here 𝑢𝑓 represents the carrying fluid velocity. 𝜌𝑖 and 𝜔𝑖 denote the density and concentration of i-th component in
fluid, respectively. The fluid density 𝜌𝑓 can now be readily written as
𝑁𝑐
∑︁
𝜌𝑓 = 𝜌𝑖 𝜔𝑖 ,
𝑖=1

where 𝑁𝑐 is the number of components in fluid. Similarly, the fluid viscosity 𝜇𝑓 can be calculated by the mass fraction
weighted average of the component viscosities.
The density and velocity of the slurry fluid are further expressed as,

𝜌𝑚 = (1 − 𝑐)𝜌𝑓 + 𝑐𝜌𝑝 ,

and

𝜌𝑚 𝑢𝑚 = (1 − 𝑐)𝜌𝑓 𝑢𝑓 + 𝑐𝜌𝑝 𝑢𝑝 ,

in which 𝜌𝑓 and 𝑢𝑓 are the density and velocity of the carrying fluid, and 𝜌𝑝 is the density of the proppant particles.

Proppant Slip Velocity

The proppant particle and carrying fluid velocities are related by the slip velocity 𝑢𝑠𝑙𝑖𝑝 ,

𝑢𝑠𝑙𝑖𝑝 = 𝑢𝑝 − 𝑢𝑓 .

The slip velocity between the proppant and carrying fluid includes gravitational and collisional components, which
take account of particle settling and collision effects, respectively.
The gravitational component of the slip velocity 𝑢𝑠𝑙𝑖𝑝𝐺 is written as a form as

𝑢𝑠𝑙𝑖𝑝𝐺 = 𝐹 (𝑐)𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 ,

where 𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 is the settling velocity for a single particle, 𝑑𝑝 is the particle diameter, and 𝐹 (𝑐) is the correction factor
to the particle settling velocity in order to account for hindered settling effects as a result of particle-particle interactions,

𝐹 (𝑐) = 𝑒−𝜆𝑠 𝑐 ,

with the hindered settling coefficient 𝜆𝑠 as an empirical constant set to 5.9 by default (Barree & Conway, 1995).
The settling velocity for a single particle, 𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 , is calculated based on the Stokes drag law by default,

𝑑𝑝 2
𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 = (𝜌𝑝 − 𝜌𝑓 ) 𝑔.
18𝜇𝑓

Single-particle settling under intermediate Reynolds-number and turbulent flow conditions can also be described re-
spectively by the Allen’s equation (Barree & Conway, 1995),
[︂ ]︂0.72 (︂ )︂0.45
𝑔(𝜌𝑝 − 𝜌𝑓 ) 𝜌𝑓
𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 = 0.2𝑑1.18
𝑝 𝑒,
𝜌𝑓 𝜇𝑓

1.5. User Guide 431

GEOS Documentation

and Newton’s equation(Barree & Conway, 1995),

[︂ ]︂0.5
𝑔(𝜌𝑝 − 𝜌𝑓 )
𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 = 1.74𝑑𝑝 0.5 𝑒.
𝜌𝑓

𝑒 is the unit gravity vector and 𝑑𝑝 is the particle diameter.

The collisional component of the slip velocity is modeled by defining 𝜆, the ratio of the particle velocity to the volume
averaged mixture velocity as a function of the proppant concentration. From this the particle slip velocity in horizontal
direction is related to the mixed fluid velocity by,

𝜆−1
𝑢𝑠𝑙𝑖𝑝𝐻 = 𝑣𝑚
1−𝑐
with 𝑣 𝑚 denoting volume averaged mixture velocity. We use a simple expression of 𝜆 proposed by Barree & Conway
(1995) to correct the particle slip velocity in horizontal direction,

𝜆 = 𝛼 − |𝑐 − 𝑐𝑠𝑙𝑖𝑝 |𝛽
[︀ ]︀

where 𝛼 and 𝛽 are empirical constants, 𝑐𝑠𝑙𝑖𝑝 is the volume fraction exhibiting the greatest particle slip. By default the
model parameters are set to the values given in (Barree & Conway, 1995): 𝛼 = 1.27, 𝑐𝑠𝑙𝑖𝑝 = 0.1 and 𝛽 = 1.5. This
model can be extended to account for the transition to the particle pack as the proppant concentration approaches the
jamming transition.

Proppant Bed Build-up and Load Transport

In addition to suspended particle flow the GEOS has the option to model proppant settling into an immobile bed at the
bottom of the fracture. As the proppant cannot settle further down the proppant bed starts to form and develop at the
element that is either at the bottom of the fracture or has an underlying element already filled with particles. Such an
“inter-facial” element is divided into proppant flow and immobile bed regions based on the proppant-pack height.
Although proppant becomes immobile fluid can continue to flow through the settled proppant pack. The pack perme-
ability K is defined based on the Kozeny-Carmen relationship:

(𝑠𝑑𝑝 )2 𝜑3
𝐾=
180 (1 − 𝜑)2

and

𝜑 = 1 − 𝑐𝑠

where 𝜑 is the porosity of particle pack and 𝑐𝑠 is the saturation or maximum fraction for proppant packing, 𝑠 is the
sphericity and 𝑑𝑝 is the particle diameter.
The growth of the settled pack in an “inter-facial” element is controlled by the interplay between proppant gravitational
settling and shear-force induced lifting as (Hu et al., 2018),

𝑑𝐻 𝑐𝑢𝑠𝑒𝑡𝑡𝑙𝑖𝑛𝑔 𝐹 (𝑐) 𝑄𝑙𝑖𝑓 𝑡

= − ,
𝑑𝑡 𝑐𝑠 𝐴𝑐𝑠
where 𝐻, 𝑡, 𝑐𝑠 , 𝑄𝑙𝑖𝑓 𝑡 , and 𝐴 represent the height of the proppant bed, time, saturation or maximum proppant concne-
tration in the proppant bed, proppant-bed load (wash-out) flux, and cross-sectional area, respectively.
The rate of proppant bed load transport (or wash out) due to shear force is calculated by the correlation proposed by
Wiberg and Smith (1989) and McClure (2018),
(︃ √︃ )︃
𝑔𝑑𝑝 (𝜌𝑝 − 𝜌𝑓 ) 0.166
𝑄𝑙𝑖𝑓 𝑡 = 𝑎 𝑑𝑝 (9.64𝑁𝑠ℎ )(𝑁𝑠ℎ − 𝑁𝑠ℎ,𝑐 )1.5 .
𝜌𝑓

432 Chapter 1. Table of Contents

GEOS Documentation

𝑎 is fracture aperture, and 𝑁𝑠ℎ is the Shields number measuring the relative importance of the shear force to the
gravitational force on a particle of sediment (Miller et al., 1977; Biot & Medlin, 1985; McClure, 2018) as
𝜏
𝑁𝑠ℎ = ,
𝑑𝑝 𝑔(𝜌𝑝 − 𝜌𝑓 )

and

𝜏 = 0.125𝑓 𝜌𝑓 𝑢2𝑚

where 𝜏 is the shear stress acting on the top of the proppant bed and 𝑓 is the Darcy friction coefficient. 𝑁𝑠ℎ,𝑐 is the
critical Shields number for the onset of bed load transport.

Proppant Bridging and Screenout

Proppant bridging occurs when proppant particle size is close to or larger than fracture aperture. The aperture at which
bridging occurs, ℎ𝑏 , is defined simply by

ℎ𝑏 = 𝜆𝑏 𝑑𝑝 ,

in which 𝜆𝑏 is the bridging factor.

Slurry Fluid Viscosity

The viscosity of the bulk fluid, 𝜇𝑚 , is calculated as a function of proppant concentration as (Keck et al., 1992),
[︂ (︂ )︂]︂2
𝑐
𝜇𝑚 = 𝜇𝑓 1 + 1.25 .
1 − 𝑐/𝑐𝑠

Note that continued model development and improvement are underway and additional empirical correlations or func-
tions will be added to support the above calculations.

Spatial Discretization

The above governing equations are discretized using a cell-centered two-point flux approximation (TPFA) finite volume
method. We use an upwind scheme to approximate proppant and component transport across cell interfaces.

Solution Strategy

The discretized non-linear slurry flow and proppant/component transport equations at each time step are separately
solved by the Newton-Raphson method. The coupling between them is achieved by a time-marching sequential
(operator-splitting) solution approach.

Parameters

The solver is enabled by adding a <ProppantTransport> node and a <SurfaceGenerator> node in the Solvers
section. Like any solver, time stepping is driven by events, see Event Management.
The following attributes are supported:

1.5. User Guide 433

GEOS Documentation

XML Element: ProppantTransport

Name Type Default Description

allowNegativePressure integer 1 Flag indicating if negative
pressure is allowed
bridgingFactor real64 0 Bridging factor used for
bridging/screen-out calcu-
lation
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
criticalShieldsNumber real64 0 Critical Shields number
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
frictionCoefficient real64 0.03 Friction coefficient
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
434 Chapter 1. information
Table of Contents
- Time step
information
- Linear solver
GEOS Documentation

In particular:
• discretization must point to a Finite Volume flux approximation scheme defined in the Numerical Methods
section of the input file (see Finite Volume Discretization)
• proppantName must point to a particle fluid model defined in the Constitutive section of the input file (see
Constitutive Models)
• fluidName must point to a slurry fluid model defined in the Constitutive section of the input file (see Constitutive
Models)
• solidName must point to a solid mechanics model defined in the Constitutive section of the input file (see
Constitutive Models)
• targetRegions attribute is currently not supported, the solver is always applied to all regions.
Primary solution field labels are proppantConcentration and pressure. Initial conditions must be prescribed on
these field in every region, and boundary conditions must be prescribed on these fields on cell or face sets of interest.
For static (non-propagating) fracture problems, the fields ruptureState and elementAperture should be provided
in the initial conditions.
In addition, the solver declares a scalar field named referencePorosity and a vector field named permeability, that
contains principal values of the symmetric rank-2 permeability tensor (tensor axis are assumed aligned with the global
coordinate system). These fields must be populated via XML Element: FieldSpecification section and permeability
should be supplied as the value of coefficientName attribute of the flux approximation scheme used.

Example

First, we specify the proppant transport solver itself and apply it to the fracture region:

Then, we specify a compatible flow solver (currently a specialized SinglePhaseProppantFVM solver must be used):

<SinglePhaseProppantFVM
name="SinglePhaseFVM"
logLevel="1"
discretization="singlePhaseTPFA"
targetRegions="{ Fracture }">
<NonlinearSolverParameters
newtonTol="1.0e-8"
newtonMaxIter="8"
lineSearchAction="None"/>
<LinearSolverParameters
solverType="gmres"
(continues on next page)

1.5. User Guide 435

GEOS Documentation

(continued from previous page)

krylovTol="1.0e-12"/>
</SinglePhaseProppantFVM>

Finally, we couple them through a coupled solver that references the two above:

References

• R. D. Barree & M. W. Conway. “Experimental and numerical modeling of convective proppant transport”,
JPT. Journal of petroleum technology, 47(3):216-222, 1995.
• M. A. Biot & W. L. Medlin. “Theory of Sand Transport in Thin Fluids”, Paper presented at the SPE Annual
Technical Conference and Exhibition, Las Vegas, NV, 1985.
• X. Hu, K. Wu, X. Song, W. Yu, J. Tang, G. Li, & Z. Shen. “A new model for simulating particle transport in
a low-viscosity fluid for fluid-driven fracturing”, AIChE J. 64 (9), 35423552, 2018.
• R. G. Keck, W. L. Nehmer, & G. S. Strumolo. “A new method for predicting friction pressures and rheology
of proppant-laden fracturing fluids”, SPE Prod. Eng., 7(1):21-28, 1992.
• M. McClure. “Bed load proppant transport during slickwater hydraulic fracturing: insights from comparisons
between published laboratory data and correlations for sediment and pipeline slurry transport”, J. Pet. Sci.
Eng. 161 (2), 599610, 2018.
• M. C. Miller, I. N. McCave, & P. D. Komar. “Threshold of sediment motion under unidirectional currents”,
Sedimentology 24 (4), 507527, 1977.
• P. L. Wiberg & J. D. Smith. “Model for calculating bed load transport of sediment”, J. Hydraul. Eng. 115
(1), 101123, 1989.

1.5.4 Constitutive Models

Constitutive models describe relations between various physical quantities. In a physics simulation they are used to
model the response or state of material (solid, fluid, or a mixture) as a function of input variables. There are many types
of constitutive models available in GEOS. These models are grouped together based on their input/output interface.

Solid Models
A solid model governs the relationship between deformation and stress in a solid (or porous) material. GEOS provides
interfaces for both small and large deformation models, as well as specific implementations of a number of well known
models.

436 Chapter 1. Table of Contents

GEOS Documentation

Deformation Theories

Table of Contents

• Deformation Theories
– Introduction
– Small Strain Models
– Finite Deformation Models with Hypo-Materials
– Finite Deformation Models with Hyper-Materials

Introduction

The solid mechanics solvers in GEOS work in a time-discrete setting, in which the system state at time 𝑡𝑛 is fully known,
and the goal of the solution procedure is to advance forward one timestep to 𝑡𝑛+1 = 𝑡𝑛 + ∆𝑡. As part of this process,
calls to a solid model must be made to compute the updated stress 𝜎 𝑛+1 resulting from incremental deformation over
the timestep. History-dependent models may also need to compute updates to one or more internal state variables
𝑄𝑛+1 .
The exact nature of the incremental update will depend, however, on the kinematic assumptions made. Appropriate
measures of deformation and stress depend on assumptions of infinitesimal or finite strain, as well as other factors like
rate-dependence and material anisotropy.
This section briefly reviews three main classes of solid models in GEOS, grouped by their kinematic assumptions. The
presentation is deliberately brief, as much more extensive presentations can be found in almost any textbook on linear
and nonlinear solid mechanics.

Small Strain Models

Let 𝑢 denote the displacement field, and ∇𝑢 its gradient. In small strain theory, ones assumes the displacement gradients
∇𝑢 ≪ 1. In this case, it is sufficient to use the linearized strain tensor
1
𝜖= (∇𝑢 + 𝑢∇)
2
as the deformation measure. Higher-order terms present in finite strain theories are neglected. For inelastic problems,
this strain is additively decomposed into elastic and inelastic components as

𝜖 = 𝜖𝑒 + 𝜖𝑖 .

Inelastic strains can arise from a number of sources: plasticity, damage, etc. Most constitutive models (including
nonlinear elastic and inelastic models) can then be generically expressed in rate form as

𝜎˙ = 𝑐 : 𝜖˙𝑒

where 𝜎˙ is the Cauchy stress rate and 𝑐 is the tangent stiffness tensor. Observe that the stress rate is driven by the elastic
component 𝜖˙𝑒 of the strain rate.
In the time-discrete setting (as implemented in the code) the incremental constitutive update for stress is computed
from a solid model update routine as

𝜎 𝑛+1 = 𝜎(∆𝜖, ∆𝑡, 𝑄𝑛 ),

where ∆𝜖 = 𝜖𝑛+1 − 𝜖𝑛 is the incremental strain, ∆𝑡 is the timestep size (important for rate-dependent models), and
𝑄𝑛 is a collection of material state variables (which may include the previous stress and strain).

1.5. User Guide 437

GEOS Documentation

For path and rate independent models, such as linear elasticity, a simpler constitutive update may be formulated in
terms of the total strain:

𝜎 𝑛+1 = 𝜎(𝜖𝑛+1 ).

GEOS will use this latter form in specific, highly-optimized solvers when we know in advance that a linear elastic
model is being applied. The more general interface is the default, however, as it can accommodate a much wider range
of constitutive behavior within a common interface.
When implicit timestepping is used, the solid models must also provide the stiffness tensor,

𝜕𝜎 𝑛+1
𝑐𝑛+1 = ,
𝜕𝜖𝑛+1
in order to accurately linearize the governing equations. In many works, this fourth-order tensor is referred to as the
algorithmic or consistent tangent, in the sense that it must be “consistent” with the discrete timestepping scheme being
used (Simo and Hughes 1987). For inelastic models, it depends not only on the intrinsic material stiffness, but also the
incremental nature of the loading process. The correct calculation of this stiffness can have a dramatic impact on the
convergence rate of Newton-type solvers used in the implicit solid mechanics solvers.

Finite Deformation Models with Hypo-Materials

In the finite deformation regime, there are two broad classes of constitutive models frequently used:
• Hypo-elastic models (and inelastic extensions)
• Hyper-elastic models (and inelastic extensions)
Hypo-materials typically rely on a rate-form of the constitutive equations expressed in the spatial configuration. Let
𝑣(𝑥, 𝑡) denote the spatial velocity field. It can be decomposed into symmetric and anti-symmetric components as
1 1
𝑑= (∇𝑣 + 𝑣∇) and 𝑤= (∇𝑣 − 𝑣∇) ,
2 2
where 𝑑 is the deformation rate tensor and 𝑤 is the spin tensor. A hypo-material model can be written in rate form as

𝜏 = 𝑐 : 𝑑𝑒
˚

where ˚𝜏 is an objective rate of the Kirchoff stress tensor, 𝑐 is the tangent stiffness tensor, and 𝑑𝑒 is the elastic component
of the deformation rate. We see that the structure is similar to the rate form in the small strain regime, except the rate
of Cauchy stress is replaced with an objective rate of Kirchoff stress, and the linearized strain rate is replaced with the
deformation rate tensor.
The key difference separating most hypo-models is the choice of the objective stress rate. In GEOS, we adopt the
incrementally objective integration algorithm proposed by Hughes and Winget (1980). This method relies on the
concept of an incrementally rotating frame of reference in order to preserve objectivity of the stress rate. In particular,
the stress update sequence is
1 1
∆𝑅 = (𝐼 − ∆𝑡𝑤)−1 (𝐼 + ∆𝑡𝑤) (compute incremental rotation),
2 2
𝜏¯𝑛 = ∆𝑅𝜏 𝑛 ∆𝑅𝑇 (rotate previous stress),
𝜏 𝑛+1 𝑛
= 𝜏¯ + ∆𝜏 (call constitutive model to update stress).

First, the previous timestep stress is rotated to reflect any rigid rotations occuring over the timestep. If the model has
tensor-valued state variables besides stress, these must also be rotated. Then, a standard constitutive update routine can
be called, typically driven by the incremental strain ∆𝜖 = ∆𝑡𝑑. In fact, an identical update routine as used for small
strain models can be re-used at this point.

438 Chapter 1. Table of Contents

GEOS Documentation

ò Note

Hypo-models suffer from several well known deficiencies. Most notably, the energy dissipation in a closed loading
cycle of a hypo-elastic material is not guaranteed to be zero, as one might desire from thermodynamic considera-
tions.

Finite Deformation Models with Hyper-Materials

Hyper-elastic models (and inelastic extensions) attempt to correct the thermodynamic deficiencies of their hypo-elastic
cousins. The constitutive update can be generically expressed at

𝑆 𝑛+1 = 𝑆(∆F, 𝑄𝑛 , ∆𝑡),

where 𝑆 is the second Piola-Kirchoff stress and ∆F is the incremental deformation gradient. Depending on the model,
the deformation gradient can be converted to different deformation measures as needed. Similarly, different stress
tensors can be recovered through appropriate push-forward and pull-back operations.
In a hyperelastic material, the elastic response is expressed in terms of a stored strain-energy function that serves as the
potential for stress, e.g.

𝜕𝜓(𝐶)
S= ,
𝜕𝐶
where 𝜓 is the stored energy potential, and 𝐶 is the right Cauchy-Green deformation tensor. This potential guarantees
that the energy dissipated or gained in a closed elastic cycle is zero.

Voigt Notation

In GEOS we express rank-two symmetric tensors using Voigt notation. Stress tensors are represented as an “unrolled”
six-component vector storing only the unique component values. For strain tensors, note that engineering strains are
used such that the shear components of strain are multiplied by a factor of two. With this representation, the strain
energy density is, conveniently, the inner product of the stress and strain vectors.
Voigt representation of common rank-2 symmetric tensors are:
⎡ ⎤ ⎡ ⎤ ⎡ ⎤ ⎡ ⎤ ⎡ ⎤ ⎡ ⎤ ⎡ ⎤
𝜎11 𝑆11 𝜖11 𝐷11 𝐸11 𝐵11 𝐶11
⎢ 𝜎22 ⎥ ⎢𝑆22 ⎥ ⎢ 𝜖22 ⎥ ⎢ 𝐷22 ⎥ ⎢ 𝐸22 ⎥ ⎢ 𝐵22 ⎥ ⎢ 𝐶22 ⎥
⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥
⎢ 𝜎33 ⎥ ⎢𝑆33 ⎥ ⎢ 𝜖33 ⎥ ⎢ 𝐷33 ⎥ ⎢ 𝐸33 ⎥ ⎢ 𝐵33 ⎥ ⎢ 𝐶33 ⎥
𝜎=⎢ ⎢
⎥ , S = ⎢𝑆23 ⎥ , 𝜖 = ⎢ 2𝜖23 ⎥ , D = ⎢2𝐷23 ⎥ , E = ⎢2𝐸23 ⎥ , B = ⎢2𝐵23 ⎥ , C = ⎢2𝐶23 ⎥ ,
⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥
⎢ 𝜎23 ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥ ⎢ ⎥
⎣ 𝜎13 ⎦ ⎣𝑆13 ⎦ ⎣ 2𝜖13 ⎦ ⎣2𝐷13 ⎦ ⎣2𝐸13 ⎦ ⎣2𝐵13 ⎦ ⎣2𝐶13 ⎦
𝜎12 𝑆12 2𝜖12 2𝐷12 2𝐸12 2𝐵12 2𝐶12

where 𝜎 is the Cauchy stress, S is the second Piola-Kirchhoff stress, 𝜖 is the small strain tensor, D is the rate of
deformation tensor, E is the Lagrangian finite strain tensor, B is the left Cauchy-Green tensor, C is the right Cauchy-
Green deformation tensor.

ò Note

The factor of two in the shear components of strain (and strain-like) quantities is a frequent source of confusion, even
for expert modelers. It can be particularly challenging to use in nuanced situations like stiffness tensor calculations
or invariant decompositions. If you plan to implement new models within GEOS, please pay extra attention to this
detail. We also provide many common operations in centralized helper functions to avoid re-inventing the wheel.

1.5. User Guide 439

GEOS Documentation

Plasticity Notation

Table of Contents

• Plasticity Notation
– Overview
– Two-Invariant Models
– Three-Invariant Models

Overview

According to the theory of plasticity in the small strain regime, the total strain 𝜖 can be additively split into elastic (𝜖𝑒 )
and plastic (𝜖𝑝 ) strains:

𝜖 = 𝜖𝑒 + 𝜖 𝑝 .

The plastic strain tensor is obtained from the flow rule:

𝜕𝑔
𝜖˙ 𝑝 = 𝜆˙ ,
𝜕𝜎
in which 𝜆˙ ≥ 0 is the magnitude of plastic strain rate and 𝑔 is the plastic potential. The elastic strain is related to
Cauchy stress tensor in rate form as:

𝜎˙ = 𝑐𝑒 : 𝜖˙ 𝑒 ,

where 𝑐𝑒 is the fourth order elastic stiffness tensor. The Cauchy stress tensor is related to the total strain as

𝜎˙ = 𝑐𝑒𝑝 : 𝜖,
˙

in which 𝑐𝑒𝑝 is the fourth order elasto-plastic stiffness tensor.

Two-Invariant Models

Two-invariant plasticity models use the first invariant of the Cauchy stress tensor and the second invariant of the devi-
atoric stress tensor to describe the yield surface.
√
Here we use the following stress invariants to define the yield surface: the von Mises stress 𝑞 = 3𝐽2 = 3/2‖𝑠‖
√︀

and mean normal stress 𝑝 = 𝐼1 /3. Here, 𝐼1 and 𝐽2 are the first invariant of the stress tensor and second invariant of
the deviatoric stress, defined as
1
𝐼1 = 𝑡𝑟(𝜎)/3 , 𝐽2 = ‖𝑠‖2 , 𝑠 = 𝜎 − 𝑝1 ,
2
in which 1 is the identity tensor.
Similarly, we can define invariants of strain tensor, namely, volumetric strain 𝜖𝑣 and deviatoric strain 𝜖𝑠 .
√︂
2 1
𝜖𝑣 = 𝑡𝑟(𝜖) , 𝜖𝑠 = ‖𝑒‖ , where 𝑒 = 𝜖 − 𝜖𝑣 1.
3 3
Stress and strain tensors can then be recomposed from the invariants as:
√︂
2
𝜎 = 𝑝1 + ˆ
𝑞𝑛
3

440 Chapter 1. Table of Contents

GEOS Documentation

√︂
1 3
𝜖 = 𝜖𝑣 1 + ˆ
𝜖𝑠 𝑛
3 2
in which 𝑛
ˆ = 𝑒/‖𝑒‖.
The following two-invariant models are currently implemented in GEOS:
• DruckerPrager
• J2Plasticity
• ModifiedCamClay
• DelftEgg

Three-Invariant Models

Several three-invariant models are under active development, but are not yet available in develop. If you are interested
in helping to add additional material models, please submit a feature request.

Model: Elastic Isotropic

Overview

This model may be used for solid materials with a linear elastic isotropic behavior. The relationship between stress and
strain is given by Hooke’s Law, expressed as:

𝜎𝑖𝑗 = 𝜆𝜖𝑘𝑘 + 2𝜇𝜖𝑖𝑗 ,

where 𝜎𝑖𝑗 is the 𝑖𝑗 component of the Cauchy stress tensor, 𝜖𝑖𝑗 is the 𝑖𝑗 component of the strain tensor, 𝜆 is the first
Lamé elastic constant, and 𝜇 is the elastic shear modulus.
Hooke’s Law may also be expressed using Voigt notation for stress and strain vectors as:

𝜎 = 𝐶 · 𝜖,

or,
⎡ ⎤ ⎡ ⎤⎡ ⎤
𝜎11 2𝜇 + 𝜆 𝜆 𝜆 0 0 0 𝜖11
⎢𝜎22 ⎥ ⎢ 𝜆 2𝜇 + 𝜆 𝜆 0 0 0⎥⎥ ⎢ 𝜖22 ⎥
⎢ ⎥
⎢ ⎥ ⎢
⎢𝜎33 ⎥ ⎢ 𝜆 𝜆 2𝜇 + 𝜆 0 0 0⎥ ⎢ 𝜖33 ⎥
⎢ ⎥=⎢ ⎥⎢ ⎥.
⎢𝜎23 ⎥ ⎢ 0 0 0 𝜇 0 0⎥⎥ ⎢2𝜖23 ⎥
⎢ ⎥
⎢ ⎥ ⎢
⎣𝜎13 ⎦ ⎣ 0 0 0 0 𝜇 0 ⎦ ⎣2𝜖13 ⎦
𝜎12 0 0 0 0 0 𝜇 2𝜖12

Variations

For finite deformation solvers, the elastic isotropic model can be called within a hypo-elastic update routine. See Finite
Deformation Models with Hypo-Materials

Parameters

The following attributes are supported. Note that any two elastic constants can be provided, and the other two will be
internally calculated. The “default” keyword in front of certain properties indicates that this is the default value adopted
for a region unless the user separately specifies a heterogeneous field via the FieldSpecification mechanism.

1.5. User Guide 441

GEOS Documentation

XML Element: ElasticIsotropic

Name Type De- Description

fault
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYoungModulus real64 -1 Default Young’s Modulus
name group- re- A name is required for any non-unique nodes
Name quired

Example

A typical Constititutive block will look like:

Model: Elastic Isotropic Pressure Dependent

Overview

This model may be used for solid materials with a pressure-dependent elastic isotropic behavior. The relationship
between stress and strain is given by a hyperelastic law. The elastic constitutive equations for the volumetric and
deviatoric stresses and strain are expressed as:

𝜖𝑣0 − 𝜖𝑒𝑣
(︂ )︂
𝑝 = 𝑝0 exp , 𝑞 = 3𝜇𝜖𝑒𝑠
𝑐𝑟

where 𝑝 and 𝑞 are the volumetric and deviatoric components of the Cauchy stress tensor. 𝜖𝑒𝑣 and 𝜖𝑒𝑠 are the volumetric
and deviatoric components of the strain tensor. 𝜖𝑣0 and 𝑝0 are the initial volumetric strain and initial pressure. 𝐶𝑟
denotes the elastic compressibility index, and 𝜇 is the elastic shear modulus. In this model, the shear modulus is
constant and the bulk modulus, 𝐾, varies linearly with pressure as follows:
𝑝
𝐾=−
𝑐𝑟

Parameters

The following attributes are supported. Note that two elastic constants 𝑐𝑟 and 𝜇, as well as the initial volumetric strain
and initial pressure need to be provided. The “default” keyword in front of certain properties indicates that this is the de-
fault value adopted for a region unless the user separately specifies a heterogeneous field via the FieldSpecification
mechanism.

442 Chapter 1. Table of Contents

GEOS Documentation

Example

A typical Constititutive block will look like:

Model: Elastic Transverse-Isotropic

Overview

This model may be used for solid materials with a linear elastic, transverse-isotropic behavior. This is most readily
expressed in Voight notation as
⎡ ⎤ ⎡ ⎤⎡ ⎤
𝜎11 𝐶11 𝐶12 𝐶13 0 0 0 𝜖11
⎢𝜎22 ⎥ ⎢𝐶12 𝐶11 𝐶13 0 0 0 ⎥ ⎢ 𝜖22 ⎥
⎢ ⎥ ⎢ ⎥⎢ ⎥
⎢𝜎33 ⎥ ⎢𝐶13 𝐶13 𝐶33 0 0 0 ⎥ ⎢ 𝜖33 ⎥
⎢ ⎥=⎢
⎥ ⎢2𝜖23 ⎥ .
⎥⎢ ⎥
⎢𝜎23 ⎥ ⎢ 0 0 0 𝐶44 0 0
⎢ ⎥ ⎢ ⎥⎢ ⎥
⎣𝜎13 ⎦ ⎣ 0 0 0 0 𝐶44 0 ⎦ ⎣2𝜖13 ⎦
𝜎12 0 0 0 0 0 (𝐶11 − 𝐶12 )/2 2𝜖12

This system contains five independent constants. These constants are calculated from the input parameters indicated
below.

Parameters

The following attributes are supported. The “default” keyword in front of certain properties indicates that this is the de-
fault value adopted for a region unless the user separately specifies a heterogeneous field via the FieldSpecification
mechanism.

1.5. User Guide 443

GEOS Documentation

XML Element: ElasticTransverseIsotropic

Name Type De- Description

fault
defaultC11 real64 -1 Default Stiffness Parameter C11
defaultC13 real64 -1 Default Stiffness Parameter C13
defaultC33 real64 -1 Default Stiffness Parameter C33
defaultC44 real64 -1 Default Stiffness Parameter C44
defaultC66 real64 -1 Default Stiffness Parameter C66
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLinearTEC real64 0 Default Linear Thermal Expansion Coefficient of the Solid
Rock Frame
defaultPoissonRatioAxial- real64 -1 Default Axial-Transverse Poisson’s Ratio
Transverse
defaultPoissonRatioTransverse real64 -1 Default Transverse Poisson’s Ratio
defaultShearModulusAxial- real64 -1 Default Axial-Transverse Shear Modulus
Transverse
defaultYoungModulusAxial real64 -1 Default Axial Young’s Modulus
defaultYoungModulusTrans- real64 -1 Default Transverse Young’s Modulus
verse
name group- re- A name is required for any non-unique nodes
Name quired

Example

A typical Constititutive block will look like:

Model: Elastic Orthotropic

Overview

This model may be used for solid materials with a linear elastic, orthotropic behavior. This is most readily expressed
in Voight notation as
⎡ ⎤ ⎡ ⎤⎡ ⎤
𝜎11 𝐶11 𝐶12 𝐶13 0 0 0 𝜖11
⎢𝜎22 ⎥ ⎢𝐶12 𝐶22 𝐶23 0 0 0 ⎥⎥ ⎢ 𝜖22 ⎥
⎢ ⎥
⎢ ⎥ ⎢
⎢𝜎33 ⎥ ⎢𝐶13 𝐶23 𝐶33 0 0 0 ⎥ ⎢ 𝜖33 ⎥
⎥ ⎢
⎢ ⎥=⎢ ⎥.
⎢𝜎23 ⎥ ⎢ 0 0 0 𝐶44 0 0 ⎥⎥ ⎢2𝜖23 ⎥
⎢ ⎥
⎢ ⎥ ⎢
⎣𝜎13 ⎦ ⎣ 0 0 0 0 𝐶55 0 ⎦ ⎣2𝜖13 ⎦
𝜎12 0 0 0 0 0 𝐶66 2𝜖12

444 Chapter 1. Table of Contents

GEOS Documentation

This system contains nine independent constants. These constants are calculated from the input parameters indicated
below.

Parameters

XML Element: ElasticOrthotropic

Name Type De- Description

fault
defaultC11 real64 -1 Default C11 Component of Voigt Stiffness Tensor
defaultC12 real64 -1 Default C12 Component of Voigt Stiffness Tensor
defaultC13 real64 -1 Default C13 Component of Voigt Stiffness Tensor
defaultC22 real64 -1 Default C22 Component of Voigt Stiffness Tensor
defaultC23 real64 -1 Default C23 Component of Voigt Stiffness Tensor
defaultC33 real64 -1 Default C33 Component of Voigt Stiffness Tensor
defaultC44 real64 -1 Default C44 Component of Voigt Stiffness Tensor
defaultC55 real64 -1 Default C55 Component of Voigt Stiffness Tensor
defaultC66 real64 -1 Default C66 Component of Voigt Stiffness Tensor
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultE1 real64 -1 Default Young’s Modulus E1
defaultE2 real64 -1 Default Young’s Modulus E2
defaultE3 real64 -1 Default Young’s Modulus E3
defaultG12 real64 -1 Default Shear Modulus G12
defaultG13 real64 -1 Default Shear Modulus G13
defaultG23 real64 -1 Default Shear Modulus G23
defaultNu12 real64 -1 Default Poission’s Ratio Nu12
defaultNu13 real64 -1 Default Poission’s Ratio Nu13
defaultNu23 real64 -1 Default Poission’s Ratio Nu23
name group- re- A name is required for any non-unique nodes
Name quired

Example

A typical Constititutive block will look like:

<Constitutive>
<ElasticOrthotropic
name="shale"
defaultDensity="2700"
defaultNu12="0.20"
defaultNu13="0.25"
defaultNu23="0.30"
defaultE1="40.0e6"
defaultE2="50.0e6"
defaultE3="60.0e6"
(continues on next page)

1.5. User Guide 445

GEOS Documentation

(continued from previous page)

defaultG12="20.0e6"
defaultG13="30.0e6"
defaultG23="40.0e6" />
</Constitutive>

Model: Drucker-Prager

Overview

This model may be used to represent a solid material with plastic response to loading according to the Drucker-Prager
yield criterion below:

𝑓 (𝑝, 𝑞) = 𝑞 + 𝑏 𝑝 − 𝑎 = 0.

Fig. 1.83: Mohr-Coulomb and Drucker-Prager yield surfaces in principal stress axes (Borja, 2002).

The material behavior is linear elastic (see Model: Elastic Isotropic) for 𝑓 < 0, and plastic for 𝑓 = 0. The two material
parameters 𝑎 and 𝑏 are derived by approximating the Mohr-Coulomb surface with a cone. Figure 3 shows the Mohr-
Coulomb yield surface and circumscribing Drucker-Prager surface in principal stress space. The Drucker-Prager yield
surface has a circular cross-section in the deviatoric plane that passes through the tension or compression corners of
the Mohr-Coulomb yield surface, as shown in the Figure 4. The material parameters 𝑎 and 𝑏 are derived as:
6 𝑐 cos 𝜑 6 sin 𝜑
𝑎= , 𝑏=
3 ± sin 𝜑 3 ± sin 𝜑
where plus signs are for circles passing through the tension corners, and minus signs are for circles passing through
compression corners. Also, 𝜑 and 𝑐 denote friction angle and cohesion, respectively, as defined by the Mohr-Coulomb

446 Chapter 1. Table of Contents

GEOS Documentation

failure envelope shown in Figure 5. In GEOS, we use a compression corner fit (minus signs) to convert the user-specified
friction angle and cohesion to 𝑎 and 𝑏.

Fig. 1.84: Mohr-Coulomb and Drucker-Prager yield surfaces on the deviatoric plane (Borja, 2013).

Fig. 1.85: The Mohr-Coulomb failure envelope (Borja, 2013).

We consider a non-associative plastic potential to determine the direction of plastic flow.

𝑔(𝑝, 𝑞) = 𝑞 + 𝑏′ 𝑝,

where 𝑏′ ≤ 𝑏 is the dilatancy parameter. Setting 𝑏′ = 𝑏 leads to associative flow rule, while for 𝑏′ < 𝑏 non-associative
flow is obtained. The parameter 𝑏′ is related to dilation angle as:
6 sin 𝜓
𝑏′ = ,
3 ± sin 𝜓
where 𝜓 ≤ 𝜑 is the dilation angle. If 𝜓 > 0, then the plastic flow is dilative. Again, we use a compression corner fit
(minus sign).
A hardening rule is defined which determines how the yield surface will change as a result of plastic deformations.
Here we use linear hardening for the cohesion parameter, 𝑎,
˙
𝑎˙ = ℎ 𝜆,

1.5. User Guide 447

GEOS Documentation

where ℎ is the hardening parameter. A positive hardening parameter will allow the cohesion to grow, shifting the co-
hesion intercept vertically on the q-axis. A negative hardening parameter will cause the cohesion to shrink, though
negative cohesion values are not allowed. Once all cohesion has been lost, the cohesion will remain at zero, so the cone
vertex is fixed at the origin. In either case, the friction and dilation angles remain constant. See the DruckerPragerEx-
tended model for an alternative version of hardening behavior.

Parameters

The following attributes are supported:

XML Element: DruckerPrager

Name Type De- Description

fault
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultCohesion real64 0 Initial cohesion
defaultDensity real64 re- Default Material Density
quired
defaultDilationAngle real64 30 Dilation angle (degrees)
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultFrictionAngle real64 30 Friction angle (degrees)
defaultHardeningRate real64 0 Cohesion hardening/softening rate
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYoungModulus real64 -1 Default Young’s Modulus
name group- re- A name is required for any non-unique nodes
Name quired

Example

Variant: J2 plasticity

J2 yield criterion can be obtained as a special case of the Drucker-Prager model by setting the friction and dilation
angles to zero, i.e. 𝜑 = 𝜓 = 0.

448 Chapter 1. Table of Contents

GEOS Documentation

Model: Extended Drucker-Prager

Overview

This model implements a more sophisticated version of the Drucker-Prager model (see Model: Drucker-Prager) al-
lowing for both cohesion and friction hardening / softening. We implement the specific hardening model reported in
Liu et al. (2020). The yield surface is given by
(︂ )︂
𝑎𝑖
𝑓 (𝑝, 𝑞) = 𝑞 + 𝑏 𝑝 − = 0,
𝑏𝑖

where 𝑏 is the current yield surface slope, 𝑏𝑖 is the initial slope, and 𝑎𝑖 is the initial cohesion intercept in p-q space.
The vertex of the Drucker-Prager cone is fixed at 𝑝 = 𝑎𝑖 /𝑏𝑖 . Let 𝜆 denote the accumulated plastic strain measure. The
current yield surface slope is given by the hyperbolic relationship
𝜆
𝑏 = 𝑏𝑖 + (𝑏𝑟 − 𝑏𝑖 )
𝑚+𝜆
with 𝑚 a parameter controlling the hardening rate. Here, 𝑏𝑟 is the residual yield surface slope. If 𝑏𝑟 < 𝑏𝑖 , hardening
behavior will be observed, while for 𝑏𝑟 < 𝑏𝑖 softening behavior will occur.
In the resulting model, the yield surface begins at an initial position defined by the initial cohesion and friction angle.
As plastic deformation occurs, the friction angle hardens (or softens) so that it asymptoptically approaches a residual
friction angle. The vertex of the cone remains fixed in p-q space, but the cohesion intercept evolves in tandem with the
friction angle. See Liu et al. (2020) <https://doi.org/10.1007/s00603-019-01992-5> for complete details.
In order to allow for non-associative behavior, we define a “dilation ratio” parameter 𝜃 ∈ [0, 1] such that 𝑏′ = 𝜃𝑏,
where 𝑏′ is the slope of the plastic potential surface, while 𝑏 is the slope of the yield surface. Choosing 𝜃 = 1 leads to
associative behavior, while 𝜃 = 0 implies zero dilatancy.

Parameters

The supported attributes will be documented soon.

Example

Model: Modified Cam-Clay

This model may be used to represent a solid material with plastic response to loading according to the Modified Cam-
Clay (MCC) critical state model. The MCC yield function is defined as:

𝑓 = 𝑞 2 + 𝑀 2 𝑝(𝑝 − 𝑝𝑐 ) = 0,

1.5. User Guide 449

GEOS Documentation

where 𝑝𝑐 is the preconsolidation pressure, and 𝑀 is the slope of the critical state line (CSL). 𝑀 can be related to the
critical state friction angle 𝜑𝑐𝑠 as

6 sin 𝜑𝑐𝑠
𝑀= .
3 − sin 𝜑𝑐𝑠
Here 𝑓 represents the yield surface, as shown in Figure 6.

Fig. 1.86: Cam-Clay and Modified Cam-Clay yield surfaces in p-q space (Borja, 2013).

Here we use a hyper-elastic constitutive law using the following elastic rate constitutive equation
𝑝 𝑒
𝑝˙ = − 𝜖˙ ,
𝑐𝑟 𝑣
where 𝑐𝑟 > 0 is the elastic compressibility index. The tangential elastic bulk modulus is 𝐾 = − 𝑐𝑝𝑟 and varies linearly
with pressure. We assume a constant shear modulus, and can write stress invariants p and q as

𝜖𝑣0 − 𝜖𝑒𝑣
(︂ )︂
𝑝 = 𝑝0 exp , 𝑞 = 3𝜇𝜖𝑒𝑠 ,
𝑐𝑟

where 𝑝0 is the reference pressure and 𝜖𝑣0 is the reference volumetric strain. The hardening law is derived from the
linear relationship between logarithm of specific volume and logarithm of preconsolidation pressure, as show in Figure
7.
The hardening law describes evolution of the preconsolidation pressure 𝑝𝑐 as

𝑡𝑟(𝜖˙ 𝑝 )
𝑝˙𝑐 = − 𝑝𝑐 ,
𝑐𝑐 − 𝑐𝑟
where 𝑐𝑐 is the virgin compressibility index and we have 0 < 𝑐𝑟 < 𝑐𝑐 .

Parameters

The supported attributes will be documented soon.

Example

450 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.87: Bilogarithmic hardening law derived from isotropic compression tests (Borja, 2013).

Model: Delft Egg

The Delft-Egg plasticity model uses a generalization of the Modified Cam-Clay yield surface, defined as

𝛼2 (𝛼 − 1) 2
[︂ (︂ )︂ ]︂
2𝛼 𝛼
𝑓 = 𝑞 2 − 𝑀 2 𝛼2 𝑝 𝑝𝑐 − 𝑝 − 𝑝𝑐 = 0 (for 𝑝𝑐 > )
𝛼+1 𝛼+1 𝛼+1
(︂ )︂
2 2 2𝛼 𝛼
𝑓 =𝑞 −𝑀 𝑝 𝑝𝑐 − 𝑝 = 0 (for 𝑝𝑐 ≤ )
𝛼+1 𝛼+1
where 𝛼 ≥ 1 is the shape parameter. For 𝛼 = 1, this model leads to a Modified Cam-Clay (MCC) type model with an
ellipsoidal yield surface. For 𝛼 > 1, an egg-shaped yield surface is obtained. The additional parameter makes it easier
to fit the cap behavior of a broader range of soils and rocks.
Because Delft-Egg is frequently used for hard rocks, GEOS uses a linear model for the elastic response, rather than the
hyper-elastic model used for MCC. This is a slight deviation from the original formulation proposed in the reference
above. For reservoir applications, the ability to use a simpler linear model was a frequent user request.

1.5. User Guide 451

GEOS Documentation

Parameters

The supported attributes will be documented soon.

Example

Damage Models

The damage models are in active development, and documentation will be added when they are ready for production
release.

Model: Viscoplasticity

The classical Perzyna-type viscoplasticity models are not suitable for rate-dependent viscoplastic models with non-
smooth multisurface, because of using unclearly defined nested viscoplastic loading surfaces. As an alternative, the
Duvaut-Lions viscoplastic theory, precludes these difficulties by excluding the concept of nested viscoplastic loading
surfaces. The viscoplastic constitutive equation that relates the stress 𝜎 and the viscoplastic strain rate 𝜖𝑣𝑝
˙ is given by:

1
𝜎−𝜎
¯= ˙
𝑐 : 𝜖𝑣𝑝
𝑡*
Here, 𝜎¯ represents the inviscid stress, which is the rate-independent elasto-plastic stress part that can be solved by using
elasto-plastic solvers (such as Drucker-Prager, CamClay, etc.). 𝑐 is the tangent stiffness tensor and 𝑡* is the relaxation
time, which is measured in units of time. The viscoplastic strain rate 𝜖˙ 𝑣𝑝 can be approximated using the following finite
difference formula:
1
˙ =
𝜖𝑣𝑝 (∆𝜖 − ∆𝜖𝑒𝑙𝑎𝑠 )
∆𝑡
Here, ∆𝑡 is the time increment, ∆𝜖 is the total strain increment, and ∆𝜖𝑒𝑙𝑎𝑠 is the elastic part of the strain increment.
Note that the elastic strain increment is related to the stress increment through Hook’s law.

∆𝜎 = 𝑐 : ∆𝜖𝑒𝑙𝑎𝑠

With some arrangements, we can obtain the following formula to update the stress tensor of the Duvaut-Lions elasto-
viscoplastic materials:

ˆ + (1 − 𝑟𝑡 )𝜎
𝜎 = 𝑟𝑡 𝜎 ¯

Here, the time ratio 𝑟𝑡 is calculated from the relaxation time 𝑡* and the time increment ∆𝑡 as:
1
𝑟𝑡 =
1 + ∆𝑡/𝑡*

452 Chapter 1. Table of Contents

GEOS Documentation

Assuming elastic behavior, the trial stress tensor 𝜎

ˆ is computed using the strain increment:

ˆ 𝑡+Δ𝑡 = 𝜎 𝑡 + 𝑐𝑡+Δ𝑡 : ∆𝜖𝑡+Δ𝑡

𝜎

The tangent stiffness tensor is updated using the following equivalent approximation:

𝑐𝑡+Δ𝑡 = 𝑟𝑡 𝑐𝑒 + (1 − 𝑟𝑡 )𝑐𝑡

Here, 𝑐𝑒 is the elastic stiffness tensor.

The name of the viscoplastic solver is formed by adding the prefix Visco to the name of the elasto-plastic solver used to
compute the inviscid stress 𝜎. For example, the solver Visco Drucker-Prager corresponds to cases where the inviscid
stress is computed by the Drucker-Prager solver. It is interesting to note that equivalent viscoelastic solutions can also
be obtained using the Duvault-Lions algorithm by updating the inviscid stress with an elastic solver.

Fluid Models
These models provide density, viscosity, and composition relationships for single fluids and fluid mixtures.

Compressible single phase fluid model

Overview

This model represents a compressible single-phase fluid with constant compressibility and pressure-dependent viscos-
ity. These assumptions are valid for slightly compressible fluids, such as water, and some types of oil with negligible
amounts of dissolved gas.
Specifically, fluid density is computed as

𝜌(𝑝) = 𝜌0 𝑒𝑐𝜌 (𝑝−𝑝0 )

where 𝑐𝜌 is compressibility, 𝑝0 is reference pressure, 𝜌0 is density at reference pressure. Similarly,

𝜇(𝑝) = 𝜇0 𝑒𝑐𝜇 (𝑝−𝑝0 )

where 𝑐𝜇 is viscosibility (viscosity compressibility), 𝜇0 is reference viscosity.

Either exponent may be approximated by linear (default) or quadratic terms of Taylor series expansion. Currently there
is no temperature dependence in the model, although it may be added in future.

Parameters

The model is represented by <CompressibleSinglePhaseFluid> node in the input.

The following attributes are supported:

1.5. User Guide 453

GEOS Documentation

XML Element: CompressibleSinglePhaseFluid

Name Type Default Description

compressibility real64 0 Fluid compressibility
defaultDensity real64 required Default value for density.
defaultViscosity real64 required Default value for viscosity.
densityModelType geos_constitutive_ExponentApproximationType
linear
Type of density model.
Valid options:
* exponential
* linear
* quadratic

name groupName required A name is required for any

non-unique nodes
referenceDensity real64 1000 Reference fluid density
referencePressure real64 0 Reference pressure
referenceViscosity real64 0.001 Reference fluid viscosity
viscosibility real64 0 Fluid viscosity exponen-
tial coefficient
viscosityModelType geos_constitutive_ExponentApproximationType
linear
Type of viscosity model.
Valid options:
* exponential
* linear
* quadratic

Example

Black-oil fluid model

Overview

In the black-oil model three pseudo-components, oil (o), gas (g) and water (w) are considered. These are assumed to
be partitioned across three fluid phases, named liquid (l), vapor (v) and aqueous (a).
Phase behavior is characterized by the following quantities which are used to relate properties of the fluids in the
reservoir to their properties at surface conditions.
• 𝐵𝑜 : oil formation volume factor

454 Chapter 1. Table of Contents

GEOS Documentation

• 𝐵𝑔 : gas formation volume factor

• 𝑅𝑠 : gas/oil ratio
• 𝑅𝑣 : oil/gas ratio
By tables, that tabulate saturated and undersaturated oil and gas properties as functions of pressure and solution ratios.

Dead oil

In dead-oil each component occupies only one phase. Thus, the following partition matrix determines the components
distribution within the three phases:
⎡ ⎤ ⎡ ⎤
𝑦𝑔𝑣 𝑦𝑔𝑙 𝑦𝑔𝑎 1 0 0
⎣ 𝑦𝑜𝑣 𝑦𝑜𝑙 𝑦𝑜𝑎 ⎦ = ⎣0 1 0⎦
𝑦𝑤𝑣 𝑦𝑤𝑙 𝑦𝑤𝑎 0 0 1

and the phase densities are

𝜌𝑆𝑇
𝑜
𝐶
𝜌𝑙 =
𝐵𝑜
𝜌𝑆𝑇
𝑔
𝐶
𝜌𝑣 = .
𝐵𝑔

Live oil

The live oil fluid model make no assumptions about the partitioning of the hydrocarbon components and the following
composition matrix can be used
𝜌𝑆𝑇 𝐶
𝜌𝑆𝑇 𝐶
⎡ ⎤
𝑔 𝑔 𝑅𝑠
0
⎡ ⎤
𝑦𝑔𝑣 𝑦𝑔𝑙 𝑦𝑔𝑎 𝑆𝑇 𝐶 𝑆𝑇 𝐶
⎢ 𝜌𝑔 +𝜌𝑜 𝑟𝑠 𝜌𝑜 +𝜌𝑔 𝑅𝑠𝑆𝑇 𝐶 𝑆𝑇 𝐶
⎥
⎢ ⎥ ⎢ ⎥
⎢ ⎥ ⎢ ⎥
⎢ 𝑦𝑜𝑣 𝑦𝑜𝑙 𝑦𝑜𝑎 ⎥ = ⎢ 𝜌𝑆𝑇 𝐶
𝑟 𝑠 𝜌 𝑆𝑇 𝐶
⎥ ⎢ 𝜌𝑆𝑇 𝐶𝑜+𝜌𝑆𝑇 𝐶 𝑟𝑠 𝜌𝑆𝑇 𝐶 +𝜌 𝑜
0
⎥
⎢ 𝑆𝑇 𝐶 𝑅 ⎥
⎣ ⎦ ⎢ 𝑔 𝑜 𝑜 𝑔 𝑠 ⎥
⎣ ⎦
𝑦𝑤𝑣 𝑦𝑤𝑙 𝑦𝑤𝑎
0 0 1

whereas the densities of the two hydrocarbon phases are

𝜌𝑆𝑇
𝑜
𝐶
+ 𝜌𝑆𝑇
𝑔
𝐶
𝑅𝑠
𝜌𝑙 =
𝐵𝑜
𝜌𝑆𝑇
𝑔
𝐶
+ 𝜌𝑆𝑇
𝑜
𝐶
𝑅𝑣
𝜌𝑣 =
𝐵𝑔

See Petrowiki for more information.

Parameters

Both types are represented by <BlackOilFluid> node in the input. Under the hood this is a wrapper around
PVTPackage library, which is included as a submodule. In order to use the model, GEOS must be built with
-DENABLE_PVTPACKAGE=ON (default).
The following attributes are supported:

1.5. User Guide 455

GEOS Documentation

456 Chapter 1. Table of Contents

GEOS Documentation

XML Element: BlackOilFluid

Name Type Default Description

checkPVTTablesRanges integer 1 Enable (1) or disable (0)
an error when the input
pressure or temperature of
the PVT tables is out of
range.
componentMolarWeight real64_array required Component molar weights
componentNames string_array {} List of component names
hydrocarbonFormation- groupNameRef_array {}
VolFactorTableNames
List of formation volume
factor TableFunction
names from the Functions
block.
The user must provide
one TableFunction per
hydrocarbon phase, in the
order provided in
“phaseNames”.
For instance, if “oil” is
before “gas” in
“phaseNames”, the table
order should be:
oilTableName,
gasTableName

hydrocarbonViscosi- groupNameRef_array {}
tyTableNames
List of viscosity
TableFunction names
from the Functions block.
The user must provide
one TableFunction per
hydrocarbon phase, in the
order provided in
“phaseNames”.
For instance, if “oil” is
before “gas” in
“phaseNames”, the table
order should be:
oilTableName,
gasTableName

name groupName required A name is required for any

non-unique nodes
phaseNames groupNameRef_array required List of fluid phases
surfaceDensities real64_array required List of surface mass densi-
ties for each phase
tableFiles path_array {} List of filenames with in-
put PVT tables (one per
phase)
waterCompressibility real64 0 Water compressibility
waterFormationVolume- real64 0 Water formation volume
Factor
1.5. User Guide factor 457
waterReferencePressure real64 0 Water reference pressure
waterViscosity real64 0 Water viscosity
GEOS Documentation

Supported phase names are:

Value Comment
oil Oil phase
gas Gas phase
water Water phase

Example

Compositional multiphase fluid model

Overview

This model represents a full composition description of a multiphase multicomponent fluid. Phase behavior is modeled
by an equation of state (EOS) and partitioning of components into phases is computed based on instantaneous chemical
equilibrium via a two-phase flash. Each component (species) is characterized by molar weight and critical properties
that serve as input parameters for the EOS. See Petrowiki for more information.
In this model the fluid is described by 𝑁𝑐 components with 𝑧𝑐 being the total mole fraction of component 𝑐. The fluid
can partition into a liquid phase, denoted ℓ, and a vapor phase denoted by 𝑣. Therefore, by taking into account the
molar phase component fractions, (which is the fraction of the molar mass of phase 𝑝 represented by component 𝑐), the
following partition matrix establishes the component distribution within the two phases:
[︂ ]︂
𝑥1 𝑥2 𝑥3 · · · 𝑥𝑁𝑐
𝑦1 𝑦2 𝑦3 · · · 𝑦𝑁𝑐
where 𝑥𝑐 is the mole fraction of component 𝑐 in the liquid phase and 𝑦𝑐 is the mole fraction of component 𝑐 in the
vapor phase.
The fluid properties are updated through the following steps:
1) The phase fractions (𝜈𝑝 ) and phase component fractions (𝑥𝑐 and 𝑦𝑐 ) are computed as a function of pressure (𝑝),
temperature (𝑇 ) and total component fractions (𝑧𝑐 ).
2) The phase densities (𝜌𝑝 ) and phase viscosities (𝜇𝑝 ) are computed as a function of pressure, temperature and the
updated phase component fractions.
After calculating the phase fractions, phase component fractions, phase densities, phase viscosities, and their derivatives
with respect to pressure, temperature, and component fractions, the Compositional Multiphase Flow Solver then moves
on to assembling the accumulation and flux terms.

Step 1: Computation of the phase fractions and phase component fractions (flash)

Stability test

The first step is to determine if the provided mixture with total molar fractions 𝑧𝑐 is stable as a single phase at the
current pressure 𝑝 and temperature 𝑇 . However, this can only be confirmed through stability testing.

458 Chapter 1. Table of Contents

GEOS Documentation

The stability of a mixture is traditionally assessed using the Tangent Plane Distance (TPD) criterion developed by
Michelsen (1982a). This criterion states that a phase with composition 𝑧 is stable at a specified pressure 𝑝 and temper-
ature 𝑇 if and only if
𝑁𝑐
∑︁
𝑔(𝑦) = 𝑦𝑖 (ln 𝑦𝑖 + ln 𝜑𝑖 (𝑦) − ln 𝑧𝑖 − ln 𝜑𝑖 (𝑧)) ≥ 0
𝑖=1

for any permissible trial composition 𝑦, where 𝜑𝑖 denotes the fugacity coefficient of component 𝑖.
To determine stability of the mixture this testing in initiated from a basic starting point, based on Wilson K-values, to
get both a lighter and a heavier trial mixture. The two trial mixtures are calculated as 𝑦𝑖 = 𝑧𝑖 /𝐾𝑖 and 𝑦𝑖 = 𝑧𝑖 𝐾𝑖 where
𝐾𝑖 are defined by
(︂ (︂ )︂)︂
𝑃𝑐𝑖 𝑇𝑐𝑖
𝐾𝑖 = exp 5.37(1 + 𝜔𝑖 ) 1 −
𝑝 𝑇
where 𝑃𝑐𝑖 and 𝑇𝑐𝑖 are respectively, the critical pressure and temperature of component 𝑖 and 𝜔𝑖 is the accentric factor
of component 𝑖.
The stability problem is solved by observing that a necessary condition is that 𝑔(𝑦) must be non-negative at all its
stationary points. The stationarity criterion can be expressed as
ln 𝑦𝑖 + ln 𝜑𝑖 (𝑦) − ℎ𝑖 = 𝑘 𝑖 = 1, 2, 3, . . . , 𝑁𝑐
where ℎ𝑖 = ln 𝑧𝑖 + ln 𝜑𝑖 (𝑧) is a constant parameter dependent on the feed composition 𝑧 and 𝑘 is an undetermined
constant. This constant can be further incorporated into the equation by defining the unnormalized trial phase moles
𝑌𝑖 as
𝑌𝑖 = exp(−𝑘)𝑦𝑖
which reduces the stationarity criterion to
ln 𝑌𝑖 + ln 𝜑𝑖 (𝑦) − ℎ𝑖 = 0
with the mole fractions 𝑦𝑖 related to the trial phase moles 𝑌𝑖 by
∑︁
𝑦𝑖 = 𝑌𝑖 / 𝑌𝑗
𝑗

With the two starting mixtures, the stationarity condition is solved using successive substitution to determine the sta-
tionary points. If both initial states converge to a solution which has 𝑔(𝑦) ≥ 0 then the mixture is deemed to be stable,
otherwise it is deemed unstable.

Phase labeling

Once it is confirmed that the fluid with composition 𝑧 is stable as a single phase at the current pressure and temperature, it
must be labeled as either ‘liquid’ or ‘vapor’. This is necessary only to apply the correct relative permeability function for
calculating the phase’s flow properties. The properties of the fluid (density, viscosity) are unchanged by the assignment
of the label.
Determining the mixture’s true critical point is the most rigorous method for labeling. It is however expensive and may
not always be necessary. As such, a simple correlation for pseudo-critical temperature is used and this is expected to
be sufficiently accurate for correct phase labeling, except under some specific conditions.
The Li-correlation is a weighted average of the component critical temperatures and is used to determine the label
applied to the mixture. The Li pseudo-critical temperature is calcaulated as
∑︀𝑁𝑐
𝑖=1 𝑇𝑐𝑖 𝑉𝑐𝑖 𝑧𝑖
𝑇𝑐𝑝 = ∑︀ 𝑁𝑐
𝑖=1 𝑉𝑐𝑖 𝑧𝑖
where 𝑉𝑐𝑖 and 𝑇𝑐𝑖 are respectively the critical volume and temperature of component 𝑖. This is compared to the current
temperature 𝑇 such that if 𝑇𝑐𝑝 < 𝑇 then the mixture is labeled as vapor and as liquid otherwise.

1.5. User Guide 459

GEOS Documentation

Negative two-phase flash

When a cell is identified as having an unstable mixture, it is necessary to determine the amounts in the liquid and vapor
phases through phase splitting. This phase split is calculated by ensuring that the two phases are in thermodynamic
equilibrium. For a system to be in thermodynamic equilibrium, the fugacities of each component in both the liquid and
vapor phases must be equal:

𝜑𝑖𝐿 = 𝜑𝑖𝑉 𝑖 = 1, 2, 3, . . . , 𝑁𝑐

where 𝜑𝑖𝐿 is the fugacity of component 𝑖 in the liquid phase and 𝜑𝑖𝐿 is the fugacity of component 𝑖 in the vapor phase.
Fugacities are functions of temperature, pressure, and composition:

𝜑𝑖𝐿 = 𝜑𝑖𝐿 (𝑇, 𝑝, 𝑥𝑖 ) 𝑖 = 1, 2, 3, . . . , 𝑁𝑐

and

𝜑𝑖𝑉 = 𝜑𝑖𝑉 (𝑇, 𝑝, 𝑦𝑖 ) 𝑖 = 1, 2, 3, . . . , 𝑁𝑐

and are calculated directly from an equation of state.

Equilibrium constants, also known as K-values, are defined for each component as:
𝑦𝑖
𝐾𝑖 =
𝑥𝑖
where 𝑥𝑖 is the mole fraction of component 𝑖 in the liquid phase and 𝑦𝑖 is the mole fraction of component 𝑖 in the vapor
phase. If we denote 𝑉 as the mole fraction of the vapor phase, the material balance indicates that the mole fractions of
each component in the liquid and vapor phases are given by:
𝑧𝑖
𝑥𝑖 =
1 + (𝐾𝑖 − 1)𝑉
and
𝐾 𝑖 𝑧𝑖
𝑦𝑖 =
1 + (𝐾𝑖 − 1)𝑉
The value of 𝑉 corresponding to a given set of K-values is determined by solving the so called Rachford and-Rice
equation:
𝑁𝑐 𝑁𝑐
∑︁ ∑︁ 𝑧𝑖 (1 − 𝐾𝑖 )
𝐹 (𝑉 ) = (𝑥𝑖 − 𝑦𝑖 ) = =0
𝑖=1 𝑖=1
1 + (𝐾𝑖 − 1)𝑉

The flash calculation process is as follows:

1. Once the mixture is confirmed to be stable, an initial set of K-values is chosen, typically using Wilson’s formula.
2. Given 𝑧𝑖 and 𝐾𝑖 , the Rachford-Rice equation is solved to determine the molar fraction of vapor, 𝑉 . This is initially
solved using successive substitution, followed by Newton iterations once the residual is sufficiently reduced.
3. After 𝑉 is calculated, the corresponding liquid and vapor mole fractions, 𝑥𝑖 and 𝑦𝑖 , are computed.
4. These phase compositions are then used to calculate the component fugacities 𝜑𝑖𝐿 and 𝜑𝑖𝑉 in the liquid and
vapor phases using the equation of state.
5. Convergence is reached when the fugacities are equal for all components. The convergence criterion is defined
as:
𝑁𝑐
∑︁ 2
(𝜑𝑖𝐿 − 𝜑𝑖𝑉 ) < 𝜀
𝑖=1

where 𝜀 is the convergence tolerance.

460 Chapter 1. Table of Contents

GEOS Documentation

6. If convergence is not achieved, successive substitution is used to update the set of K-values for the next iteration.
The new K-values at iteration 𝑡 + 1 are given by:

(𝑡+1) (𝑡) 𝜑𝑖𝐿

𝐾𝑖 = 𝐾𝑖
𝜑𝑖𝑉

Parameters

The model represented by <CompositionalMultiphaseFluid> node in the input. Under the hood this is a wrapper
around PVTPackage library, which is included as a submodule. In order to use the model, GEOS must be built with
-DENABLE_PVTPACKAGE=ON (default).
The following attributes are supported:

XML Element: CompositionalMultiphaseFluid

Name Type De- Description

fault
checkPVTTa- integer 1 Enable (1) or disable (0) an error when the input pressure or tem-
blesRanges perature of the PVT tables is out of range.
componentAcen- real64_array re- Component acentric factors
tricFactor quired
componentBina- real64_array2d {{0}} Table of binary interaction coefficients
ryCoeff
componentCritical- real64_array re- Component critical pressures
Pressure quired
componentCritical- real64_array re- Component critical temperatures
Temperature quired
componentMolar- real64_array re- Component molar weights
Weight quired
componentNames string_array re- List of component names
quired
componentVol- real64_array {0} Component volume shifts
umeShift
constantPhaseVis- real64_array {0} Viscosity for each phase
cosity
equationsOfState string_array re- List of equation of state types for each phase
quired
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- re- List of fluid phases
NameRef_array quired

Supported phase names are:

Value Comment
oil Oil phase
gas Gas phase
water Water phase

Supported Equation of State types:

1.5. User Guide 461

GEOS Documentation

Value Comment
PR Peng-Robinson EOS
SRK Soave-Redlich-Kwong EOS

Example

<Constitutive>
<CompositionalMultiphaseFluid name="fluid1"
phaseNames="{ oil, gas }"
equationsOfState="{ PR, PR }"
componentNames="{ N2, C10, C20, H2O }"
componentCriticalPressure="{ 34e5, 25.3e5, 14.6e5, 220.
˓→5e5 }"

componentCriticalTemperature="{ 126.2, 622.0, 782.0, 647.

˓→0 }"

componentAcentricFactor="{ 0.04, 0.443, 0.816, 0.344 }"

componentMolarWeight="{ 28e-3, 134e-3, 275e-3, 18e-3 }"
componentVolumeShift="{ 0, 0, 0, 0 }"
componentBinaryCoeff="{ { 0, 0, 0, 0 },
{ 0, 0, 0, 0 },
{ 0, 0, 0, 0 },
{ 0, 0, 0, 0 } }"/>
</Constitutive>

References

• M. L. Michelsen, The Isothermal Flash Problem. Part I. Stability., Fluid Phase Equilibria, vol. 9.1, pp. 1-19,
1982a.
• M. L. Michelsen, The Isothermal Flash Problem. Part II. Phase-Split Calculation., Fluid Phase Equilibria, vol.
9.1, pp. 21-40, 1982b.

CO2-brine model

Summary

The CO2-brine model implemented in GEOS includes two components (CO2 and H2O) that are transported by one or
two fluid phases (the brine phase and the CO2 phase). We refer to the brine phase with the subscript ℓ and to the CO2
phase with the subscript 𝑔 (although the CO2 phase can be in supercritical, liquid, or gas state). The water component is
only present in the brine phase, while the CO2 component can be present in the CO2 phase as well as in the brine phase.
Thus, considering the molar phase component fractions, 𝑦𝑐,𝑝 (i.e., the fraction of the molar mass of phase 𝑝 represented
by component 𝑐) the following partition matrix determines the component distribution within the two phases:
[︂ ]︂
𝑦𝐻2𝑂,ℓ 𝑦𝐶𝑂2,ℓ
0 1

The update of the fluid properties is done in two steps:

1) The phase fractions (𝜈𝑝 ) and phase component fractions (𝑦𝑐,𝑝 ) are computed as a function of pressure (𝑝), tem-
perature (𝑇 ), component fractions (𝑧𝑐 ), and a constant salinity.
2) The phase densities (𝜌𝑝 ) and phase viscosities (𝜇𝑝 ) are computed as a function of pressure, temperature, the
updated phase component fractions, and a constant salinity.

462 Chapter 1. Table of Contents

GEOS Documentation

Once the phase fractions, phase component fractions, phase densities, phase viscosities–and their derivatives with
respect to pressure, temperature, and component fractions–have been computed, the Compositional Multiphase Flow
Solver proceeds to the assembly of the accumulation and flux terms. Note that the current implementation of the flow
solver is isothermal and that the derivatives with respect to temperature are therefore discarded.
The models that are used in steps 1) and 2) are reviewed in more details below.

Step 1: Computation of the phase fractions and phase component fractions (flash)

At initialization, GEOS performs a preprocessing step to construct a two-dimensional table storing the values of CO2
solubility in brine as a function of pressure, temperature, and a constant salinity. The user can parameterize the con-
struction of the table by specifying the salinity and by defining the pressure (𝑝) and temperature (𝑇 ) axis of the table
in the form:

FlashModel CO2Solubility 𝑝𝑚𝑖𝑛 𝑝𝑚𝑎𝑥 ∆𝑝 𝑇𝑚𝑖𝑛 𝑇𝑚𝑎𝑥 ∆𝑇 Salinity

Note that the pressures are in Pascal, temperatures are in Kelvin, and the salinity is a molality (moles of NaCl per kg of
brine). The temperature must be between 283.15 and 623.15 Kelvin. The table is populated using the model of Duan
and Sun (2003). Specifically, we solve the following nonlinear CO2 equation of state (equation (A1) in Duan and Sun,
2003) for each pair (𝑝, 𝑇 ) to obtain the reduced volume, 𝑉𝑟 .

𝑝𝑟 𝑉𝑟 𝑎1 + 𝑎2 /𝑇𝑟2 + 𝑎3 /𝑇𝑟3 𝑎4 + 𝑎5 /𝑇𝑟2 + 𝑎6 /𝑇𝑟3 𝑎7 + 𝑎8 /𝑇𝑟2 + 𝑎9 /𝑇𝑟3

=1+ + 2
+
𝑇𝑟 𝑉𝑟 𝑉𝑟 𝑉𝑟4
𝑎10 + 𝑎11 /𝑇𝑟2 + 𝑎12 /𝑇𝑟3 𝑎13 (︀ 𝑎15 )︀ 𝑎15
+ 5
+ 3 2 𝑎14 + 2 exp(− 2 )
𝑉𝑟 𝑇𝑟 𝑉𝑟 𝑉𝑟 𝑉𝑟

where 𝑝𝑟 = 𝑝/𝑝𝑐𝑟𝑖𝑡 and 𝑇𝑟 = 𝑇 /𝑇𝑐𝑟𝑖𝑡 are respectively the reduced pressure and the reduced temperature. We refer the
reader to Table (A1) in Duan and Sun (2003) for the definition of the coefficients 𝑎𝑖 involved in the previous equation.
Using the reduced volume, 𝑉𝑟 , we compute the fugacity coefficient of CO2, ln𝜑 (𝑝, 𝑇 ), using equation (A6) of Duan
and Sun (2003). To conclude this preprocessing step, we use the fugacity coefficient of CO2 to compute and store the
solubility of CO2 in brine, 𝑠𝐶𝑂2 , using equation (6) of Duan and Sun (2003):

𝑦𝐶𝑂2 𝑃 Φ𝐶𝑂2 ∑︁ ∑︁ ∑︁
ln = − ln𝜑 (𝑝, 𝑇 ) + 2𝜆𝑐 𝑚 + 2𝜆𝑎 𝑚 + 𝜁𝑎,𝑐 𝑚2
𝑠𝐶𝑂2 𝑅𝑇 𝑐 𝑎 𝑎,𝑐

where Φ𝐶𝑂2 is the chemical potential of the CO2 component, 𝑅 is the gas constant, and 𝑚 is the salinity. The mole
fraction of CO2 in the vapor phase, 𝑦𝐶𝑂2 , is computed with equation (4) of Duan and Sun (2003). Note that the first,
third, fourth, and fifth terms in the equation written above are approximated using equation (7) of Duan and Sun (2003)
as recommended by the authors.
During the simulation, Step 1 starts with a look-up in the precomputed table to get the CO2 solubility, 𝑠𝐶𝑂2 , as a
function of pressure and temperature. Then, we compute the phase fractions as:
1 + 𝑠𝐶𝑂2
𝜈ℓ =
1 + 𝑧𝐶𝑂2 /(1 − 𝑧𝐶𝑂2 )
𝜈𝑔 = 1 − 𝜈ℓ

We conclude Step 1 by computing the phase component fractions as:

𝑠𝐶𝑂2
𝑦𝐶𝑂2,ℓ =
1 + 𝑠𝐶𝑂2
𝑦𝐻2𝑂,ℓ = 1 − 𝑦𝐶𝑂2,ℓ
𝑦𝐶𝑂2,𝑔 = 1
𝑦𝐻2𝑂,𝑔 = 0

1.5. User Guide 463

GEOS Documentation

Step 2: Computation of the phase densities and phase viscosities

CO2 phase density and viscosity

In GEOS, the computation of the CO2 phase density and viscosity is entirely based on look-up in precomputed tables.
The user defines the pressure (in Pascal) and temperature (in Kelvin) axis of the density table in the form:

DensityFun SpanWagnerCO2Density 𝑝𝑚𝑖𝑛 𝑝𝑚𝑎𝑥 ∆𝑝 𝑇𝑚𝑖𝑛 𝑇𝑚𝑎𝑥 ∆𝑇

This correlation is valid for pressures less than 8 × 108 Pascal and temperatures less than 1073.15 Kelvin. Using these
parameters, GEOS internally constructs a two-dimensional table storing the values of density as a function of pressure
and temperature. This table is populated as explained in the work of Span and Wagner (1996) by solving the following
nonlinear Helmholtz energy equation for each pair (𝑝, 𝑇 ) to obtain the value of density, 𝜌𝑔 :
𝑝
= 1 + 𝛿𝜑𝑟𝛿 (𝛿, 𝜏 )
𝑅𝑇 𝜌𝑔
where 𝑅 is the gas constant, 𝛿 := 𝜌𝑔 /𝜌𝑐𝑟𝑖𝑡 is the reduced CO2 phase density, and 𝜏 := 𝑇𝑐𝑟𝑖𝑡 /𝑇 is the inverse of the
reduced temperature. The definition of the residual part of the energy equation, denoted by 𝜑𝑟𝛿 , can be found in equation
(6.5), page 1544 of Span and Wagner (1996). The coefficients involved in the computation of 𝜑𝑟𝛿 are listed in Table
(31), page 1544 of Span and Wagner (1996). These calculations are done in a preprocessing step.
The pressure and temperature axis of the viscosity table can be parameterized in a similar fashion using the format:

ViscosityFun FenghourCO2Viscosity 𝑝𝑚𝑖𝑛 𝑝𝑚𝑎𝑥 ∆𝑝 𝑇𝑚𝑖𝑛 𝑇𝑚𝑎𝑥 ∆𝑇

This correlation is valid for pressures less than 3 × 108 Pascal and temperatures less than 1493.15 Kelvin. This table
is populated as explained in the work of Fenghour and Wakeham (1998) by computing the CO2 phase viscosity, 𝜇𝑔 , as
follows:

𝜇𝑔 = 𝜇0 (𝑇 ) + 𝜇𝑒𝑥𝑐𝑒𝑠𝑠 (𝜌𝑔 , 𝑇 ) + 𝜇𝑐𝑟𝑖𝑡 (𝜌𝑔 , 𝑇 )

The “zero-density limit” viscosity, 𝜇0 (𝑇 ), is computed as a function of temperature using equations (3), (4), and (5),
as well as Table (1) of Fenghour and Wakeham (1998). The excess viscosity, 𝜇𝑒𝑥𝑐𝑒𝑠𝑠 (𝜌𝑔 , 𝑇 ), is computed as a function
of temperature and CO2 phase density (computed as explained above) using equation (8) and Table (3) of Fenghour
and Wakeham (1998). We currently neglect the critical viscosity, 𝜇𝑐𝑟𝑖𝑡 . These calculations are done in a preprocessing
step.
During the simulation, the update of CO2 phase density and viscosity is simply done with a look-up in the precomputed
tables.

Brine density and viscosity using Phillips correlation

The computation of the brine density involves a tabulated correlation presented in Phillips et al. (1981). The user
specifies the (constant) salinity and defines the pressure and temperature axis of the brine density table in the form:

DensityFun PhillipsBrineDensity 𝑝𝑚𝑖𝑛 𝑝𝑚𝑎𝑥 ∆𝑝 𝑇𝑚𝑖𝑛 𝑇𝑚𝑎𝑥 ∆𝑇 Salinity

The pressure must be in Pascal and must be less than 5 × 107 Pascal. The temperature must be in Kelvin and must be
between 283.15 and 623.15 Kelvin. The salinity is a molality (moles of NaCl per kg of brine). Using these parameters,
GEOS performs a preprocessing step to construct a two-dimensional table storing the brine density, 𝜌ℓ,𝑡𝑎𝑏𝑙𝑒 for the
specified salinity as a function of pressure and temperature using the expression:
𝜌ℓ,𝑡𝑎𝑏𝑙𝑒 = 𝐴 + 𝐵𝑥 + 𝐶𝑥2 + 𝐷𝑥3
𝑥 = 𝑐1 exp(𝑎1 𝑚) + 𝑐2 exp(𝑎2 𝑇 ) + 𝑐3 exp(𝑎3 𝑃 )

464 Chapter 1. Table of Contents

GEOS Documentation

We refer the reader to Phillips et al. (1981), equations (4) and (5), pages 14 and 15 for the definition of the coefficients
involved in the previous equation. This concludes the preprocessing step.
Then, during the simulation, the brine density update proceeds in two steps. First, a table look-up is performed to
retrieve the value of density, 𝜌ℓ,𝑡𝑎𝑏𝑙𝑒 . Then, in a second step, the density is modified using the method of Garcia (2001)
to account for the presence of CO2 dissolved in brine as follows:

𝜌ℓ = 𝜌ℓ,𝑡𝑎𝑏𝑙𝑒 + 𝑀𝐶𝑂2 𝑐𝐶𝑂2 − 𝑐𝐶𝑂2 𝜌ℓ,𝑡𝑎𝑏𝑙𝑒 𝑉𝜑

where 𝑀𝐶𝑂2 is the molecular weight of CO2, 𝑐𝐶𝑂2 is the concentration of CO2 in brine, and 𝑉𝜑 is the apparent molar
volume of dissolved CO2. The CO2 concentration in brine is obtained as:
𝑦𝐶𝑂2,ℓ 𝜌ℓ,𝑡𝑎𝑏𝑙𝑒
𝑐𝐶𝑂2 =
𝑀𝐻2𝑂 (1 − 𝑦𝐶𝑂2,ℓ )
where 𝑀𝐻2𝑂 is the molecular weight of water. The apparent molar volume of dissolved CO2 is computed as a function
of temperature using the expression:

𝑉𝜑 = 37.51 − 9.585 × 10−2 𝑇 + 8.740 × 10−4 𝑇 2 − 5.044 × 10−7 𝑇 3

The brine viscosity is controlled by a salinity parameter provided by the user in the form:

ViscosityFun PhillipsBrineViscosity Salinity

During the simulation, the brine viscosity is updated as a function of temperature using the analytical relationship of
Phillips et al. (1981):

𝜇ℓ = 𝑎𝑇 + 𝑏

where the coefficients 𝑎 and 𝑏 are defined as:

𝑎 = 𝜇𝑤 (𝑇 ) × 0.000629(1.0 − exp(−0.7𝑚))
𝑏 = 𝜇𝑤 (𝑇 )(1.0 + 0.0816𝑚 + 0.0122𝑚2 + 0.000128𝑚3 )
where 𝜇𝑤 is the pure water viscosity computed as a function of temperature, and 𝑚 is the user-defined salinity (in
moles of NaCl per kg of brine).

Brine density and viscosity using Ezrokhi correlation

Brine density 𝜌𝑙 is computed from pure water density 𝜌𝑤 at specified pressure and temperature corrected by Ezrokhi
correlation presented in Zaytsev and Aseyev (1993):
𝑙𝑜𝑔10 (𝜌𝑙 ) = 𝑙𝑜𝑔10 (𝜌𝑤 (𝑃, 𝑇 )) + 𝐴(𝑇 )𝑥𝐶𝑂2,ℓ
𝐴(𝑇 ) = 𝑎0 + 𝑎1 𝑇 + 𝑎2 𝑇 2 ,
where 𝑎0 , 𝑎1 , 𝑎2 are correlation coefficients defined by user:

DensityFun EzrokhiBrineDensity 𝑎0 𝑎1 𝑎2

While 𝑥𝐶𝑂2,ℓ is mass fraction of CO2 component in brine, computed from molar fractions as
𝑀𝐶𝑂2 𝑦𝐶𝑂2,ℓ
𝑥𝐶𝑂2,ℓ = ,
𝑀𝐶𝑂2 𝑦𝐶𝑂2,ℓ + 𝑀𝐻2𝑂 𝑦𝐻2𝑂,ℓ
Pure water density is computed according to:

𝜌𝑤 = 𝜌𝑤,𝑠𝑎𝑡 (𝑇 )𝑒𝑐𝑤 *(𝑃 −𝑃𝑤,𝑠𝑎𝑡 (𝑇 )) ,

1.5. User Guide 465

GEOS Documentation

where 𝑐𝑤 is water compressibility defined as a constant 4.5 × 10−10 𝑃 𝑎−1 , while 𝜌𝑤,𝑠𝑎𝑡 (𝑇 ) and 𝑃𝑤,𝑠𝑎𝑡 (𝑇 ) are density
and pressure of saturated water at a given temperature. Both are obtained through internally constructed tables tabulated
as functions of temperature and filled with the steam table data from Engineering ToolBox (2003, 2004).
Brine viscosity 𝜇ℓ is computed from pure water viscosity 𝜇𝑤 similarly:

𝑙𝑜𝑔10 (𝜇𝑙 ) = 𝑙𝑜𝑔10 (𝜇𝑤 (𝑃, 𝑇 )) + 𝐵(𝑇 )𝑥𝐶𝑂2,ℓ

𝐵(𝑇 ) = 𝑏0 + 𝑏1 𝑇 + 𝑏2 𝑇 2 ,

where 𝑏0 , 𝑏1 , 𝑏2 are correlation coefficients defined by user:

ViscosityFun EzrokhiBrineViscosity 𝑏0 𝑏1 𝑏2

Mass fraction of CO2 component in brine 𝑥𝐶𝑂2,ℓ is exactly as in density calculation. The dependency of pure water
viscosity from pressure is ignored, and it is approximated as saturated pure water viscosity:

𝜇𝑤 (𝑃, 𝑇 ) = 𝜇𝑤,𝑠𝑎𝑡 (𝑇 ),

which is tabulated using internal table as a function of temperature based on steam table data Engineering ToolBox
(2004).

Parameters

The models are represented by <CO2BrinePhillipsFluid>, <CO2BrineEzrokhiFluid> nodes in the input.

The following attributes are supported:

XML Element: CO2BrinePhillipsFluid

Name Type De- Description

fault
checkPVTTa- integer 1 Enable (1) or disable (0) an error when the input pressure or tempera-
blesRanges ture of the PVT tables is out of range.
componentMo- real64_array {0} Component molar weights
larWeight
component- string_array {} List of component names
Names
flashModel- path Name of the file defining the parameters of the flash model
ParaFile
logLevel integer 0 Log level
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- {} List of fluid phases
NameRef_array
phasePVT- path_array re- Names of the files defining the parameters of the viscosity and density
ParaFiles quired models
solubilityTable- string_array {} Names of solubility tables for each phase
Names
writeCSV integer 0 Write PVT tables into a CSV file

Supported phase names are:

466 Chapter 1. Table of Contents

GEOS Documentation

Value Comment
gas CO2 phase
water Water phase

Supported component names are:

Value Component
co2,CO2 CO2 component
water,liquid Water component

Example

In the XML code listed above, “co2flash.txt” parameterizes the CO2 solubility table constructed in Step 1. The file
“pvtgas.txt” parameterizes the CO2 phase density and viscosity tables constructed in Step 2, the file “pvtliquid.txt”
parameterizes the brine density and viscosity tables according to Phillips or Ezrokhi correlation, depending on chosen
fluid model.

References

• Z. Duan and R. Sun, An improved model calculating CO2 solubility in pure water and aqueous NaCl solutions
from 273 to 533 K and from 0 to 2000 bar., Chemical Geology, vol. 193.3-4, pp. 257-271, 2003.
• R. Span and W. Wagner, A new equation of state for carbon dioxide covering the fluid region from the triple-point
temperature to 1100 K at pressure up to 800 MPa, J. Phys. Chem. Ref. Data, vol. 25, pp. 1509-1596, 1996.
• A. Fenghour and W. A. Wakeham, The viscosity of carbon dioxide, J. Phys. Chem. Ref. Data, vol. 27, pp.
31-44, 1998.
• S. L. Phillips et al., A technical databook for geothermal energy utilization, Lawrence Berkeley Laboratory report,
1981.

1.5. User Guide 467

GEOS Documentation

• J. E. Garcia, Density of aqueous solutions of CO2. No. LBNL-49023. Lawrence Berkeley National Laboratory,
Berkeley, CA, 2001.
• Zaytsev, I.D. and Aseyev, G.G. Properties of Aqueous Solutions of Electrolytes, Boca Raton, Florida, USA CRC
Press, 1993.
• Engineering ToolBox, Water - Density, Specific Weight and Thermal Expansion Coefficients, 2003
• Engineering ToolBox, Water - Dynamic (Absolute) and Kinematic Viscosity, 2004

Relative Permeability Models

There are two ways to specify relative permeabilities in GEOS. The user can either select an analytical relative perme-
ability model (e.g., Brooks-Corey or Van Genuchten) or provide relative permeability tables. This is explained in the
following sections.

Brooks-Corey relative permeability model

Overview

The following paragraphs explain how the Brooks-Corey model is used to compute the phase relative permeabilities as
a function of volume fraction (i.e., saturation) with the expression:
𝜆ℓ
𝑘𝑟ℓ = 𝑘rℓ,max 𝑆ℓ,scaled ,

where the scaled volume fraction of phase ℓ is computed as:

𝑆ℓ − 𝑆ℓ,min
𝑆ℓ,scaled = ∑︀𝑛𝑝 .
1 − 𝑚=1 𝑆m,min
The minimum phase volume fractions 𝑆ℓ,min are model parameters specified by the user.

Parameters

The relative permeability constitutive model is listed in the <Constitutive> block of the input XML file. The relative
permeability model must be assigned a unique name via name attribute. This name is used to assign the model to regions
of the physical domain via a materialList attribute of the <ElementRegions> node.
The following attributes are supported:

XML Element: BrooksCoreyRelativePermeability

Name Type De- Description

fault
name groupName re- A name is required for any non-unique nodes
quired
phaseMinVolume- real64_array {0} Minimum volume fraction value for each phase
Fraction
phaseNames group- re- List of fluid phases
NameRef_array quired
phaseRelPermExpo- real64_array {1} Minimum relative permeability power law exponent for
nent each phase
phaseRelPermMax- real64_array {0} Maximum relative permeability value for each phase
Value

Below are some comments on the model parameters.

468 Chapter 1. Table of Contents

GEOS Documentation

• phaseNames - The number of phases can be either two or three. Note that for three-phase flow, this model does
not apply a special treatment to the intermediate phase relative permeability (no Stone or Baker interpolation).
Supported phase names are:

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• phaseMinVolFraction - The list of minimum volume fractions 𝑆ℓ,𝑚𝑖𝑛 for each phase is specified in the same
order as in phaseNames. Below this volume fraction, the phase is assumed to be immobile.
• phaseRelPermExponent - The list of exponents 𝜆ℓ for each phase is specified in the same order as in
phaseNames.
• phaseMaxValue - The list of maximum values 𝑘rℓ,max for each phase is specified in the same order as in
phaseNames.

Examples

For a two-phase water-gas system (for instance in the CO2-brine fluid model), a typical relative permeability input
looks like:

For a three-phase oil-water-gas system (for instance in the Black-Oil fluid model), a typical relative permeability input
looks like:

Three-phase relative permeability model

Overview

For the simulation of three-phase flow in porous media, it is common to use a specific treatment (i.e., different from
the typical two-phase procedure) to evaluate the oil relative permeability. Specifically, the three-phase oil relative

1.5. User Guide 469

GEOS Documentation

permeability is obtained by interpolation of oil-water and oil-gas experimental data measured independently in two-
phase displacements.
Let 𝑘𝑟𝑤,𝑤𝑜 and 𝑘𝑟𝑜,𝑤𝑜 be the water-oil two-phase relative permeabilities for the water phase and the oil phase, re-
spectively. Let 𝑘𝑟𝑔,𝑔𝑜 and 𝑘𝑟𝑜,𝑔𝑜 be the oil-gas two-phase relative permeabilities for the gas phase and the oil phase,
respectively. In the current implementation, the two-phase relative permeability data is computed analytically using
the Brooks-Corey relative permeability model.
The water and gas three-phase relative permeabilities are simply given by two-phase data and only depend on 𝑆𝑤 and
𝑆𝑔 , respectively. That is,

𝑘𝑟𝑤,𝑤𝑜𝑔 (𝑆𝑤 ) = 𝑘𝑟𝑤,𝑤𝑜 (𝑆𝑤 ),

𝑘𝑟𝑔,𝑤𝑜𝑔 (𝑆𝑔 ) = 𝑘𝑟𝑔,𝑔𝑜 (𝑆𝑔 ).

The oil three-phase relative permeability is obtained using a variant of the saturation-weighted interpolation procedure
initially proposed by Baker. Specifically, we compute:

(𝑆𝑤 − 𝑆𝑤,min )𝑘𝑟𝑜,𝑤𝑜 (𝑆𝑤 ) + 𝑆𝑔 𝑘𝑟𝑔,𝑔𝑜 (𝑆𝑔 )

𝑘𝑟𝑜,𝑤𝑜𝑔 (𝑆𝑤 , 𝑆𝑔 ) = .
(𝑆𝑤 − 𝑆𝑤,min ) + 𝑆𝑔

This procedure provides a simple but effective formula avoiding the problems associated with the other interpolation
methods (negative values).
Another option can be triggered using threePhaseInterpolator to set interpolation model to be STONEII described by:

𝑘𝑟 𝑜 = 𝑘𝑟 𝑜𝑐𝑤((𝑘𝑟 𝑜𝑤/𝑘𝑟 𝑜𝑐𝑤 + 𝑘𝑟 𝑤)(𝑘𝑟 𝑜𝑔/𝑘𝑟 𝑜𝑐𝑤 + 𝑘𝑟 𝑔) − 𝑘𝑟 𝑤 − 𝑘𝑟 𝑔)

...

Parameters

470 Chapter 1. Table of Contents

GEOS Documentation

XML Element: BrooksCoreyBakerRelativePermeability

Name Type Default Description

gasOilRelPermExponent real64_array {1}
Rel perm power law
exponent for the pair (gas
phase, oil phase) at
residual water saturation
The expected format is “{
gasExp, oilExp }”, in that
order

gasOilRelPermMaxValue real64_array {0}

Maximum rel perm value
for the pair (gas phase, oil
phase) at residual water
saturation
The expected format is “{
gasMax, oilMax }”, in
that order

name groupName required A name is required for any

non-unique nodes
phaseMinVolumeFraction real64_array {0} Minimum volume fraction
value for each phase
phaseNames groupNameRef_array required List of fluid phases
waterOilRelPermExpo- real64_array {1}
nent
Rel perm power law
exponent for the pair
(water phase, oil phase) at
residual gas saturation
The expected format is “{
waterExp, oilExp }”, in
that order

waterOilRelPermMax- real64_array {0}

Value
Maximum rel perm value
for the pair (water phase,
oil phase) at residual gas
saturation
The expected format is “{
waterMax, oilMax }”, in
that order

Below are some comments on the model parameters.

• phaseNames - The number of phases should be 3. Supported phase names are:

1.5. User Guide 471

GEOS Documentation

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• phaseMinVolFraction - The list of minimum volume fractions 𝑆ℓ,𝑚𝑖𝑛 for each phase is specified in the same
order as in phaseNames. Below this volume fraction, the phase is assumed to be immobile.
• waterOilRelPermExponent - The list of exponents 𝜆ℓ,𝑤𝑜 for the two-phase water-oil relative permeability
data, with the water exponent first and the oil exponent next. These exponents are then used to compute 𝑘𝑟ℓ,𝑤𝑜
in the Brooks-Corey relative permeability model.
• waterOilRelPermMaxValue - The list of maximum values 𝑘rℓ,𝑤𝑜,max for the two-phase water-oil relative per-
meability data, with the water max value first and the oil max value next. These exponents are then used to
compute 𝑘𝑟ℓ,𝑤𝑜 in the Brooks-Corey relative permeability model.
• gasOilRelPermExponent - The list of exponents 𝜆ℓ,𝑔𝑜 for the two-phase gas-oil relative permeability data,
with the gas exponent first and the oil exponent next. These exponents are then used to compute 𝑘𝑟ℓ,𝑔𝑜 in the
Brooks-Corey relative permeability model.
• gasOilRelPermMaxValue - The list of maximum values 𝑘rℓ,𝑔𝑜,max for the two-phase gas-oil relative permeabil-
ity data, with the gas max value first and the oil max value next. These exponents are then used to compute 𝑘𝑟ℓ,𝑔𝑜
in the Brooks-Corey relative permeability model.

Example

Table relative permeability

Overview

The user can specify the relative permeabilities using tables describing a piecewise-linear relative permeability function
of volume fraction (i.e., saturation) for each phase. Depending on the number of fluid phases, this model is used as
follows:
• For two-phase flow, the user must specify two relative permeability tables, that is, one for the wetting-phase
relative permeability, and one for the non-wetting phase relative permeability. During the simulation, the relative
permeabilities are then obtained by interpolating in the tables as a function of phase volume fraction.
• For three-phase flow, following standard reservoir simulation practice, the user must specify four relative perme-
ability tables. Specifically, two relative permeability tables are required for the pair wetting-phase–intermediate
phase (typically, water-oil), and two relative permeability tables are required for the pair non-wetting-
phase–intermediate phase (typically, gas-oil). During the simulation, the relative permeabilities of the wetting
and non-wetting phases are computed by interpolating in the tables as a function of their own phase volume

472 Chapter 1. Table of Contents

GEOS Documentation

fraction. The intermediate phase relative permeability is obtained by interpolating the two-phase relative perme-
abilities using the Baker interpolation procedure.

Parameters

1.5. User Guide 473

GEOS Documentation

XML Element: TableRelativePermeability

Name Type Default Description

name groupName required A name is required for any
non-unique nodes
nonWettingIntermedi- groupNameRef_array {}
ateRelPermTableNames
List of relative
permeability tables for the
pair (non-wetting phase,
intermediate phase)
The expected format is “{
nonWetting-
PhaseRelPermTable-
Name,
intermedi-
atePhaseRelPermTable-
Name }”, in that order
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettin-
gRelPermTableNames to
specify the table names

phaseNames groupNameRef_array required List of fluid phases

threePhaseInterpolator geos_constitutive_ThreePhaseInterpolator
BAKER
Type of Three phase
interpolator.Valid options
* BAKER
* STONEII

wettingIntermedi- groupNameRef_array {}
ateRelPermTableNames
List of relative
permeability tables for the
pair (wetting phase,
intermediate phase)
The expected format is “{
wetting-
PhaseRelPermTable-
Name,
intermedi-
atePhaseRelPermTable-
Name }”, in that order
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettin-
gRelPermTableNames to
474 Chapter 1. Table
specify of names
the table Contents

wettingNonWettin- groupNameRef_array {}
gRelPermTableNames
GEOS Documentation

Below are some comments on the model parameters.

• phaseNames - The number of phases can be either two or three. For three-phase flow, this model applies a Baker
interpolation to the intermediate phase relative permeability. Supported phase names are:

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• wettingNonWettingRelPermTableNames - The list of relative permeability table names for two-phase

systems, starting with the name of the wetting-phase relative permeability table, followed by the name
of the non-wetting phase relative permeability table. Note that this keyword is only valid for two-
phase systems, and is not allowed for three-phase systems (for which the user must specify instead
wettingIntermediateRelPermTableNames and nonWettingIntermediateRelPermTableNames).
• wettingIntermediateRelPermTableNames - The list of relative permeability table names for the pair
wetting-phase–intermediate-phase, starting with the name of the wetting-phase relative permeability table, and
continuing with the name of the intermediate phase relative permeability table. Note that this keyword is only
valid for three-phase systems, and is not allowed for two-phase systems (for which the user must specify instead
wettingNonWettingRelPermTableNames).
• nonWettingIntermediateRelPermTableNames - The list of relative permeability table names for the pair
non-wetting-phase–intermediate-phase, starting with the name of the non-wetting-phase relative permeability
table, and continuing with the name of the intermediate phase relative permeability table. Note that this keyword
is only valid for three-phase systems, and is not allowed for two-phase systems (for which the user must specify
instead wettingNonWettingRelPermTableNames).

ò Note

We remind the user that the relative permeability must be a strictly increasing function of phase volume fraction.
GEOS throws an error when this condition is not satisfied.

Examples

For a two-phase water-gas system (for instance in the CO2-brine fluid model), a typical relative permeability input
looks like:

...
</Constitutive>

ò Note

The name of the wetting-phase relative permeability table must be specified before the name of the non-wetting
phase relative permeability table.

1.5. User Guide 475

GEOS Documentation

For a three-phase oil-water-gas system (for instance in the Black-Oil fluid model), a typical relative permeability input
looks like:

<Constitutive>
...
<TableRelativePermeability
name="relPerm"
phaseNames="{ water, oil, gas }"
wettingIntermediateRelPermTableNames="{ waterRelativePermeabilityTable,␣
˓→oilRelativePermeabilityTableForWO }"

nonWettingIntermediateRelPermTableNames="{ gasRelativePermeabilityTable,␣
˓→oilRelativePermeabilityTableForGO }"/>

...
</Constitutive>

ò Note

For the wetting-phase–intermediate-phase pair, the name of the wetting-phase relative permeability table must be
specified first. For the non-wetting-phase–intermediate-phase pair, the name of the non-wetting-phase relative
permeability table must be specified first. If the results look incoherent, this is something to double-check.

The tables mentioned above by name must be defined in the <Functions> block of the XML file using the
<TableFunction> keyword.

Capillary Pressure Models

There are two ways to specify capillary pressures in GEOS. The user can either select an analytical capillary pressure
model (e.g., Brooks-Corey or Van Genuchten) or provide capillary pressure tables. This is explained in the following
sections.

Brooks-Corey capillary pressure model

Overview

In GEOS, the oil-phase pressure is assumed to be the primary pressure. The following paragraphs explain how the
Brooks-Corey capillary pressure model is used to compute the water-phase and gas-phase pressures as:

𝑝𝑤 = 𝑝𝑜 − 𝑃𝑐,𝑤 (𝑆𝑤 ),

and

𝑝𝑔 = 𝑝𝑜 + 𝑃𝑐,𝑔 (𝑆𝑔 ).

In the Brooks-Corey model, the water-phase capillary pressure is computed as a function of the water-phase volume
fraction with the following expression:
−1/𝜆
𝑃𝑐,𝑤 (𝑆𝑤 ) = 𝑝𝑒,𝑤 𝑆w,scaled𝑤 ,

where the scaled water-phase volume fraction is computed as:

𝑆𝑤 − 𝑆w,min
𝑆w,scaled = .
1 − 𝑆w,min − 𝑆o,min − 𝑆g,min

The gas capillary pressure is computed analogously.

476 Chapter 1. Table of Contents

GEOS Documentation

Parameters

The capillary pressure constitutive model is listed in the <Constitutive> block of the input XML file. The capillary
pressure model must be assigned a unique name via name attribute. This name is used to assign the model to regions
of the physical domain via a materialList attribute of the <ElementRegions> node.
The following attributes are supported:

XML Element: BrooksCoreyCapillaryPressure

Name Type De- Description

fault
capPressureEp- real64 1e- Wetting-phase saturation at which the max cap. pressure is attained; used
silon 06 to avoid infinite cap. pressure values for saturations close to zero
name group- re- A name is required for any non-unique nodes
Name quired
phaseCap- real64_array {2} Inverse of capillary power law exponent for each phase
PressureExpo-
nentInv
phaseEntry- real64_array {1} Entry pressure value for each phase
Pressure
phaseMinVol- real64_array {0} Minimum volume fraction value for each phase
umeFraction
phaseNames group- re- List of fluid phases
NameRef_array
quired

Below are some comments on the model parameters:

• phaseNames - The number of phases can be either 2 or 3. The names entered for this attribute should match
the phase names specified in the relative permeability block, either in Brooks-Corey relative permeability model
or in Three-phase relative permeability model. The capillary pressure model assumes that oil is always present.
Supported phase names are:

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• phaseMinVolFraction - The list of minimum volume fractions 𝑆ℓ,𝑚𝑖𝑛 for each phase is specified in the same
order as in phaseNames. Below this volume fraction, the phase is assumed to be immobile. The values entered
for this attribute have to match those of the same attribute in the relative permeability block.
• phaseCapPressureExponentInv - The list of exponents 𝜆ℓ for each phase is specified in the same order as in
phaseNames. The parameter corresponding to the oil phase is currently not used.
• phaseEntryPressure - The list of entry pressures 𝑝𝑒,ℓ for each phase is specified in the same order as in
phaseNames. The parameter corresponding to the oil phase is currently not used.
• capPressureEpsilon - This parameter is used for both the water-phase and gas-phase capillary pressure. To
avoid extremely large, or infinite, capillary pressure values, we set 𝑃𝑐,𝑤 (𝑆𝑤 ) := 𝑃𝑐,𝑤 (𝜖) whenever 𝑆𝑤 < 𝜖. The
gas-phase capillary pressure is treated analogously.

1.5. User Guide 477

GEOS Documentation

Example

Van Genuchten capillary pressure model

Overview

In GEOS, the oil-phase pressure is assumed to be the primary pressure. The following paragraphs explain how the Van
Genuchten capillary pressure model is used to compute the water-phase and gas-phase pressures as:

𝑝𝑤 = 𝑝𝑜 − 𝑃𝑐,𝑤 (𝑆𝑤 ),

and

𝑝𝑔 = 𝑝𝑜 + 𝑃𝑐,𝑔 (𝑆𝑔 ),

The Van Genuchten model computes the water-phase capillary pressure as a function of the water-phase volume fraction
as:
−1/𝑚
𝑤
𝑃𝑐 (𝑆𝑤 ) = 𝛼𝑤 (𝑆𝑤,𝑠𝑐𝑎𝑙𝑒𝑑 − 1)(1−𝑚𝑤 )/2 ,

where the scaled water-phase volume fraction is computed as:

𝑆𝑤 − 𝑆w,min
𝑆w,scaled = .
1 − 𝑆w,min − 𝑆o,min − 𝑆g,min

The gas-phase capillary pressure is computed analogously.

Parameters

478 Chapter 1. Table of Contents

GEOS Documentation

XML Element: VanGenuchtenCapillaryPressure

Name Type De- Description

fault
capPressureEp- real64 1e- Saturation at which the extremum capillary pressure is attained; used to
silon 06 avoid infinite capillary pressure values for saturations close to 0 and 1
name group- re- A name is required for any non-unique nodes
Name quired
phaseCap- real64_array {0.5} Inverse of capillary power law exponent for each phase
PressureExpo-
nentInv
phaseCapPres- real64_array {1} Entry pressure value for each phase
sureMultiplier
phaseMinVol- real64_array {0} Minimum volume fraction value for each phase
umeFraction
phaseNames group- re- List of fluid phases
NameRef_array
quired

Below are some comments on the model parameters:

• phaseNames - The number of phases can be either 2 or 3. The phase names entered for this attribute should
match the phase names specified in the relative permeability block, either in Brooks-Corey relative permeability
model or in Three-phase relative permeability model. The capillary model assumes that oil is always present.
Supported phase names are:

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• phaseMinVolFraction - The list of minimum volume fractions 𝑆ℓ,𝑚𝑖𝑛 for each phase is specified in the same
order as in phaseNames. Below this volume fraction, the phase is assumed to be immobile. The values entered
for this attribute have to match those of the same attribute in the relative permeability block.
• phaseCapPressureExponentInv - The list of exponents 𝑚ℓ for each phase is specified in the same order as in
phaseNames. The parameter corresponding to the oil phase is not used.
• phaseCapPressureMultiplier - The list of multipliers 𝛼ℓ for each phase is specified in the same order as in
phaseNames. The parameter corresponding to the oil phase is not used.
• capPressureEpsilon - The parameter 𝜖. This parameter is used for both the water-phase and gas-phase cap-
illary pressure. To avoid extremely large, or infinite, capillary pressure values, we set 𝑃𝑐,𝑤 (𝑆𝑤 ) := 𝑃𝑐,𝑤 (𝜖)
whenever 𝑆𝑤 < 𝜖. The gas-phase capillary pressure is treated analogously.

Example

<Constitutive>
...
<VanGenuchtenCapillaryPressure name="capPressure"
phaseNames="{ water, oil }"
phaseMinVolumeFraction="{ 0.1, 0.015 }"
phaseCapPressureExponentInv="{ 0.55, 0 }"
(continues on next page)

1.5. User Guide 479

GEOS Documentation

(continued from previous page)

phaseCapPressureMultiplier="{ 1e6, 0 }"
capPressureEpsilon="1e-7"/>
...
</Constitutive>

Table capillary pressure

Overview

The user can specify the capillary pressures using tables describing a piecewise-linear capillary pressure function of
volume fraction (i.e., saturation) for each phase, except the reference phase for which capillary pressure is assumed to
be zero. Depending on the number of fluid phases, this model is used as follows:
• For two-phase flow, the user must specify one capillary pressure table. During the simulation, the capillary
pressure of the non-reference phase is computed by interpolating in the table as a function of the non-reference
phase saturation.
• For three-phase flow, the user must specify two capillary pressure tables. One capillary pressure table is required
for the pair wetting-phase–intermediate-phase (typically, water-oil), and one capillary pressure table is required
for the pair non-wetting-phase–intermediate-phase (typically, gas-oil). During the simulation, the former is used
to compute the wetting-phase capillary pressure as a function of the wetting-phase volume fraction and the latter
is used to compute the non-wetting-phase capillary pressure as a function of the non-wetting-phase volume
fraction. The intermediate phase is assumed to be the reference phase, and its capillary pressure is set to zero.
Below is a table summarizing the choice of reference pressure for the various phase combinations:

Phases present in the model Reference phase

oil, water, gas Oil phase
oil, water Oil phase
oil, gas Oil phase
water, gas Gas phase

In all cases, the user-provided capillary pressure is used in GEOS to compute the phase pressure using the formula:

𝑃𝑐 = 𝑝𝑛𝑤 − 𝑝𝑤 .

where 𝑝𝑛𝑤 and 𝑝𝑤 are respectively the non-wetting-phase and wetting-phase pressures.

Parameters

480 Chapter 1. Table of Contents

GEOS Documentation

XML Element: TableCapillaryPressure

Name Type Default Description

name groupName required A name is required for any
non-unique nodes
nonWettingIntermediate- groupNameRef
CapPressureTableName
Capillary pressure table
[Pa] for the pair
(non-wetting phase,
intermediate phase)
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettingCap-
PressureTableName to
specify the table names

phaseNames groupNameRef_array required List of fluid phases

wettingIntermediateCap- groupNameRef
PressureTableName
Capillary pressure table
[Pa] for the pair (wetting
phase, intermediate
phase)
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettingCap-
PressureTableName to
specify the table names

wettingNonWettingCap- groupNameRef
PressureTableName
Capillary pressure table
[Pa] for the pair (wetting
phase, non-wetting phase)
Note that this input is only
used for two-phase flow.
If you want to do a
three-phase simulation,
please use instead
wettingIntermediateCap-
PressureTableName and
nonWettingIntermediate-
CapPressureTableName
to specify the table names

1.5. User Guide 481

GEOS Documentation

Below are some comments on the model parameters.

• phaseNames - The number of phases can be either two or three. Supported phase names are:

Value Phase
oil Oil phase
gas Gas phase
water Water phase

• wettingNonWettingCapPressureTableName - The name of the capillary pressure table for two-phase

systems. Note that this keyword is only valid for two-phase systems, and is not allowed for three-phase
systems (for which the user must specify instead wettingIntermediateCapPressureTableName and
nonWettingIntermediateCapPressureTableName). This capillary pressure must be a strictly decreasing
function of the water-phase volume fraction (for oil-water systems and gas-water systems), or a strictly increas-
ing function of the gas-phase volume fraction (for oil-gas systems).
• wettingIntermediateCapPressureTableName - The name of the capillary pressure table for the pair
wetting-phase–intermediate-phase. This capillary pressure is applied to the wetting phase, as a function of the
wetting-phase volume fraction. Note that this keyword is only valid for three-phase systems, and is not allowed
for two-phase systems (for which the user must specify instead wettingNonWettingCapPressureTableName).
This capillary pressure must be a strictly decreasing function of the wetting-phase volume fraction.
• nonWettingIntermediateCapPressureTableName - The name of the capillary pressure table for
the pair non-wetting-phase–intermediate-phase. Note that this keyword is only valid for three-
phase systems, and is not allowed for two-phase systems (for which the user must specify instead
wettingNonWettingCapPressureTableName). This capillary pressure must be a strictly increasing function
of the non-wetting-phase volume fraction.

Examples

For a two-phase water-gas system (for instance in the CO2-brine fluid model), a typical capillary pressure input looks
like:

For a three-phase oil-water-gas system (for instance in the Black-Oil fluid model), a typical capillary pressure input
looks like:

482 Chapter 1. Table of Contents

GEOS Documentation

The tables mentioned above by name must be defined in the <Functions> block of the XML file using the
<TableFunction> keyword.

Porosity models
Pressure dependent porosity

Overview

This model assumes a simple exponential law for the porosity as function of pressure, i.e.

𝜑 = 𝜑𝑟𝑒𝑓 𝑒𝑥𝑝(𝑐 · (𝑝 − 𝑝𝑟𝑒𝑓 ))

where 𝜑𝑟𝑒𝑓 is the reference porosity at reference pressure, 𝑝𝑟𝑒𝑓 , 𝑝 is the pressure and, 𝑐 is the compressibility.

Parameters

The following attributes are supported:

XML Element: PressurePorosity

Name Type Default Description

compressibility real64 required Solid compressibility
defaultReferencePorosity real64 required Default value of the reference porosity
name groupName required A name is required for any non-unique nodes
referencePressure real64 required Reference pressure for solid compressibility

Example

Biot Porosity Model

Overview

According to the poroelasticity theory, the porosity (pore volume), 𝜑, can be computed as

𝜑 = 𝜑𝑟𝑒𝑓 + 𝛼(𝜖𝑣 − 𝜖𝑣, 𝑟𝑒𝑓 ) + (𝑝 − 𝑝𝑟𝑒𝑓 )/𝑁.

Here, 𝜑𝑟𝑒𝑓 is the porosity at a reference state with pressure 𝑝𝑟𝑒𝑓 and volumetric strain 𝜖𝑣, 𝑟𝑒𝑓 . Additionally, 𝛼 is the Biot
coefficient, 𝜖𝑣 is the volumetric strain, 𝑝 is the fluid pressure and 𝑁 = 𝛼−𝜑
𝐾𝑠
𝑟𝑒𝑓
, where 𝐾𝑠 is the grain bulk modulus.

1.5. User Guide 483

GEOS Documentation

Parameters

The Biot Porosity Model can be called in the <Constitutive> block of the input XML file. This porosity model must
be assigned a unique name via the name attribute. This name is used to assign the model to regions of the physical
domain via a materialList attribute in the <ElementRegions> block.
The following attributes are supported:

XML Element: BiotPorosity

Name Type Default Description

defaultGrainBulkModulus real64 required Grain bulk modulus
defaultPorosityTEC real64 0 Default thermal expansion coefficient
defaultReferencePorosity real64 required Default value of the reference porosity
name groupName required A name is required for any non-unique nodes
useUniaxialFixedStress integer 0 Flag enabling uniaxial approximation in fixed stress update

Example

Permeability models
Constant Permeability Model

Overview

This model is used to define a diagonal permeability tensor that does not depend on any primary variable.

Parameters

The following attributes are supported:

XML Element: ConstantPermeability

Name Type Default Description

name group- re- A name is required for any non-unique nodes
Name quired
permeabilityCompo- R1Tensor re- xx, yy and zz components of a diagonal permeability tensor.
nents quired

484 Chapter 1. Table of Contents

GEOS Documentation

Example

Exponential Decay Permeability Model

Overview

This stress-dependent permeability model assumes a simple exponential law for the fracture permeability as function
of the effective normal stress acting on the fracture surface (Gutierrez et al., 2000):

𝑘 = 𝑘𝑖 exp(−𝐶𝜎𝑛 ′ )

where 𝑘𝑖 is the initial unstressed fracture permeability; 𝐶 is an empirical constant; 𝜎𝑛 ′ is the effective normal stress.

Parameters

The Exponential Decay Permeability model can be called in the <Constitutive> block of the input XML
file. This permeability model must be assigned a unique name via the name attribute. This name is
used to assign the model to regions of the physical domain via a permeabilityModelName attribute in the
<CompressibleSolidExponentialDecayPermeability> block.
The following attributes are supported:

XML Element: ExponentialDecayPermeability

Name Type Default Description

empiricalConstant real64 required an empirical constant.
initialPermeability R1Tensor required initial permeability of the fracture.
name groupName required A name is required for any non-unique nodes

Example

Kozeny-Carman Permeability Model

1.5. User Guide 485

GEOS Documentation

Overview

In the Kozeny-Carman model (see ref), the permeability of a porous medium is governed by several key parameters,
including porosity, grain size, and grain shape:

(𝑠𝜖 𝐷𝑝 )2 𝜑3
𝑘=
150(1 − 𝜑)2

where 𝑠𝜖 is the sphericity of the particles, 𝐷𝑝 is the particle diameter, 𝜑 is the porosity of the porous medium.

Parameters

The Kozeny-Carman Permeability Model can be called in the <Constitutive> block of the input XML file. This
permeability model must be assigned a unique name via the name attribute. This name is used to assign the model to
regions of the physical domain via a materialList attribute in the <ElementRegions> block.
The following attributes are supported:

XML Element: CarmanKozenyPermeability

Name Type Default Description

anisotropy R1Tensor {1,1,1} Anisotropy factors for three permeability components.
name groupName required A name is required for any non-unique nodes
particleDiameter real64 required Diameter of the spherical particles.
sphericity real64 required Sphericity of the particles.

Example

Parallel Plates Permeability Model

Overview

The parallel plates permeability model defines the relationship between the hydraulic fracture aperture and its corre-
sponding permeability following the classic lubrication model (Witherspoon et al. ) . In this model, the two fracture
walls are assumed to be smooth and parallel to each other and separated by a uniform aperture.

𝑎3
𝑘=
12
where 𝑎 denotes the hydraulic fracture aperture.
Remark: 𝑘, dimensionally, is not a permeability (as it is expressed in 𝑚3 ).

486 Chapter 1. Table of Contents

GEOS Documentation

Parameters

The Parallel Plates Permeability Model can be called in the <Constitutive> block of the input XML file. This
permeability model must be assigned a unique name via the name attribute. This name is used to assign the model to
regions of the physical domain via a materialList attribute in the <ElementRegions> block.
The following attributes are supported:

XML Element: ParallelPlatesPermeability

Name Type De- Description

fault
name group- re- A name is required for any non-unique nodes
Name quired
transversalPer- real64 -1 Default value of the permeability normal to the surface. If not specified the
meability permeability is updated using the cubic law.

Slip Dependent Permeability Model

Overview

The slip dependent permeability model defines the relationship between the relative shear displacement and fracture
permeability. In this model, fractrues/faults are represented as slip interfaces.
[︂ (︂ )︂ ]︂
𝑈𝑠
𝑘 = 𝑘𝑖 (𝑀𝑚𝑢𝑙𝑡 − 1)tanh 3 +1
𝑈𝑠𝑡ℎ𝑟𝑒𝑠ℎ𝑜𝑙𝑑

where 𝑘𝑖 is the initial fracture permeability; 𝑀𝑚𝑢𝑙𝑡 is the maximum permeability multiplier; 𝑈𝑠 is the relative shear
displacement; 𝑈𝑠𝑡ℎ𝑟𝑒𝑠ℎ𝑜𝑙𝑑 is the slip threshold.

Parameters

The Slip Dependent Permeability model can be called in the <Constitutive> block of the input XML
file. This permeability model must be assigned a unique name via the name attribute. This name is
used to assign the model to regions of the physical domain via a permeabilityModelName attribute in the
<CompressibleSolidSlipDependentPermeability> block.
The following attributes are supported:

XML Element: SlipDependentPermeability

Name Type Default Description

initialPermeability R1Tensor required initial permeability of the fracture.
maxPermMultiplier real64 required Maximum permeability multiplier.
name groupName required A name is required for any non-unique nodes
shearDispThreshold real64 required Threshold of shear displacement.

Example

<Constitutive>
...
(continues on next page)

1.5. User Guide 487

GEOS Documentation

(continued from previous page)

Willis-Richards Permeability Model

Overview

In the Willis-Richards permeability model, the stress-aperture relationship is derived based on Barton–Bandis consti-
tutive model. In this model, fracture hydraulic aperture is assumed to be a function of effective normal stress acting on
the fracture surface and shear displacement along the fracture surface (Willis-Richards et al., 1996).
𝑎𝑚 + 𝑈𝑠 tan (𝜑𝑑𝑖𝑙 )
𝑎=
1 + 9 𝜎𝜎𝑟𝑒𝑓
𝑛

Based on the assumption of parallel plates, the correlation between fracture hydraulic aperture and its corresponding
permeability is defined as:

𝑎2
𝑘=
12
where
𝑎 is the fracture hydraulic aperture; 𝑎𝑚 is the fracture aperture at zero contact stress; 𝑈𝑠 is the relative shear
displacement; 𝜑𝑑𝑖𝑙 is the shear dilation angle; 𝜎𝑛 is the effective normal stress acting on the fracture surface;
𝜎𝑟𝑒𝑓 is the effective normal stress that causes a 90% reduction in the fracture hydraulic aperture.

Parameters

The Willis-Richards permeability model is called in the <Constitutive> block of the input XML file.
This permeability model must be assigned a unique name via the name attribute. This name is used
to attach the model to regions of the physical domain via a permeabilityModelName attribute in the
<CompressibleSolidWillisRichardsPermeability> block.
The following attributes are supported:

XML Element: WillisRichardsPermeability

Name Type Default Description

dilationCoefficient real64 required Dilation coefficient (tan of dilation angle).
maxFracAperture real64 required Maximum fracture aperture at zero contact stress.
name groupName required A name is required for any non-unique nodes
refClosureStress real64 required Effective normal stress causes 90% reduction in aperture.

Example

<Constitutive>
...
(continues on next page)

488 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Porous Solids
Overview

Simulation of fluid flow in porous media and of poromechanics, requires to define, along with fluid properties, the
hydrodynamical properties of the solid matrix. Thus, for porous media flow and and poromecanical simulation in
GEOS, two types of composite constitutive models can be defined to specify the characteristics of a porous material:
(1) a CompressibleSolid model, used for flow-only simulations and which assumes that all poromechanical effects can
be represented by the pressure dependency of the porosity; (2) a PorousSolid model which, instead, allows to couple
any solid model with a BiotPorosity model and to include permeability’s dependence on the mechanical response.
Both these composite models require the names of the solid, porosity and permeability models that, combined, define
the porous material. The following sections outline how these models can be defined in the Constitutive block of the
xml input files and which type of submodels they allow for.

CompressibleSolid

This composite constitutive model requires to define a NullModel as solid model (since no mechanical properties are
used), a PressurePorosity model and any type of Permeability model.
To define this composite model the keyword CompressibleSolid has to be appended to the name of the permeability
model of choice, as shown in the following example for the ConstantPermeability model.

</Constitutive>

1.5. User Guide 489

GEOS Documentation

PorousSolid

To run poromechanical problems, the total stress is decomposed into an “effective stress” (driven by mechanical de-
formations) and a pore fluid pressure component, following the Biot theory of poroelasticity. For single-phase flow, or
multiphase problems with no capillarity, this decomposition reads

𝜎𝑖𝑗 = 𝜎′𝑖𝑗 − 𝑏𝑝𝛿𝑖𝑗

where 𝜎𝑖𝑗 is the 𝑖𝑗 component of the total stress tensor, 𝜎′𝑖𝑗 is the 𝑖𝑗 component of the effective (Cauchy) stress tensor,
𝑏 is Biot’s coefficient, 𝑝 is fluid pressure, and 𝛿 is the Kronecker delta.
The PorousSolid models simply append the keyword Porous in front of the solid model they contain, e.g., PorousE-
lasticIsotropic, PorousDruckerPrager, and so on. Additionally, they require to define a BiotPorosity model and a Con-
stantPermeability model. For example, a Poroelastic material with a certain permeability can be defined as

Note that any of the previously described solid models is used by the PorousSolid model to compute the effective stress,
leading to either poro-elastic, poro-plastic, or poro-damage behavior depending on the specific model chosen.

Temperature-dependent Solid Volumetric Heat Capacity Model

Overview

In this model, solid volumetric specific heat capacity is assumed to be a linear function of temperature:
𝑑𝐶
𝐶 = 𝐶0 + (𝑇 − 𝑇0 )
𝑑𝑇
where
𝐶 is the solid volumetric heat capacity at temperature T; 𝐶0 is the reference solid volumetric heat capacity at the
reference temperature; 𝑇0 is the reference temperature; 𝑑𝐶𝑑𝑇 is the gradient of the volumetric heat capacity with
respect to temperature, which equals to zero for the cases with constant solid volumetric heat capacity;

Parameters

The temperature-dependent solid volumetric heat capacity model is called in the <SolidInternalEnergy> block
of the input XML file. This model must be assigned a unique name via the name attribute. This name is used
to attach the model to regions of the physical domain via a solidInternalEnergyModelName attribute in the
<CompressibleSolidConstantPermeability> block.

490 Chapter 1. Table of Contents

GEOS Documentation

The following attributes are supported:

XML Element: SolidInternalEnergy

Name Type De- Description

fault
dVolumetricHeatCapac- real64 0 Derivative of the solid volumetric heat capacity w.r.t. tem-
ity_dTemperature perature [J/(m^3.K^2)]
name group- re- A name is required for any non-unique nodes
Name quired
referenceInternalEnergy real64 re- Internal energy at the reference temperature [J/kg]
quired
referenceTemperature real64 re- Reference temperature [K]
quired
referenceVolumetricHeatCa- real64 re- Reference solid volumetric heat capacity [J/(kg.K)]
pacity quired

Example

Temperature-dependent Thermal Conductivity Model

Overview

In this model, thermal conductivity of porous medium is defined as a linear function of temperature:

𝑑𝑘
𝑘 = 𝑘0 + (𝑇 − 𝑇0 )
𝑑𝑇
where
𝑘 is the thermal conductivity at temperature T, which is a vector; 𝑘0 is the reference thermal conductivity at
the reference temperature; 𝑇0 is the reference temperature; 𝑑𝑇𝑑𝑘
is the gradient of the thermal conductivity with
respect to temperature, which equals to zero for the cases with constant thermal conductivity; note that this term
is also in vector form, whose components could vary with directions.

Parameters

The temperature-dependent thermal conductivity model is called in the <SinglePhaseThermalConductivity>

block of the input XML file. This model must be assigned a unique name via the name attribute. This name is used to
attach the model to CellElementRegion of the physical domain in the <ElementRegions> block.
The following attributes are supported:

1.5. User Guide 491

GEOS Documentation

XML Element: SinglePhaseThermalConductivity

Name Type De- Description

fault
defaultThermalConduc- R1Tensor re- xx, yy, and zz diagonal components of the default thermal conduc-
tivityComponents quired tivity tensor [J/(s.m.K)]
name group- re- A name is required for any non-unique nodes
Name quired
referenceTemperature real64 0 The reference temperature at which the conductivity components are
equal to the default values
thermalConductivityGra- R1Tensor {0,0,0} xx, yy, and zz diagonal components of the thermal conductivity gra-
dientComponents dient tensor w.r.t. temperature [J/(s.m.K^2)]

Example

In an input XML file, constitutive models are listed in the <Constitutive> block. Each parameterized model has
its own XML tag, and each must be assigned a unique name via the name attribute. Names are used to assign models
to regions of the physical domain via the materialList attribute of the <CellElementRegion> node (see XML
Element: ElementRegions). In some cases, physics solvers must also be assigned specific constitutive models to use
(see Physics Solvers).
A typical <Constitutive> and <ElementRegions> block will look like:

</Constitutive>

<CellElementRegion
(continues on next page)

492 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

name="region1"
cellBlocks="{ * }"
materialList="{ water }"/>

</ElementRegions>

... remainder of problem definition here ...

</Problem>

1.5.5 Constitutive Drivers

To test and calibrate constitutive models, GEOS provides a set of drivers that can be used to run simulations with
specific input parameters. These drivers are designed to facilitate the exploration of various constitutive behaviors and
to validate the models against known benchmarks.

PVT Driver

Table of Contents

• PVT Driver
– Introduction
– XML Structure
– Parameters
• XML Element: PVTDriver
– Output Format
– Unit Testing

Introduction

When calibrating fluid material parameters to experimental or other reference data, it can be a hassle to launch a full
flow simulation just to confirm density, viscosity, and other fluid properties are behaving as expected. Instead, GEOS
provides a PVTDriver allowing the user to test fluid property models for a well defined set of pressure, temperature,
and composition conditions. The driver itself is launched like any other GEOS simulation, but with a particular XML
structure:

./bin/geosx -i myFluidTest.xml

This driver will work for any multi-phase fluid model (e.g. black-oil, co2-brine, compositional multiphase) enabled
within GEOS.

XML Structure

A typical XML file to run the driver will have several key elements. Here, we will walk through an example file included
in the source tree at

1.5. User Guide 493

GEOS Documentation

src/coreComponents/unitTests/constitutiveTests/testPVT_docExample.xml

The first thing to note is that the XML file structure is identical to a standard GEOS input deck. In fact, once the
constitutive block is calibrated, one could start adding solver and discretization blocks to the same file to create a
proper field simulation. This makes it easy to go back and forth between calibration and simulation.
The first step is to define a parameterized fluid model to test. Here, we create a particular type of CO2-Brine mixture:

<Constitutive>
<CO2BrinePhillipsFluid
name="co2Mixture"
phaseNames="{ gas, water }"
componentNames="{ co2, water }"
componentMolarWeight="{ 44e-3, 18e-3 }"
phasePVTParaFiles="{ testPVT_data/carbonDioxidePVT.txt, testPVT_data/brinePVT.txt }
˓→"

flashModelParaFile="testPVT_data/carbonDioxideFlash.txt"/>
</Constitutive>

We also define two time-history functions for the pressure (Pascal units) and temperature (Kelvin units) conditions we
want to explore.

Note that the time-axis here is just a pseudo-time, allowing us to parameterize arbitrarily complicated paths through a
(pressure,temperature) diagram. The actual time values have no impact on the resulting fluid properties. Here, we fix
the temperature at 350K and simply ramp up pressure from 1 MPa to 50 MPa:
A PVTDriver is then added as a Task, a particular type of executable event often used for simple actions.

The driver itself takes as input the fluid model, the pressure and temperature control functions, and a “feed composition.”

494 Chapter 1. Table of Contents

GEOS Documentation

The latter is the mole fraction of each component in the mixture to be tested. The steps parameter controls how many
steps are taken along the parametric (P,T) path. Results will be written in a simple ASCII table format (described
below) to the file output. The logLevel parameter controls the verbosity of log output during execution.
The driver task is added as a SoloEvent to the event queue. This leads to a trivial event queue, since all we do is
launch the driver and then quit.

Internally, the driver uses a simple form of time-stepping to advance through the (P,T) steps. This timestepping is
handled independently of the more complicated time-stepping pattern used by physics Solvers and coordinated by
the EventManager. In particular, in the XML file above, the maxTime parameter in the Events block is an event
manager control, controlling when/if certain events occur. Once launched, the PVTDriver internally determines its
own max time and timestep size using a combination of the input functions’ time coordinates and the requested number
of loadsteps. It is therefore helpful to think of the driver as an instantaneous event (from the event manager’s point of
view), but one which has a separate, internal clock.

Parameters

The key XML parameters for the PVTDriver are summarized in the following table:

XML Element: PVTDriver

Name Type De- Description

fault
baseline path none Baseline file
feedComposition real64_array re- Feed composition array [mol fraction]
quired
fluid group- re- Fluid to test
NameRef quired
logLevel integer 0 Log level
name groupName re- A name is required for any non-unique nodes
quired
output string none Output file
outputCompressibility integer 0 Flag to indicate that the total compressibility should be output
outputMassDensity integer 0 Flag to indicate that the mass density of each phase should be
output
outputPhaseComposi- integer 0 Flag to indicate that phase compositions should be output
tion
pressureControl group- re- Function controlling pressure time history
NameRef quired
steps integer re- Number of load steps to take
quired
temperatureControl group- re- Function controlling temperature time history
NameRef quired

1.5. User Guide 495

GEOS Documentation

Output Format

The output key is used to identify a file to which the results of the simulation are written. If this key is omitted, or the
user specifies output="none", file output will be suppressed. The file is a simple ASCII format with a brief header
followed by test data:

# column 1 = time
# column 2 = pressure
# column 3 = temperature
# column 4 = density
# columns 5-6 = phase fractions
# columns 7-8 = phase densities
# columns 9-10 = phase viscosities
0.0000e+00 1.0000e+06 3.5000e+02 1.5581e+01 1.0000e+00 4.1138e-11 1.5581e+01 1.0033e+03␣
˓→1.7476e-05 9.9525e-04

2.0408e-02 2.0000e+06 3.5000e+02 3.2165e+01 1.0000e+00 4.1359e-11 3.2165e+01 1.0050e+03␣

˓→1.7601e-05 9.9525e-04

4.0816e-02 3.0000e+06 3.5000e+02 4.9901e+01 1.0000e+00 4.1563e-11 4.9901e+01 1.0066e+03␣

˓→1.7778e-05 9.9525e-04

...

Note that the number of columns will depend on how many phases and components are present. In this case, we have a
two-phase, two-component mixture. The total density is reported in column 4, while phase fractions, phase densities,
and phase viscosities are reported in subsequent columns. If the outputCompressibility flag is activated, an extra
column will be added for the total fluid compressibility after the density. This is defined as 𝑐𝑡 = 𝜌1𝑡 (𝜕𝜌𝑡 /𝜕𝑃 ) where
𝜌𝑡 is the total density. If the outputMassDensity flag is activated, extra columns will be added for the mass density
of each phase. The number of columns will also depend on whether the outputPhaseComposition flag is activated
or not. If it is activated, there will be an extra column for the mole fraction of each component in each phase. The
phase order will match the one defined in the input XML (here, the co2-rich phase followed by the water-rich phase).
This file can be readily plotted using any number of plotting tools. Each row corresponds to one timestep of the driver,
starting from initial conditions in the first row.

Unit Testing

The development team also uses the PVTDriver to perform unit testing on the various fluid models within GEOS.
The optional argument baseline can be used to point to a previous output file that has been validated (e.g. against
experimental benchmarks or reference codes). If such a file is specified, the driver will perform a testing run and then
compare the new results against the baseline. In this way, any regressions in the fluid models can be quickly identified.
Developers of new models are encouraged to add their own baselines to src/coreComponents/constitutive/
unitTests. Adding additional tests is straightforward:
1. Create a new xml file for your test in src/coreComponents/constitutive/unitTests or (easier) add extra
blocks to the existing XML at src/coreComponents/constitutive/unitTests/testPVT.xml. For new XMLs,
we suggest using the naming convention testPVT_myTest.xml, so that all tests will be grouped together alphabet-
ically. Set the output file to testPVT_myTest.txt, and run your test. Validate the results however is appropriate.
If you have reference data available for this validation, we suggest archiving it in the testPVT_data/ subdirectory,
with a description of the source and formatting in the file header. Several reference datasets are included already as
examples. This directory is also a convenient place to store auxiliary input files like PVT tables.
2. This output file will now become your new baseline. Replace the output key with baseline so that the driver can
read in your file as a baseline for comparison. Make sure there is no remaining output key, or set output=none, to
suppress further file output. While you can certainly write a new output for debugging purposes, during our automated
unit tests we prefer to suppress file output. Re-run the driver to confirm that the comparison test passes.
3. Modify src/coreComponents/constitutive/unitTests/CMakeLists.txt to enable your new test in the unit

496 Chapter 1. Table of Contents

GEOS Documentation

test suite. In particular, you will need to add your new XML file to the existing list in the gtest_pvt_xmls variable.
Note that if you simply added your test to the existing testPVT.xml file, no changes are needed.

set( gtest_pvt_xmls
testPVT.xml
testPVT_myTest.xml
)

4. Run make in your build directory to make sure the CMake syntax is correct
5. Run ctest -V -R PVT to run the PVT unit tests. Confirm your test is included and passes properly.
If you run into troubles, do not hesitate to contact the development team for help.

Triaxial Driver

Table of Contents

• Triaxial Driver
– Introduction
– XML Structure
• XML Element: TriaxialDriver
– Test Modes
– Output Format
– Model Convergence
– Unit Testing

Introduction

When calibrating solid material parameters to experimental data, it can be a hassle to launch a full finite element
simulation to mimic experimental loading conditions. Instead, GEOS provides a TriaxialDriver allowing the user
to run loading tests on a single material point. This makes it easy to understand the material response and fit it to lab
data. The driver itself is launched like any other GEOS simulation, but with a particular XML structure:

./bin/geosx -i myTest.xml

XML Structure

A typical XML file to run the triaxial driver will have the following key elements. We present the whole file first, before
digging into the individual blocks.

Name Type De- Description

fault
axialCon- groupNameRef re- Function controlling axial stress or strain (depending on test
trol quired mode)
baseline path none Baseline file
initialStress real64 re- Initial stress (scalar used to set an isotropic stress state)
quired
logLevel integer 0 Log level
material groupNameRef re- Solid material to test
quired
mode geos_TriaxialDriver_Mode re- Test mode [stressControl, strainControl, mixedControl]
quired
name groupName re- A name is required for any non-unique nodes
quired
output string none Output file
radialCon- groupNameRef re- Function controlling radial stress or strain (depending on test
trol quired mode)
steps integer re- Number of load steps to take
quired

ò Note

GEOS uses the engineering sign convention where compressive stresses and strains are negative. This is one of
the most frequent issues users make when calibrating material parameters, as stress- and strain-like quantities often
need to be negative to make physical sense. You may note in the XML above, for example, that stressFunction
and strainFunction have negative values for a compressive test.

Test Modes

The most complicated part of the driver is understanding how the stress and strain functions are applied in different
testing modes. The driver mimics laboratory core tests, with loading controlled in the axial and radial directions.
These conditions may be either strain-controlled or stress-controlled, with the user providing time-dependent functions
to describe the loading. The following table describes the available test modes in detail:

mode axial loading radial loading initial stress

Note that a classical triaxial test can be described using either the stressControl or mixedControl mode. We
recommend using the mixedControl mode when possible, because this almost always leads to well-posed loading
conditions. In a pure stress controlled test, it is possible for the user to request that the material sustain a load beyond
its intrinsic strength envelope, in which case there is no feasible solution and the driver will fail to converge. Imagine,
for example, a perfectly plastic material with a yield strength of 10 MPa, but the user attempts to load it to 11 MPa.

500 Chapter 1. Table of Contents

GEOS Documentation

A volumetric test can be created by setting the axial and radial control functions to the same time history function.
Similarly, an oedometer test can be created by setting the radial strain to zero.
The user should be careful to ensure that the initial stress set via the initialStress value is consistent any applied
stresses set through axial or radial loading functions. Otherwise, the material may experience sudden and unexpected
deformation at the first timestep because it is not in static equilibrium.

Output Format

# column 1 = time
# column 2 = axial_strain
# column 3 = radial_strain_1
# column 4 = radial_strain_2
# column 5 = axial_stress
# column 6 = radial_stress_1
# column 7 = radial_stress_2
# column 8 = newton_iter
# column 9 = residual_norm
0.0000e+00 0.0000e+00 0.0000e+00 0.0000e+00 -1.0000e+00 -1.0000e+00 -1.0000e+00 0.
˓→0000e+00 0.0000e+00
1.6000e-01 -1.6000e-04 4.0000e-05 4.0000e-05 -1.1200e+00 -1.0000e+00 -1.0000e+00 2.
˓→0000e+00 0.0000e+00
3.2000e-01 -3.2000e-04 8.0000e-05 8.0000e-05 -1.2400e+00 -1.0000e+00 -1.0000e+00 2.
˓→0000e+00 0.0000e+00
...

This file can be readily plotted using any number of plotting tools. Each row corresponds to one timestep of the driver,
starting from initial conditions in the first row.
We note that the file contains two columns for radial strain and two columns for radial stress. For an isotropic material,
the stresses and strains along the two radial axes will usually be identical. We choose to output this way, however, to
accommodate both anisotropic materials and true-triaxial loading conditions. In these cases, the stresses and strains in
the radial directions could potentially differ.
These columns can be added and subtracted to produce other quantities of interest, like mean stress or deviatoric stress.
For example, we can plot the output produce stress / strain curves (in this case for a plastic rather than simple elastic
material):

Fig. 1.88: Stress/strain behavior for a plastic material.

In this plot, we have reversed the sign convention to be consistent with typical experimental plots. Note also that the
strainFunction includes two unloading cycles, allowing us to observe both plastic loading and elastic unloading.

Model Convergence

The last two columns of the output file contain information about the convergence behavior of the material driver. In
triaxial mode, the mixed nature of the stress/strain control requires using a Newton solver to converge the solution.
This last column reports the number of Newton iterations and final residual norm. Large values here would be indica-
tive of the material model struggling (or failing) to converge. Convergence failures can result from several reasons,
including:
1. Inappropriate material parameter settings

1.5. User Guide 501

GEOS Documentation

2. Overly large timesteps

3. Infeasible loading conditions (i.e. trying to load a material to a physically-unreachable stress point)
4. Poor model implementation
We generally spend a lot of time vetting the material model implementations (#4). When you first encounter a problem,
it is therefore good to explore the other three scenarios first. If you find something unusual in the model implementation
or are just really stuck, please submit an issue on our issue tracker so we can help resolve any bugs.

Unit Testing

The development team also uses the Triaxial Driver to perform unit testing on the various material models within
GEOS. The optional argument baseline can be used to point to a previous output file that has been validated (e.g.
against analytical or experimental benchmarks). If such a file is specified, the driver will perform a loading run and
then compare the new results against the baseline. In this way, any regressions in the material models can be quickly
identified.
Developers of new models are encouraged to add their own baselines to src/coreComponents/constitutive/
unitTests. Adding additional tests is straightforward:
1. Create a new xml file for your test in src/coreComponents/constitutive/unitTests. There are sev-
eral examples is this directory already to use as a template. We suggest using the naming convention
testTriaxial_myTest.xml, so that all triaxial tests will be grouped together alphabetically. Set the output
file to testTriaxial_myTest.txt, and run your test. Validate the results however is appropriate.
2. This output file will now become your new baseline. Replace the output key with baseline so that the
driver can read in your file as a baseline for comparison. Make sure there is no remaining output key, or
set output=none, to suppress further file output. While you can certainly write a new output for debugging
purposes, during our automated unit tests we prefer to suppress file output. Re-run the triaxial driver to confirm
that the comparison test passes.
3. Modify src/coreComponents/constitutive/unitTests/CMakeLists.txt to enable your new test in
the unit test suite. In particular, you will need to add your new XML file to the existing list in the
gtest_triaxial_xmls variable:

set( gtest_triaxial_xmls
testTriaxial_elasticIsotropic.xml
testTriaxial_druckerPragerExtended.xml
testTriaxial_myTest.xml
)

4. Run make in your build directory to make sure the CMake syntax is correct
5. Run ctest -V -R Triax to run the triaxial unit tests. Confirm your test is included and passes properly.
If you run into troubles, do not hesitate to contact the development team for help.

1.5.6 Initial and Boundary Conditions

Hydrostatic Equilibrium Initial Condition
Overview

The user can request an initialization procedure enforcing a hydrostatic equilibrium for flow simulations and for coupled
flow and mechanics simulations. The hydrostatic initialization is done by placing one or more HydrostaticEquilibrium
tag(s) in the FieldSpecifications block of the XML input file. This initialization procedure is described below in the
context of single-phase and compositional multiphase flow. At the end of this document, we compare the hydrostatic
equilibrium method to another initialization method, based on the input of x-y-z tables.

502 Chapter 1. Table of Contents

GEOS Documentation

Single-phase flow parameters

For single-phase flow, the HydrostaticEquilibrium initialization procedure requires the following user input parame-
ters:
• datumElevation: the elevation (in meters) at which the datum pressure is enforced. The user must ensure that
the datum elevation is within the elevation range defined by the input mesh. GEOS issues a warning if this is not
the case.
• datumPressure: the pressure value (in Pascal) enforced by GEOS at the datum elevation.
• objectPath: the path defining the groups on which the hydrostatic equilibrium is computed. We recommend
using ElementRegions to apply the hydrostatic equilibrium to all the cells in the mesh. Alternatively, the
format ElementRegions/NameOfRegion/NameOfCellBlock can be used to select only a cell block on which
the hydrostatic equilibrium is computed.

ò Note

In GEOS, the z-axis is positive going upward, this is why the attributes listed in this page are expressed as a function
of elevation, not depth.

Using these parameters and the pressure-density constitutive relationship, GEOS uses a fixed-point iteration scheme
to populate a table of hydrostatic pressures as a function of elevation. The fixed-point iteration scheme uses two
optional attributes: equilibriumTolerance, the absolute tolerance to declare that the algorithm has converged, and
maxNumberOfEquilibrationTolerance, the maximum number of iterations for a given elevation in the fixed point
iteration scheme.
In addition, the elevation spacing of the hydrostatic pressure table is set with the optional
elevationIncrementInHydrostaticPressureTable parameter (in meters), whose default value is 0.6096
meters. Then, once the table is fully constructed, the hydrostatic pressure in each cell is obtained by interpolating in
the hydrostatic pressure table using the elevation at the center of the cell.

ò Note

The initialization algorithm assumes that the gravityVector (defined in the Solvers XML tag) is aligned with the
z-axis. If this is not the case, GEOS terminates the simulation when the HydrostaticEquilibrium tag is detected
in the XML file.

Compositional multiphase flow parameters

For compositional multiphase flow, the HydrostaticEquilibrium initialization procedure follows the same logic but
requires more input parameters. In addition to the required datumElevation, datumPressure, and objectPath
parameters listed above, the user must specify:
• componentNames: the names of the components present in the fluid model. This field is used to make sure
that the components provided to HydrostaticEquilibrium are consistent with the components listed in the fluid
model of the Constitutive block.
• componentFractionVsElevationTableNames: the names of 𝑛𝑐 tables (where 𝑛𝑐 is the number of compo-
nents) specifying the component fractions as a function of elevation. There must be one table name per compo-
nent, and the table names must be listed in the same order as the components in componentNames.
• temperatureVsElevationTableName: the names of the table specifying the temperature (in Kelvin) as a
function of elevation.

1.5. User Guide 503

GEOS Documentation

• initialPhaseName: the name of the phase initially saturating the domain. The other phases are assumed to be
at residual saturation at the beginning of the simulation.
These parameters are used with the fluid density model (depending for compositional flow on pressure, component
fractions, and in some cases, temperature) to populate the hydrostatic pressure table, and later initialize the pressure in
each cell.

ò Note

The current initialization algorithm has an important limitation and does not support initial phase contacts (e.g.,
water-oil, gas-oil, or water-gas contacts). The implementation assumes only one mobile phase in the initial system,
identified by the initialPhaseName attribute. The other phases are assumed at residual saturation. As a result,
the system may not be at equilibrium if there is initially more than one mobile phase in the system (for instance if
the domain is saturated with gas at the top, and water at the bottom, for instance).

ò Note

As in the single-phase flow case, GEOS terminates the simulation if HydrostaticEquilibrium tag is present in an
XML file defining a gravityVector not aligned with the z-axis.

The full list of parameters is provided below:

504 Chapter 1. Table of Contents

GEOS Documentation

XML Element: HydrostaticEquilibrium

Name Type De- Description

fault
bcApplicationTableName group- Name of table that specifies the on/off application of the
NameRef boundary condition.
beginTime real64 - Time at which the boundary condition will start being ap-
1e+99 plied.
componentFractionVsEle- group- {} Names of the tables specifying the (component fraction vs
vationTableNames NameRef_array elevation) relationship for each component
componentNames string_array {} Names of the fluid components
datumElevation real64 re- Datum elevation [m]
quired
datumPressure real64 re- Datum pressure [Pa]
quired
direction R1Tensor {0,0,0} Direction to apply boundary condition to.
elevationIncrementInHy- real64 0.6096 Elevation increment [m] in the hydrostatic pressure table
drostaticPressureTable constructed internally
endTime real64 1e+99 Time at which the boundary condition will stop being ap-
plied.
equilibrationTolerance real64 0.001 Tolerance in the fixed-point iteration scheme used for hydro-
static initialization
functionName group- Name of function that specifies variation of the boundary
NameRef condition.
initialPhaseName group- Name of the phase initially saturating the reservoir
NameRef
logLevel integer 0 Log level
maxNumberOfEquilibra- integer 5 Maximum number of equilibration iterations
tionIterations
name groupName re- A name is required for any non-unique nodes
quired
objectPath group- Path to the target field
NameRef
scale real64 0 Scale factor for value of the boundary condition.
temperatureVsEleva- group- Name of the table specifying the (temperature [K] vs eleva-
tionTableName NameRef tion) relationship

Examples

For single-phase flow, a typical hydrostatic equilibrium input looks like:

</FieldSpecifications>

For compositional multiphase flow, using for instance the CO2-brine flow model, a typical hydrostatic equilibrium

1.5. User Guide 505

GEOS Documentation

input looks like:

</FieldSpecifications>

In this case, a possible way to provide the three required tables is:

</Functions>

Note that the spacing of the two component fraction tables must be the same, but the spacing of the temperature table
can be different.

Expected behavior and comparison with another initialization method

As illustrated in Tutorial 3: Regions and Property Specifications, users can also use multiple FieldSpecification tags
to impose initial fields, such as the pressure, component fractions, and temperature fields. To help users select the
initialization method that best meets their needs, we summarize and compare below the two possible ways to initialize
complex, non-uniform initial fields for compositional multiphase simulations in GEOS.

Initialization using HydrostaticEquilibrium

This is the initialization procedure that we have described in the first sections of this page. In HydrostaticEquilib-
rium, the initial component fractions and temperatures are provided as a function of elevation only, and the hydrostatic
pressure is computed internally before the simulation starts. The typical input was illustrated for a CO2-brine fluid
model in the previous paragraph.

506 Chapter 1. Table of Contents

GEOS Documentation

Expected behavior:
• If FieldSpecification tags specifying initial pressure, component fractions, and/or temperature are included in
an XML input file that also contains the HydrostaticEquilibrium tag, the FieldSpecification tags are ignored
by GEOS. In other words, only the pressure, component fractions, and temperature fields defined with the Hy-
drostaticEquilibrium tag as a function of elevation are taken into account.
• In the absence of source/sink terms and wells, the initial flow residual should be smaller than 10− 6. Similarly,
in coupled simulations, the residual of the mechanical problem should be close to zero.

Initialization using FieldSpecification tags

This is the initialization method illustrated in Tutorial 3: Regions and Property Specifications. The user can impose ini-
tial pressure, component fractions, and temperature fields using FieldSpecification tags, such as, for a two-component
CO2-brine case:

<FieldSpecification
name="initialTemperature"
initialCondition="1"
setNames="{ all }"
objectPath="ElementRegions"
fieldName="temperature"
scale="1"
(continues on next page)

1.5. User Guide 507

GEOS Documentation

(continued from previous page)

functionName="initialTemperatureTableXYZ"/>

</FieldSpecifications>

In this input method, initialPressureTableXYZ, initialCO2CompFracTableXYZ,

initialWaterCompFracTableXYZ, and initialTemperatureTableXYZ are tables describing these initial
fields as a function of the x, y, and z spatial coordinates. Then, the cell-wise values are determined by interpolating in
these tables using the coordinates of the center of the cells.
Expected behavior:
• In this approach, it is the responsibility of the user to make sure that these initial fields satisfy a hydrostatic
equilibrium. If not, the model will equilibrate itself during the first time steps of the simulation, possibly causing
large initial changes in pressure, component fractions, and temperature.
• If the initial state imposed by the FieldSpecification tags is not at equilibrium, the displacements produced by
coupled flow and mechanics simulations should be interpreted with caution, as these displacements are computed
with respect to a non-equilibrium initial state.
• This method is suited to impose initial fields in complex cases currently not supported by the HydrostaticEqui-
librium tag (e.g., in the presence of phase contacts, capillary pressure, etc). Specifically, the user can equilibrate
the model using other means (such as using another simulator, or running a few steps of GEOS), retrieve the
equilibrated values, convert them into x-y-z tables, and impose them in the new GEOS simulations using Field-
Specification tags.

Aquifer Boundary Condition

Overview

Aquifer boundary conditions allow simulating flow between the computational domain (the reservoir) and one or mul-
tiple aquifers. In GEOS, we use a Carter-Tracy aquifer model parameterized in Aquifer tags of the FieldSpecifications
XML input file blocks.

Aquifer model

An aquifer 𝐴 is a source of volumetric flow rate 𝑞𝑓𝐴 , where 𝑓 is the index of a face connecting the aquifer and the
reservoir. We use a Carter-Tracy model in GEOS to compute this volumetric flow rate.
Once 𝑞𝑓𝐴 is computed, the aquifer mass contribution 𝐹𝑓𝐴 is assembled and added to the mass conservation equations of
the reservoir cell 𝐾 connected to face 𝑓 . The computation of 𝐹𝑓𝐴 depends on the sign of the volumetric flow rate 𝑞𝑓𝐴 .
The upwinding procedure is done as follows: if the sign of 𝑞𝑓𝐴 indicates that flow goes from the aquifer to the reservoir,
the aquifer contribution to the conservation equation of component 𝑐 is:
𝐴
𝐹𝑓,𝑐 = 𝜌𝐴 𝐴 𝐴
𝑤 𝑦𝑤,𝑐 𝑞𝑓

where 𝜌𝐴𝑤 is the aquifer mass/molar water phase density and 𝑦𝑤,𝑐 is the aquifer mass/molar fraction of component 𝑐 in
𝐴

the water phase. We assume that the aquifer is fully saturated with the water phase.
If the sign of 𝑞𝑓𝐴 indicates that flow goes from the reservoir into the aquifer, the aquifer contribution to the mass/molar
conservation equation of component 𝑐 is computed as:
𝑛𝑝
∑︁
𝐴
𝐹𝑓,𝑐 = (𝜌ℓ 𝑆ℓ 𝑦ℓ,𝑐 )𝐾 𝑞𝑓𝐴
ℓ=1

where 𝑛𝑝 is the number of fluid phases, (𝜌ℓ )𝐾 is the reservoir cell mass/molar density of phase ℓ, (𝑆ℓ )𝐾 is the reservoir
cell saturation of phase ℓ, and (𝑦ℓ,𝑐 )𝐾 is the reservoir cell mass/molar fraction of component 𝑐 in phase ℓ.

508 Chapter 1. Table of Contents

GEOS Documentation

In the next section, we review the computation of the aquifer volumetric flow rate 𝑞𝑓𝐴 .

Carter-Tracy analytical aquifer

The Carter-Tracy aquifer model is a simplified approximation to a fully transient model (see R. D. Carter and G. W.
Tracy, An improved method for calculating water influx, Transactions of the AIME, 1960).
Although the theory was developed for a radially symmetric reservoir surrounded by an annular aquifer, this method
applies to any geometry where the dimensionless pressure can be expressed as a function of a dimensionless time.
The two main parameters that govern the behavior of the aquifer are the time constant and the influx constant. These
two parameters are precomputed at the beginning of the simulation and are later used to compute the aquifer volumetric
flow rate.

Time constant

The time constant, 𝑇𝑐 , has the dimension of time (in seconds).

It is computed as:

𝜇𝐴 𝐴 𝐴 𝐴 2
𝑤 𝜑 𝑐𝑡 (𝑟0 )
𝑇𝑐 =
𝑘𝐴
where 𝜇𝐴𝑤 is the aquifer water phase viscosity, 𝜑 is the aquifer porosity, 𝑐𝑡 is the aquifer total compressibility (fluid
𝐴 𝐴

and rock), 𝑟0 is the inner radius of the aquifer, and 𝑘 is the aquifer permeability.
𝐴 𝐴

The time constant is used to convert time (𝑡, in seconds) into dimensionless time, 𝑡𝐷 using the following expression:
𝑡
𝑡𝐷 =
𝑇𝑐

Influx constant

The influx constant, 𝛽, has the dimension of 𝑚3 .𝑃 𝑎−1 .

It is computed as:

𝛽 = 6.283ℎ𝐴 𝜃𝐴 𝜑𝐴 𝑐𝐴 𝐴 2
𝑡 (𝑟0 )

where ℎ𝐴 is the aquifer thickness, 𝜃𝐴 is the aquifer angle, 𝜑𝐴 is the aquifer porosity, 𝑐𝐴
𝑡 is the aquifer total compress-
ibility (fluid and rock), and 𝑟0𝐴 is the inner radius of the aquifer.

Aquifer volumetric flow rate

Let us consider a reservoir cell 𝐾 connected to aquifer 𝐴 through face 𝑓 , and the corresponding aquifer volumetric
flow rate 𝑞𝑓𝐴 over time interval [𝑡𝑛 , 𝑡𝑛+1 ].
The computation of 𝑞𝑓𝐴 proceeds as follows:

𝑞𝑓𝐴 = 𝛼𝑓𝐴 (𝑎 − 𝑏(𝑝𝐾 (𝑡𝑛+1 ) − 𝑝𝐾 (𝑡𝑛 )))

where 𝛼𝑓𝐴 is the area fraction of face f, and 𝑝𝐾 (𝑡𝑛+1 ) and 𝑝𝐾 (𝑡𝑛 ) are the pressures in cell 𝐾 at time 𝑡𝑛+1 and time 𝑡𝑛 ,
respectively.
The area fraction of face 𝑓 with area |𝑓 | is computed as:

|𝑓 |
𝛼𝑓𝐴 = ∑︀
𝑓𝑖 ∈𝐴 |𝑓𝑖 |

1.5. User Guide 509

GEOS Documentation

The coefficient 𝑎 is computed as:

′ 𝑛+1
1 𝛽∆Φ𝐴 𝑛 𝐴 𝑛
𝐾 (𝑡𝐷 ) − 𝑊 (𝑡𝐷 )𝑃𝐷 (𝑡𝐷 )
𝑎=
𝑇𝑐 𝑃𝐷 (𝑡𝑛+1 𝑛+1 ′ 𝑛+1
𝐷 ) − 𝑡𝐷 𝑃𝐷 (𝑡𝐷 )

and the coefficient 𝑏 is given by the formula:

1 𝛽
𝑏=
𝑇𝑐 𝑃𝐷 (𝑡𝑛+1
𝐷 ) − 𝑡𝑛+1 ′ 𝑛+1
𝐷 𝑃𝐷 (𝑡𝐷 )

where ∆Φ𝐴 𝐾 (𝑡𝐷 ) := 𝑝 − 𝑝𝐾 (𝑡 ) − 𝜌𝑤 𝑔(𝑧𝐾 − 𝑧 ) is the potential difference between the reservoir cell and the aquifer
𝑛 𝐴 𝑛 𝐴 𝐴

at time 𝑡𝑛 , 𝑃𝐷 (𝑡𝐷 ) is the dimensionless pressure evaluated at dimensionless time 𝑡𝐷 , 𝑃𝐷

′
(𝑡𝐷 ) is the derivative of the
dimensionless pressure with respect to dimensionless time, evaluated at dimensionless time 𝑡𝐷 .
The functional relationship of dimensionless pressure, 𝑃𝐷 , as a function of dimensionless time is provided by the user.
A default table is also available, as shown below. The cumulative aquifer flow rate, 𝑊 𝐴 (𝑡𝑛𝐷 ), is an explicit quantity
evaluated at 𝑡𝑛𝐷 and updated at the end of each converged time step using the formula:
∑︁
𝑊 𝐴 (𝑡𝑛+1 𝐴 𝑛
𝐷 ) = 𝑊 (𝑡𝐷 ) + (𝑡
𝑛+1
− 𝑡𝑛 ) 𝑞𝑓𝐴
𝑓 ∈𝐴

with 𝑊 𝐴 (0) := 0.

Parameters

The main Carter-Tracy parameters and the expected units are listed below:
• aquiferPorosity: the aquifer porosity 𝜑𝐴 .
• aquiferPermeability: the aquifer permeability 𝑘 𝐴 (in m2).

𝐾.
• aquiferInitialPressure: the aquifer initial pressure 𝑝𝐴 (in Pa), used to compute ∆Φ𝐴

𝑤 (in Pa.s).
• aquiferWaterViscosity: the aquifer water viscosity 𝜇𝐴
• aquiferWaterDensity: the aquifer water mass/molar density 𝜌𝐴
𝑤 (in kg/m3 or mole/m3).

• aquiferWaterPhaseComponentNames: the name of the components in the water phase. These names must match
the component names listed in the fluid model of the Constitutive block. This parameter is ignored in single-
phase flow simulations.
• aquiferWaterPhaseComponentFraction: the aquifer component fractions in the water phase, 𝑦𝑤,𝑐
𝐴
. The compo-
nents must be listed in the order of the components in aquiferWaterPhaseComponentNames. This parameter is
ignored in single-phase flow simulations.
• aquiferTotalCompressibility: the aquifer total compressibility (for the fluid and the solid) 𝑐𝐴
𝑡 (in 1/Pa).

• aquiferElevation: the elevation of the aquifer (in m).

• aquiferThickness: the thickness of the aquifer (in m).
• aquiferInnerRadius: the aquifer inner radius (in m).
• aquiferAngle: the angle subtended by the aquifer boundary from the center of reservoir (in degrees, must be
between 0 and 360).
• allowAllPhasesIntoAquifer: flag controlling the behavior of the aquifer when there is flow from the reservoir to
the aquifer. If the flag is equal to 1, all phases can flow into the aquifer. If the flag is equal to 0, only the water
phase can flow into the aquifer. The default value of this optional parameter is 0.
• pressureInfluenceFunctionName: the name of the table providing the dimensionless pressure as a function of
dimensionless time. This table must be defined as a TableFunction in the Functions block of the XML file. If
this optional parameter is omitted, a default pressure influence table is used.

510 Chapter 1. Table of Contents

GEOS Documentation

• setNames: the names of the face sets on which the aquifer boundary condition is applied.

ò Note

Following the GEOS convention, the z-coordinate is increasing upward. This convention must be taken into account
when providing the aquiferElevation. In other words, the z-value is not a depth.

The full list of parameters is provided below:

1.5. User Guide 511

GEOS Documentation

XML Element: Aquifer

Name Type Default Description

allowAllPhasesIn- integer 0
toAquifer
Flag to allow all phases to
flow into the aquifer.
This flag only matters for
the configuration in which
flow is from reservoir to
aquifer.
- If the flag is equal
to 1, then all
phases, including
non-aqueous
phases, are allowed
to flow into the
aquifer.
- If the flag is
equal to 0,
then only the
water phase
is allowed to
flow into the
aquifer.
If you are in a
configuration in which
flow is from reservoir to
aquifer and you expect
non-aqueous phases to
saturate the reservoir cells
next to the aquifer, set this
flag to 1.
This keyword is ignored
for single-phase flow
simulations

aquiferAngle real64 required Angle subtended by the

aquifer boundary from
the center of the reservoir
[degress]
aquiferElevation real64 required Aquifer elevation (positive
going upward) [m]
aquiferInitialPressure real64 required Aquifer initial pressure
[Pa]
aquiferInnerRadius real64 required Aquifer inner radius [m]
aquiferPermeability real64 required Aquifer permeability
[m^2]
aquiferPorosity real64 required Aquifer porosity
aquiferThickness real64 required Aquifer thickness [m]
aquiferTotalCompressibil- real64 required Aquifer total compress-
ity ibility (rock and fluid)
[Pa^-1]
aquiferWaterDensity real64 required Aquifer water density
512 [kg.m^-3]
Chapter 1. Table of Contents
aquiferWaterPhaseCom- real64_array {0} Aquifer water phase com-
ponentFraction ponent fraction. This key-
word is ignored for single-
GEOS Documentation

Examples

Setting up the Aquifer boundary condition requires two additional pieces of information in the XML input file: a set
of faces to specify where the aquifer boundary conditions will apply, and an aquifer tag that specifies the physical
characteristics of the aquifer and determines how the boundary condition is applied.
1) To specify a set of faces: on simple grids, in the Geometry block of the XML file, we can define a Box that
selects and assigns a name to a set of faces. To be included in a set, the faces must be fully enclosed in the Box
(all vertices of a face must be inside the box for the face to be included to the set). The name of this box is a
user-defined string, and it will be used in the aquifer tag to locate the face set. Here is an example of XML code
to create such a face set from a box:

ò Note

This step captures faces, not cells. For now, the user must ensure that the box actually contains faces (GEOS will
proceed even if the face set is empty).

For more complex meshes, sch as those imported using the VTKMesh, using a Box to perform a face selection is
challenging. We recommend using a surface in the vtk file instead, which will be used to locate the face set.
2) To specify the aquifer characteristics: in the FieldSpecifications block of the XML file, we include an Aquifer
tag. For single-phase flow, the aquifer definition looks like:

For compositional multiphase flow, the user must include additional parameters to specify the water composition. We
have additional influx controls over the aquifer with allowAllPhasesIntoAquifer. This is illustrated below for the
CO2-brine fluid model:

1.5. User Guide 513

GEOS Documentation

Finally, for both single-phase and multiphase flow, if a pressureInfluenceFunctionName attribute is specified in
the Aquifer tag, a TableFunction must be included in the Functions block of the XML file as follows:

<Functions>
...
<TableFunction
name="pressureInfluenceFunction"
coordinates="{ 0.01, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9,␣
˓→1.0, 1.5,

2.0, 2.5, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 15.0, 20.0, 25.0,␣
˓→30.0, 40.0,

50.0, 60.0, 70.0, 80.0, 90.0, 100.0, 200.0, 800.0, 1600.0, 3200.0,␣
˓→6400.0, 12800.0 }"

values="{ 0.112, 0.229, 0.315, 0.376, 0.424, 0.469, 0.503, 0.564, 0.616, 0.659, 0.
˓→702, 0.735, 0.772, 0.802,

0.927, 1.02, 1.101, 1.169, 1.275, 1.362, 1.436, 1.5, 1.556, 1.604, 1.651,␣
˓→1.829, 1.96, 2.067, 2.147,

2.282, 2.388, 2.476, 2.55, 2.615, 2.672, 2.723, 3.0537, 3.7468, 4.0934, 4.
˓→44, 4.7866, 5.1331 }"/>

...
</Functions>

ò Note

The values provided in the table above are the default values used internally in GEOS when the user does not specify
the pressure influence function in the XML file.

514 Chapter 1. Table of Contents

GEOS Documentation

1.5.7 Event Management

The goal of the GEOS event manager is to be flexible with regards to event type, application order, and method of
triggering. The event manager is configured via the Event block in an input .xml file, i.e.:

Event Execution Rules

The EventManager will repeatedly iterate through a list of candidate events specified via the Events block in the order
they are defined in the xml. When certain user-defined criteria are met, they will trigger and perform a task. The
simulation cycle denotes the number of times the primary event loop has completed, time denotes the simulation
time at the beginning of the loop, and dt denotes the global timestep during the loop.
During each cycle, the EventManager will do the following:
1. Loop through each event and obtain its timestep request by considering:
a. The maximum dt specified via the target’s GetTimestepRequest method
b. The time remaining until user-defined points (e.g. application start/stop times)
c. Any timestep overrides (e.g. user-defined maximum dt)
d. The timestep request for any of its children
2. Set the cycle dt to the smallest value requested by any event
3. Loop through each event and:
a. Calculate the event forecast, which is defined as the expected number of cycles until the event is expected
to execute.
b. if (forecast == 1) the event will signal its target to prepare to execute. This is useful for preparing
time-consuming I/O operations.
c. if (forecast <= 0) the event will call the Execute method on its target object
4. Check to see if the EventManager exit criteria have been met
After exiting the main event loop, the EventManager will call the Cleanup method for each of its children (to produce
final plots, etc.). Note: if the code is resuming from a restart file, the EventManager will pick up exactly where it left
off in the execution loop.

fault
beginTime real64 0 Start time of this event.
endTime real64 1e+100 End time of this event.
finalDt- real64 0.001 Allow the final dt request for this event to grow by this percentage to match
Stretch the endTime exactly.
forceDt real64 -1 While active, this event will request this timestep value (ignoring any chil-
dren/targets requests).
logLevel integer 0 Log level
maxEventDt real64 -1 While active, this event will request a timestep <= this value (depending upon
any child/target requests).
maxRuntime real64 re- The maximum allowable runtime for the job.
quired
name group- re- A name is required for any non-unique nodes
Name quired
target group- Name of the object to be executed when the event criteria are met.
NameRef
targetExact- integer 1 If this option is set, the event will reduce its timestep requests to match any
StartStop specified beginTime/endTimes exactly.
HaltEvent node XML Element: HaltEvent
Peri- node XML Element: PeriodicEvent
odicEvent
SoloEvent node XML Element: SoloEvent

Other Event Features

Event Progress Indicator

Because the event manager allows the user to specify the order of events, it could introduce ambiguity into the times-
tamps of output files. To resolve this, we pass two arguments to the target’s Execute method:
1. eventCounter (integer) - the application index for the event (or sub-event)
2. eventProgress (real64) - the percent completion of the event loop, paying attention to events whose targets are
associated with physics (from the start of the event, indicated via target->GetTimestepBehavior())
For example, consider the following Events block:

1.5. User Guide 519

GEOS Documentation

In this case, the events solverApplications_a and solverApplications_b point target physics events. The eventCounter,
eventProgress pairs will be: outputs (0, 0.0), solverApplications_a (1, 0.0), solverApplications_b (2, 0.5), and restarts
(3, 1.0). These values are supplied to the target events via their Execute methods for use. For example, for the name of
a silo output file will have the format: “%s_%06d%02d” % (name, cycle, eventCounter), and the time listed in the file
will be time = time + dt*eventProgress

Nested Events

The event manager allows its child events to be nested. If this feature is used, then the manager follows the basic
execution rules, with the following exception: When its criteria are met, an event will first execute its (optional) target.
It will then estimate the forecast for its own sub-events, and execute them following the same rules as in the main loop.
For example:

In this example, event_a will trigger during every cycle and call the Execute method on the object located at
/path/to/target_a. Because it is time-driven, event_b will execute every 100 s. When this occurs, it will execute it
will execute its own target (if it were defined), and then execute subevent_b_1 and subevent_b_2 in order. Note: these
are both cycle-driven events which, by default would occur every cycle. However, they will not execute until each of
their parents, grandparents, etc. execution criteria are met as well.

1.5.8 Tasks Manager

Name Type Default Description

coordinateFiles path_array {} List of coordinate file
names for ND Table
coordinates real64_array {0} Coordinates inputs for 1D
tables
inputVarNames groupNameRef_array {} Name of fields are input to
function.
interpolation geos_TableFunction_InterpolationType
linear
Interpolation method.
Valid options:
* linear
* nearest
* upper
* lower

name groupName required A name is required for any

non-unique nodes
values real64_array {0} Values for 1D tables
voxelFile path Voxel file name for ND Ta-
ble

1D Table

For 1D tables, the function may be defined using the coordinates and values attributes. These represent the location of
the grid nodes (ordered from smallest to largest) and the function values at those points, respectively. For example, the
following function defines a simple ramp function with a rise-time of 60 seconds:

ND Table

For ND tables, the grid coordinates and values may be defined using a set of .csv files. The coordinateFiles attribute
specifies the file names that define the coordinates for each axis. The values in each coordinate file must be comma-
delimited and ordered from smallest to largest. The dimensionality of the table is defined by the number of coordinate
files (coordinateFiles=”x.csv” would indicate a 1D table, coordinateFiles=”x.csv y.csv z.csv t.csv” would indicate a
4D table, etc.). The voxelFile attribute specifies name of the file that defines the value of the function at each point
along the grid. These values must be comma-delimited (line-breaks are allowed) and be specified in Fortran order, i.e.,
column-major order (where the index of the first dimension changes the fastest, and the index of the last dimension
changes slowest).
The following would define a simple 2D function c = a + 2*b:

1.5. User Guide 523

GEOS Documentation

• a.csv: “0, 1”
• b.csv: “0, 0.5, 1”
• c.csv: “0, 1, 1, 2, 2, 3”

Interpolation Methods

There are four interpolation methods available for table functions. Within the table axes, these will return a value:
• linear: using piecewise-linear interpolation
• upper: equal to the value of the next table vertex
• nearest: equal to the value of the nearest table vertex
• lower: equal to the value of the previous table vertex
Outside of the table axes, these functions will return the edge-values. The following figure illustrates how each of these
methods work along a single dimension, given identical table values:

524 Chapter 1. Table of Contents

GEOS Documentation

Table Generation Example

The following is an example of how to generate the above tables in Python:

import numpy as np

# Define table axes

a = np.array([0.0, 1.0])
b = np.array([0.0, 0.5, 1.0])

# Generate table values (note: the indexing argument is important)

A, B = np.meshgrid(a, b, indexing='ij')
C = A + 2.0*B

# Write axes, value files

np.savetxt('a.csv', a, fmt='%1.2f ', delimiter=',')
np.savetxt('b.csv', b, fmt='%1.2f ', delimiter=',')
values = np.reshape(C, (-1), order='F')
np.savetxt('c.csv', values, fmt='%1.2f ', delimiter=',')

1.5. User Guide 525

GEOS Documentation

SymbolicFunction

This function leverages the symbolic expression library mathpresso to define and evaluate functions. These functions
are processed using an x86-64 JIT compiler, so are nearly as efficient as natively compiled C++ expressions.

Name Type De- Description

fault
expression string re- Symbolic math expression
quired
inputVar- group- {} Name of fields are input to function.
Names NameRef_array
name groupName re- A name is required for any non-unique nodes
quired
variable- group- re- List of variables in expression. The order must match the evaluate
Names NameRef_array quired argument

The variableNames attribute defines a set of single-character names for the inputs to the symbolic function.
There should be a definition for each scalar input and for each component of a vector input. For example
if inputVarName="time, ReferencePosition", then variableNames="t, x, y, z". The expression at-
tribute defines the symbolic expression to be executed. Aside from the following exceptions, the syntax mirrors python:
• The function string cannot contain any spaces
• The power operator is specified using the C-style expression (e.g. pow(x,3) instead of x**3)
The following would define a simple 2D function c = a + 2*b:

CompositeFunction

This function is derived from the symbolic function. However, instead of using the time or object as inputs, it is used
to combine the outputs of other functions using a symbolic expression.

Name Type De- Description

fault
expression string Composite math expression
function- string_array {} List of source functions. The order must match the variableNames
Names argument.
inputVar- group- {} Name of fields are input to function.
Names NameRef_array
name groupName re- A name is required for any non-unique nodes
quired
variable- group- {} List of variables in expression
Names NameRef_array

The functionNames attribute defines the set of input functions to use (these may be of any type, and may each have
any number of inputs). The variableNames attribute defines a set of single-character names for each function. The
expression attribute defines the symbolic expression, and follows the same rules as above. The inputVarNames
attribute is ignored for this function type.

526 Chapter 1. Table of Contents

GEOS Documentation

The following would define a simple 1D table function f(t) = 1 + t, a 3D symbolic function g(x, y, z) = x**2
+ y**2 + z**2, and a 4D composite function h = sin(f(t)) + g(x, y, z):

1.5.10 Poromechanical Models Intialization

This section demonstrates the intializaton of poromechanical models in GEOS.

Model Initialization: Hydrostatic and Mechanical Equilibrium

Context
Prior to simulating underground operations, it is necessary to run a few steps of a fully coupled geomechanical sim-
ulation to reach the equilibrium state. In this example, we perform a gravity-only stress initialization for a reservoir
with a hydrostatic in-situ pressure. The problem is solved using a single-phase poromechanics solver (see Poromechan-
ics Solver) and the HydrostaticEquilibrium initialization procedure (see Hydrostatic Equilibrium Initial Condition) in
GEOS to predict the initial state of stress with depth in the reservoir, subject to the reservoir rock properties and the
prevailing hydrostatic pressure condition. This way, the poromechanical model is initialized at mechanical equilibrium
and all displacements are set to zero after initialization. We verify numerical results obtained by GEOS against an
analytical equation (Eaton’s equation).
Input file
The xml input files for the test case are located at:

inputFiles/initialization/gravityInducedStress_initialization_base.xml
inputFiles/initialization/gravityInducedStress_initialization_benchmark.xml

A Python script for post-processing the simulation results is provided:

src/coreComponents/physicsSolvers/multiphysics/docs/gravityInducedStressInitialization/
˓→gravityInitializationFigure.py

Description of the Case

We model the in-situ state of stress of a subsurface reservoir subject to a gravity-only induced stress and hydrostatic in-
situ pressure condition. The domain is homogenous, isotropic and isothermal. The domain is subject to roller boundary
conditions on lateral surfaces and at the base of the model, while the top of the model is a free surface.

1.5. User Guide 527

GEOS Documentation

Fig. 1.89: Sketch of the problem

528 Chapter 1. Table of Contents

GEOS Documentation

We set up and solve a PoroMechanics model to obtain the gradient of total stresses (principal stress components) across
the domain due to gravity effects and hydrostatic pressure only. These numerical predictions are compared with the
analytical solutions derived from Eaton et al. (1969, 1975)
For this example, we focus on the Mesh, the Constitutive, and the FieldSpecifications tags.

Mesh

The following figure shows the mesh used for solving this poromechanical problem:

Fig. 1.90: Generated mesh

The mesh was created with the internal mesh generator and parametrized in the InternalMesh XML tag. It con-
tains 20x20x40 eight-node brick elements in the x, y, and z directions respectively. Such eight-node hexahedral ele-
ments are defined as C3D8 elementTypes, and their collection forms a mesh with one group of cell blocks named here
cellBlockNames.

<Mesh>
<InternalMesh
name="mesh1"
elementTypes="{ C3D8 }"
xCoords="{ 0.0, 1000 }"
yCoords="{ 0.0, 1000 }"
zCoords="{ -1000, 0 }"
(continues on next page)

1.5. User Guide 529

GEOS Documentation

(continued from previous page)

nx="{ 20 }"
ny="{ 20 }"
nz="{ 40 }"
cellBlockNames="{ cb1 }" />
</Mesh>

Poro-Mechanics Solver

For the initialization test, a hydrostatic pore pressure is imposed on the system. This is done using the Hydrostatic
Equilibrium tag under Field Specifications. We then define a poro-mechanics solver called here poroSolve. This solid
mechanics solver (see Solid Mechanics Solver) called lagSolve is based on the Lagrangian finite element formulation.
The problem is run as QuasiStatic without considering inertial effects. The computational domain is discretized by
FE1, defined in the NumericalMethods section. We use the targetRegions attribute to define the regions where
the poromechanics solver is applied. Since we only have one cellBlockName type called Domain, the poromechanics
solver is applied to every element of the model. The flow solver for this problem (see Singlephase Flow Solver) called
SinglePhaseFlow is discretized by fluidTPFA, defined in the NumericalMethods section.

Constitutive Laws

A homogeneous domain with one solid material is assumed, and its mechanical and fluid properties are specified in
the Constitutive section:

530 Chapter 1. Table of Contents

GEOS Documentation

As shown above, in the CellElementRegion section, rock is the solid material in the computational domain and
water is the fluid material. Here, Porous Elastic Isotropic model PorousElasticIsotropic is used to simulate
the elastic behavior of rock. As for the solid material parameters, defaultDensity, defaultPoissonRatio,
defaultYoungModulus, grainBulkModulus, defaultReferencePorosity, and permeabilityComponents de-
note the rock density, Poisson ratio, Young modulus, grain bulk modulus, porosity, and permeability components re-
spectively. In additon, the fluid property (water) of density, viscosity, compressibility and viscosibility are specified
with defaultDensity, defaultViscosity, compressibility, and viscosibility. All properties are specified
in the International System of Units.

Stress Initialization Function

In the Tasks section, SinglePhasePoromechanicsInitialization tasks are defined to initialize the model by
calling the poro-mechanics solver poroSolve. This task is used to determine stress gradients through designated den-
sities and established constitutive relationships to maintain mechanical equilibrium and reset all initial displacements
to zero following the initialization process.

<Tasks>
<SinglePhasePoromechanicsInitialization
logLevel="1"
name="singlephasePoromechanicsPreEquilibrationStep"
(continues on next page)

1.5. User Guide 531

GEOS Documentation

(continued from previous page)

poromechanicsSolverName="poroSolve" />
</Tasks>

The initialization is triggered into action using the Event management section, where the soloEvent function calls
the task at the target time (in this case -1e10s).

</Events>

The PeriodicEvent function is used here to define recurring tasks that progress for a stipulated time during the
simuation. We also use it in this example to save the vtkOuput results.

We use Paraview to extract the data from the vtkOutput files at the initialization time, and then use a Python script to
read and plot the stress and pressure gradients for verification and visualization.

Initial and Boundary Conditions

The next step is to specify fields, including:

• The initial value (hydrostatic equilibrium),
• The boundary conditions (the displacement control of the outer boundaries have to be set).
In this problem, all outer boundaries of the domain are subject to roller constraints except the top of the model, left as
a free surface.
These boundary conditions are set up through the FieldSpecifications section.

532 Chapter 1. Table of Contents

GEOS Documentation

</FieldSpecifications>

The parameters used in the simulation are summarized in the following table.

Symbol Parameter Unit Value

𝐸 Young Modulus [MPa] 100
𝑣 Poisson Ratio [-] 0.25
𝜌𝑏 Bulk Density [kg/m3 ] 2500
𝜑 Porosity [-] 0.375
𝐾𝑠 Grain Bulk Modulus [Pa] 1027
𝜅 Permeability [m2 ] 10-12
𝜌𝑓 Fluid Density [kg/m3 ] 1000
𝑐𝑓 Fluid compressibility [Pa-1 ] 4.4x10-10
𝜇 Fluid viscosity [Pa s] 10-3

Inspecting Results

In the example, we request vtk output files for time-series (time history). We use paraview to visualize the outcome at the
time 0s. The following figure shows the final gradient of pressure and of the effective vertical stress after initialization
is completed.

1.5. User Guide 533

GEOS Documentation

Fig. 1.91: Simulation result of pressure

The figure below shows the comparison between the total stress computed by GEOS(marks) and with an analytical
solutions (solid lines). Note that, because of the use of an isotropic model, the minimum and maximul horizontal
stresses are equal.

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

Model Initialization: User Defined Tables

Context
This example uses the same reservoir model as the gravity-induced hydrostatic stress initialization case (see Model
Initialization: Hydrostatic and Mechanical Equilibrium). Instead of using the gravity based equilibrium initialization
procedure, we collect the interpretated stress and pore pressure gradients for a reservoir and then request the simulator
to perform an initialization with the provided pressure and stresses in every element in the model. The problem is
solved by using the single-phase poromechanics solver (see Poromechanics Solver) in GEOS.
Input file
The xml input files for the test case are located at:

inputFiles/initialization/userdefinedStress_initialization_base.xml
inputFiles/initialization/userdefinedStress_initialization_benchmark.xml

This example also uses a set of table files located at:

534 Chapter 1. Table of Contents

GEOS Documentation

Fig. 1.92: Simulation result of effective vertical stress

1.5. User Guide 535

GEOS Documentation

0 Sxx_Total_GEOS
Sxx_Total_Analytical
Syy_Total_GEOS
Szz_Total_GEOS
Szz_Total_Analytical
Pore Pressure_GEOS
200 Pore Pressure_Analytical

400
Depth [m]

600

800

1000
0.0 2.5 5.0 7.5 10.0 12.5 15.0 17.5
Total Stresses [MPa]

536 Chapter 1. Table of Contents

GEOS Documentation

inputFiles/initialization/userTables/

Last, a Python script for post-processing the results is provided:

src/coreComponents/physicsSolvers/multiphysics/docs/userTableStressInitialization/
˓→tableInitializationFigure.py

Stress Initialization Table Functions

The major distinction between this “user-defined” initialization and the “gravity-based” initialization is that in the user-
defined case, the user provides the following additional information:
• The distribution of effective stresses and pore pressure across the domain, with their gradients assumed constant
along the depth in this example. We use a table function (see Functions) to specify pressure and stress conditions
throughout the area.
This is shown in the following tags under the FieldSpecifications section below
<FieldSpecification
component="0"
fieldName="rockSolid_stress"
functionName="sigma_xx"
initialCondition="1"
name="init_sigma_xx"
objectPath="ElementRegions/Domain"
scale="1.0"
setNames="{ all }" />

<FieldSpecification
fieldName="pressure"
functionName="init_pressure"
initialCondition="1"
name="init_pressure"
objectPath="ElementRegions/Domain"
(continues on next page)

1.5. User Guide 537

GEOS Documentation

(continued from previous page)

scale="1.0"
setNames="{ all }" />

The tables for sigma_xx, sigma_yy, sigma_zz and init_pressure are listed under the Functions section as shown
below.

The required input files: x.csv, y.csv, z.csv, effectiveSigma_xx.csv, effectiveSigma_yy.csv, effectiveSigma_zz.csv, and
porePressure.csv are generated based on the expected stress-gradients in the model.
A Python script to generate these files is provided:

src/coreComponents/physicsSolvers/multiphysics/docs/userTableStressInitialization/
˓→genetrateTable.py

In addition to generating the files listed above, the script prints out the corresponding fluid density and rock density
based on the model parameters provided. These values are then input into the defaultDensity parameter of the
CompressibleSinglePhaseFluid and ElasticIsotropic tags respectively, as shown below:

<ElasticIsotropic
name="rockSolid"
defaultDensity="3302.752294"
defaultPoissonRatio="0.25"
(continues on next page)

538 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

defaultYoungModulus="100.0e6" />

Inspecting Results

Fig. 1.93: Simulation result of pressure

The figure below shows the comparisons between the numerical predictions (marks) and the corresponding user-
provided stress gradients. Note that anisotropic horizontal stresses are obtained through this intialization procedure;
however, mechanical equilibrium might not be guaranteed, especially for the heterogeneous models.

1.5. User Guide 539

GEOS Documentation

Fig. 1.94: Simulation result of effective vertical stress

To go further

Feedback on this example

For any feedback on this example, please submit a GitHub issue on the project’s GitHub page.

1.5.11 Linear Solvers

Introduction
Any physics solver relying on standard finite element and finite volume techniques requires the solution of algebraic
linear systems, which are obtained upon linearization and discretization of the governing equations, of the form:

Ax = b

where A is the square sparse matrix, x the solution vector, and b the right-hand side. For example, in a classical linear
elastostatics problem A is the stiffness matrix, and x and b are the displacement and nodal force vectors, respectively.
This solution stage represents the most computationally expensive portion of a typical simulation. Solution algorithms
generally belong to two families of methods: direct methods and iterative methods. In GEOS both options are made
available wrapping around well-established open-source linear algebra libraries, namely HYPRE, PETSc, SuperLU,
and Trilinos.

Direct methods
The major advantages are their reliability, robustness, and ease of use. However, they have large memory requirements
and exhibit poor scalability. Direct methods should be used in a prototyping stage, for example when developing a new
formulation or algorithm, when the dimension of the problem, namely the size of matrix A, is small. Irrespective of
the selected direct solver implementation, three stages can be idenitified:

540 Chapter 1. Table of Contents

GEOS Documentation

0 Sxx_Total_GEOS
Sxx_Total_Reference
Syy_Total_GEOS
Syy_Total_Reference
Szz_Total_GEOS
Szz_Total_Reference
200 Pore Pressure_GEOS
Pore Pressure_Reference

400
Depth [m]

600

800

1000
0 5 10 15 20 25
Total Stresses [MPa]

1.5. User Guide 541

GEOS Documentation

(1) Setup Stage: the matrix is first analyzed and then factorized
(2) Solve Stage: the solution to the linear systems involving the factorized matrix is computed
(3) Finalize Stage: the systems involving the factorized matrix have been solved and the direct solver lifetime ends
The default option in GEOS relies on SuperLU, a general purpose library for the direct solution of large, sparse,
nonsymmetric systems of linear equations, that is called taking advantage of the interface provided in HYPRE.

Iterative methods
As the problem size (number of computational cells) increases, global iterative solution strategies are the method of
choice—typically nonsymmetric Krylov solvers. Because of the possible poor conditioning of A, preconditioning is
essential to solve such systems efficiently. ‘’Preconditioning is simply a means of transforming the original linear
system into one which has the same solution, but which is likely to be easier to solve with an iterative solver” [Saad
(2003)].
The design of a robust and efficient preconditioner is based on a trade-off between two competing objectives:
• Robustness: reducing the number of iterations needed by the preconditioned solver to achieve convergence;
• Efficiency: limiting the time required to construct and apply the preconditioner.
Assuming a preconditioning matrix M is available, three standard approaches are used to apply the preconditioner:
(1) Left preconditioning: the preconditioned system is M−1 Ax = M−1 b
(2) Right preconditioning: the preconditioned system is AM−1 y = b, with x = M−1 y
(3) Split preconditioning: the preconditioned system is M−1 −1 −1 −1
𝐿 AM𝑅 y = M𝐿 b, with x = M𝑅 y

Summary
The following table summarizes the available input parameters for the linear solver.

XML Element: LinearSolverParameters

Name Type Default Description

542 Chapter 1. Table of Contents

GEOS Documentation

Table 1.2 – continued from previous page

• ILUT: a dual threshold incomplete LU factorization: M−1 = U−1 L−1 . Further details can be found in:
– HYPRE documentation,
– not yet available through PETSc interface,
– Trilinos documentation.
• ICC: incomplete Cholesky factorization of a symmetric positive definite matrix: M−1 = L−𝑇 L−1 . Further
details can be found in:
– not yet available through hypre interface,
– PETSc documentation,
– Trilinos documentation.
• AMG: algebraic multigrid (can be classical or aggregation-based according to the specific package). Further
details can be found in:
– HYPRE documentation,
– PETSc documentation,
– Trilinos documentation.
• MGR: multigrid reduction. Available through hypre interface only. Further details can be found in MGR docu-
mentation, also see section below.
• Block: custom preconditioner designed for a 2 x 2 block matrix.

HYPRE MGR Preconditioner

MGR stands for multigrid reduction, a multigrid method that uses the interpolation, restriction operators, and the
Galerkin triple product, to reduce a linear system to a smaller one, similar to a Schur complement approach. As
such, it is designed to target block linear systems resulting from discretizations of multiphysics problems. GEOS
uses MGR through an implementation in HYPRE. More information regarding MGR can be found here. Currently,
MGR strategies are implemented for hydraulic fracturing, singlephase and multiphase poromechanics, singlephase
poromechanics with fractures, compositional flow with and without wells. More multiphysics solvers with MGR will
be enabled in the future.
To use MGR for a specific block system, several components need to be specified.
(1) The number of reduction levels and the coarse points (corresponding to fields) for each level. For example,
for single-phase hydraulic fracturing, there are two fields, i.e. displacement and fluid pressure, a two-level MGR
strategy can be used with the fluid pressure being the coarse degrees of freedom.
(2) Interpolation/restriction operators and the coarse-grid computation strategy. A simple but effective strat-
egy is to use Jacobi diagonalization for interpolation and injection for restriction. For most cases, a Galerkin
coarse grid strategy can be used, but for special cases such as poroelastic, a non-Galerkin approach is preferable.
(3) Global smoother. Depending on the problem, a global relaxation step could be beneficial. Some options include
ILU(k), (block) Jacobi, (block) Gauss-Seidel.
(4) Solvers for F-relaxation and coarse-grid correction. These solvers should be chosen carefully for MGR to
be effective. The choice of these solvers should correspond to the properties of the blocks specified by the C-
and F-points. For example, if the A𝐹 𝐹 block is hyperbolic, a Jacobi smoother is sufficient while for an elliptic
operator an AMG V-cycle might be required. For the single-phase hydraulic fracturing case, an AMG V-cycle
is needed for both F-relaxation and coarse-grid correction.
Note that these are only general guidelines for designing a working MGR recipe. For complicated multiphysics prob-
lems, experimentation with different numbers of levels, choices of C- and F-points, and smoothers/solvers, etc., is
typically needed to find the best strategy. Currently, these options are only available to developers. We are working on
exposing these functionalities to the users in future releases.

546 Chapter 1. Table of Contents

GEOS Documentation

Block preconditioner
This framework allows the user to design a block preconditioner for a 2 x 2 block matrix. The key component is the
Schur complement S = A11 −A10 A ̃︀ −1 A01 computation, that requires an approximation of the leading block. Currently,
00
−1
available options for A
̃︀ are:
00

• diagonal with diagonal values (essentially, a Jacobi preconditioner);

• diagonal with row sums as values (e.g., used for CPR-like preconditioners).
Once the Schur complement is computed, to properly define the block preconditioner we need:
• the preconditioner for A00 (any of the above listed single-matrix preconditioner);
• the preconditioner for S (any of the above listed single-matrix preconditioner);
• the application strategy. This can be:
– diagonal: none of the coupling terms is used;
– upper triangular: only the upper triangular coupling term is used;
– lower-upper triangular: both coupling terms are used.
Moreover, a block scaling is available. Feasible options are:
• none: keep the original scaling;
• Frobenius norm: equilibrate Frobenius norm of the diagonal blocks;
• user provided.

Adaptive tolerance
This feature is available for iterative solvers and can be enabled using krylovAdaptiveTol flag in LinearSolverParameters.
It follows the Eisenstat-Walker inexact Newton approach described in [Eisenstat and Walker 1996]. The key idea is to
relax the linear solver tolerance at the beginning of the nonlinear iterations loop and tighten it when getting closer to
the final solution. The initial tolerance is defined by krylovWeakestTol and starting from second nonlinear iteration the
tolerance is chosen using the following steps:
• compute the current to previous nonlinear norm ratio: nr = min(norm𝑐𝑢𝑟𝑟 /norm𝑝𝑟𝑒𝑣 , 1.0)
• estimate the new linear solver tolerance: tol𝑛𝑒𝑤 = 𝛾 · nr𝑎𝑥
• compute a safeguard to avoid too sharp tolerance reduction: tol𝑎𝑙𝑡 = tol2𝑜𝑙𝑑 (the bound is the quadratic reduction
with respect to the previous tolerance value)
• apply safeguards and compute the final tolerance: tol = max(tol𝑛𝑒𝑤 , tol𝑎𝑙𝑡 ), tol =
min(tol𝑚𝑎𝑥 , max(tol𝑚𝑖𝑛 , tol))
Here 𝛾 is the forcing term, 𝑎𝑥 is the adaptivity exponent, tol𝑚𝑖𝑛 and tol𝑚𝑎𝑥 are prescribed tolerance bounds (defined
by krylovStrongestTol and krylovWeakestTol, respectively).

1.5.12 Numerical Methods

This section describes the specification of numerical methods used by solvers.

1.5.13 XML Element: NumericalMethods

Name Type Default Description

FiniteElements node unique XML Element: FiniteElements
FiniteVolume node unique XML Element: FiniteVolume

1.5. User Guide 547

GEOS Documentation

Finite Element Discretization

We are currently refactoring the finite element infrastructure, and will update the documentation soon to reflect the new
structure.

Finite Volume Discretization

Two different finite-volume discretizations are available to simulate single-phase flow in GEOSX, namely, a standard
cell-centered TPFA approach, and a hybrid finite-volume scheme relying on both cell-centered and face-centered de-
grees of freedom. The key difference between these two approaches is the computation of the flux, as detailed below.

Standard cell-centered TPFA FVM

This is the standard scheme implemented in the SinglePhaseFVM flow solver. It only uses cell-centered degrees of
freedom and implements a Two-Point Flux Approximation (TPFA) for the computation of the flux. The numerical flux
is obtained using the following expression for the mass flux between cells 𝐾 and 𝐿:
𝜌𝑢𝑝𝑤 (︀
𝑝𝐾 − 𝑝𝐿 − 𝜌𝑎𝑣𝑔 𝑔(𝑑𝐾 − 𝑑𝐿 ) ,
)︀
𝐹𝐾𝐿 = Υ𝐾𝐿 𝑢𝑝𝑤
𝜇
where 𝑝𝐾 is the pressure of cell 𝐾, 𝑑𝐾 is the depth of cell 𝐾, and Υ𝐾𝐿 is the standard TPFA transmissibility coefficient
at the interface. The fluid density, 𝜌𝑢𝑝𝑤 , and the fluid viscosity, 𝜇𝑢𝑝𝑤 , are upwinded using the sign of the potential
difference at the interface.
This is currently the only available discretization in the Compositional Multiphase Flow Solver.

Hybrid FVM

This discretization scheme overcomes the limitations of the standard TPFA on non K-orthogonal meshes. The hybrid
finite-volume scheme–equivalent to the well-known hybrid Mimetic Finite Difference (MFD) scheme–remains consis-
tent with the pressure equation even when the mesh does not satisfy the K-orthogonality condition. This numerical
scheme is currently implemented in the SinglePhaseHybridFVM solver.
The hybrid FVM scheme uses both cell-centered and face-centered pressure degrees of freedom. The one-sided face
flux, 𝐹𝐾,𝑓 , at face 𝑓 of cell 𝐾 is computed as:

𝜌𝑢𝑝𝑤 ̃︀
𝐹𝐾,𝑓 = 𝐹𝐾,𝑓 ,
𝜇𝑢𝑝𝑤

where 𝐹̃︀𝐾,𝑓 reads:

∑︁ (︀ )︀
𝐹̃︀𝐾,𝑓 = Υ𝑓 𝑓 ′ 𝑝𝐾 − 𝜋𝑓 − 𝜌𝐾 𝑔(𝑑𝐾 − 𝑑𝑓 ) .
𝑓′

In the previous equation, 𝑝𝐾 is the cell-centered pressure, 𝜋𝑓 is the face-centered pressure, 𝑑𝐾 is the depth of cell 𝐾,
and 𝑑𝑓 is the depth of face 𝑓 . The fluid density, 𝜌𝑢𝑝𝑤 , and the fluid viscosity, 𝜇𝑢𝑝𝑤 , are upwinded using the sign of
𝐹̃︀𝐾,𝑓 . The local transmissibility Υ of size 𝑛local faces × 𝑛local faces satisfies:

𝑁 𝐾 = Υ𝐶

Above, 𝑁 is a matrix of size 𝑛local faces × 3 storing the normal vectors to each face in this cell, 𝐶 is a matrix of size
𝑛local faces × 3 storing the vectors from the cell center to the face centers, and 𝐾 is the permeability tensor. The local
transmissibility matrix, Υ, is currently computed using the quasi-TPFA approach described in Chapter 6 of this book.
The scheme reduces to the TPFA discretization on K-orthogonal meshes but remains consistent when the mesh does
not satisfy this property. The mass flux 𝐹𝐾,𝑓 written above is then added to the mass conservation equation of cell 𝐾.

548 Chapter 1. Table of Contents

GEOS Documentation

In addition to the mass conservation equations, the hybrid FVM involves algebraic constraints at each mesh face to
enforce mass conservation. For a given interior face 𝑓 between two neighboring cells 𝐾 and 𝐿, the algebraic constraint
reads:

𝐹̃︀𝐾,𝑓 + 𝐹̃︀𝐿,𝑓 = 0.

We obtain a numerical scheme with 𝑛cells cell-centered degrees of freedom and 𝑛faces face-centered pressure degrees of
freedom. The system involves 𝑛cells mass conservation equations and 𝑛faces face-based constraints. The linear systems
can be efficiently solved using the MultiGrid Reduction (MGR) preconditioner implemented in the Hypre linear algebra
package.
The implementation of the hybrid FVM scheme for Compositional Multiphase Flow Solver is in progress.

1.5.14 Parallel Partitioning

Parallel GEOS simulations involves multiple partitions and there are ghost objects in each partition. Users need
to understand these concepts to effectively design models and visualize results.

Partition and ghosting : simple examples

A model, or more strictly, a computational domain, is stored in a distributed fashion among many processors. In the
following simple example, the computational domain has 10 cells and the simulation involves two processors. The first
processor, “partition 0” (“0” is called the “rank” of the processor) owns the first five cells (0 to 4) while “partition 1”
owns 5 to 9. When the whole domain is divided into partitions, each partition will number the cells and other objects
such as nodes, faces, and edges in the partition . Therefore, in both partitions, the cells IDs start from zero. Element
0 in partition 1 is cell 5 (or the sixthc cell) of the original domain. In parallel computing, each partition does not only
need to know information about its own cells, but it also needs to know information about some cells owned by the
neighbor partitions if these cells are directly connected to objects in this partition. For example, cell 0 in partition 1
(i.e. cell 5 in the original whole domain) is connected to cell 4 in partition 0. Therefore, partition 0 will keep a copy of
this cell (including the data associated with this cell) which is synchronized with the corresponding information in the
partition that actually owns this cell.
In summary, a partition owns a number of cells and other objects (e.g. faces) and also keeps copies of objects from
neighbor partitions. Partitioning is automatically handled by GEOS once the user specifies how the domain should be
divided.
The following figure show the partitioning of a simple mesh. Real nodes appear as solid red circles in the owning
partition and ghost nodes are shown as hollow circles.

This concept of ghosting and communications between owned cells and ghost cells can also be applied to the other
types of elements in GEOS (Faces, Edges, Nodes). The next figure summarizes the way nodes, edges, faces and cells
are ghosted.

Specifying partitioning pattern

Cartesian partitioning

In the command line to run GEOS, the user can specify the partitioning pattern by adding the following switches:
• -x, --x-partitions - Number of partitions in the x-direction
• -y, --y-partitions - Number of partitions in the y-direction
• -z, --z-partitions - Number of partitions in the z-direction

1.5. User Guide 549

GEOS Documentation

Graph-based partitioning

The Graph-based partitioning is used only when importing exernal meshes using the VTKMesh (see Tutorial 3: Regions
and Property Specifications section for more details using external meshes). While importing themesh, vtk computes
the graph of connectivity between all the volume elements of the mesh. The partitioning is then done using whether
a KD-tree or the PTSCOTCH, METIS, PARMETIS libraries. The graph is not weighted so the expected result is as
mesh divided in n parts, with n being the number of MPI ranks used for simulation containing a similar amount of
cells.

Ghost ranks
Each object (node, edge, face, or cell) has a ghost rank attribute, stored in the ghostRank field. If a object does
not appear in any other partition as a ghost, its ghost rank is a large negative number, -2.14e9 in a typical system. If
a object is real (owned by the current partition) but exists in other partitions as ghosts, its ghost rank is -1. The ghost
rank of a ghost object is the rank of the partition that owns the corresponding real object.

Considerations for visualization

In VisIt, a partition is called a domain. The ID of a domain is the rank of the corresponding partition in GEOS plus
one. VisIt would display all elements/objects regardless if they are real or ghosts. As information about a ghost is
synchronized with the real object, VisIt just overlaying the same images on top of each other. The user would not
perceive the overlapping between partitions unless the models are shown as semi-transparent entities. Note that if
ghosts are not hidden, results from a query operation, such as summation of variable values, would be wrong due to
double-counting. Therefore, it is a good practice or habit to hide ghost objects using ghostRank as a filter.
If the visualization method involves interpolation, such as interpolating a zonal field into a nodal field or generating
contours, the interpretation near partition boundaries is not accurate.

1.5.15 Outputs
This section describes how outputs are handled by GEOS
The outputs are defined in a <Outputs> XML block.
There are three available formats to output the results of a simulation: SILO, VTK, and Time History output into simple
dataset HDF5 files which are consumable by post-processing scripts..

Defining an output
SILO Output

The SILO output is defined through the <Silo> XML node (subnode of <Outputs> XML block) as shown here:

The parameter options are listed in the following table:

550 Chapter 1. Table of Contents

GEOS Documentation

XML Element: Silo

Name Type Default Description

childDirectory string Child directory path
fieldNames groupNameRef_array {} Names of the fields to out-
put. If this attribute is
specified, GEOSX outputs
all (and only) the fields
specified by the user, re-
gardless of their plotLevel
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Output timing
information

name groupName required A name is required for any

non-unique nodes
onlyPlotSpecifiedField- integer 0 If this flag is equal to 1,
Names then we only plot the fields
listed in fieldNames. Oth-
erwise, we plot all the
fields with the required
plotLevel, plus the fields
listed in fieldNames
parallelThreads integer 1 Number of plot files.
plotFileRoot string plot (no description available)
plotLevel integer 1 (no description available)
writeCellElementMesh integer 1 (no description available)
writeEdgeMesh integer 0 (no description available)
writeFEMFaces integer 0 (no description available)
writeFaceElementMesh integer 1 (no description available)

VTK Output

The VTK output is defined through the <VTK> XML node (subnode of <Outputs> XML block) as shown here:

The parameter options are listed in the following table:

1.5. User Guide 551

GEOS Documentation

XML Element: VTK

Name Type De- Description

fault
childDirec- string Child directory path
tory
fieldNames group- {} Names of the fields to output. If this attribute is specified, GEOS outputs all
NameRef_array the fields specified by the user, regardless of their plotLevel
format geos_vtk_VTKOutputMode
bi- Output data format. Valid options: binary, ascii
nary
levelNames string_array {} Names of mesh levels to output.
logLevel integer 0 Log level
name groupName re- A name is required for any non-unique nodes
quired
numberOf- integer 1 Number of output aggregate files to be written.
TargetPro-
cesses
onlyPlot- integer 0 If this flag is equal to 1, then we only plot the fields listed in fieldNames.
Specified- Otherwise, we plot all the fields with the required plotLevel, plus the fields
FieldNames listed in fieldNames
outputRe- geos_vtk_VTKRegionTypes
all Output region types. Valid options: cell, well, surface, particle, all
gionType
paral- integer 1 Number of plot files.
lelThreads
plotFileRoot string VTK Name of the root file for this output.
plotLevel integer 1 Level detail plot. Only fields with lower of equal plot level will be output.
writeFEM- integer 0 (no description available)
Faces
write- integer 0 Should the face elements be written as 3d volumes or not.
FaceEle-
mentsAs3D
writeGhost- integer 0 Should the vtk files contain the ghost cells or not.
Cells

TimeHistory Output

The TimeHistory output is defined through the <TimeHistory> XML node (subnode of <Outputs> XML block) as
shown here:

</Outputs>

The parameter options are listed in the following table:

552 Chapter 1. Table of Contents

GEOS Documentation

XML Element: TimeHistory

Name Type Default Description

childDirec- string Child directory path
tory
filename string TimeHis- The filename to which to write time history output.
tory
format string hdf The output file format for time history output.
logLevel integer 0 Log level
name groupName required A name is required for any non-unique nodes
paral- integer 1 Number of plot files.
lelThreads
sources group- required A list of collectors from which to collect and output time history
NameRef_array information.

In order to properly collect and output time history information the following steps must be accomplished:
1. Specify one or more collection tasks using the Tasks Manager.
2. Specify a TimeHistory Output using the collection task(s) as source(s).
3. Specify an event in the Event Management to trigger the collection task(s).
4. Specify an event in the Event Management to trigger the output.
Note: Currently if the collection and output events are triggered at the same simulation time, the one specified first will
also trigger first. Thus in order to output time history for the current time in this case, always specify the time history
collection events prior to the time history output events.

Triggering the outputs

The outputs can be triggered using the Event Management. It is recommended to use a <PeriodicEvent> to output
results with a defined frequency:

The keyword target has to match with the name of the <Silo>, <VTK>, or <TimeHistory> node.

Visualisation of the outputs

We suggest the use of VisIT, Paraview, and MatPlotLib to visualize the outputs.

Visualizing Silo outputs with VisIT

If the <Silo> XML node was defined, GEOS writes the results in a folder called siloFiles.
In VisIT :
1. File > Open file. . .
2. On the right panel, browse to the siloFiles folder.
3. On the left panel, select the file(s) you want to visualize. Usually, one file is written according the frequency
defined in the timeFrequency keyword of the Event that has triggered the output.

1.5. User Guide 553

GEOS Documentation

4. To load fields, use the “Add” button and browse to the fields you want to plot.
5. To plot fields, use the “Draw” button.
Please consult the VisIT documentation for further explanations on its usage.

Visualizing VTK outputs with VisIT

If the <VTK> XML node was defined, GEOS writes the results in a folder named after the plotFileRoot attribute
(default = vtkOutputs). For problems with multiple active regions (e.g. Hydraulic Fracturing), additional work may
be required to ensure that vtk files can be read by VisIt. Options include:
1. Using a VisIt macro / python script to convert default multi-region vtk files (see GEOS/src/coreComponents/
python/visitMacros/visitVTKConversion.py).
2. Using the outputRegionType attribute to output separate sets of files per region. For example:

In VisIt, the prepared files can be visualized as follows:

1. Click the Open icon (or select File/Open from the top menu).
2. Enter the vtk output folder in the left-hand panel (these will be separate if you use option 2 above).
3. Select the desired *.vtm group in the right-hand panel (by double-clicking or selecting OK).
4. (Repeat for any additional datasets/regions.)
5. In the main window, select the desired dataset from the Active Sources dropdown menu.
6. Click on the Add icon, and select a parameter to visualize from the mesh, psuedocolor, or vector plot options

554 Chapter 1. Table of Contents

GEOS Documentation

7. At some point you may be prompted to create a Database Correlation. If you select Yes, then VisIt will create a
new time slider, which can be used to change the time state while keeping the various aspects of the simulation
synchronized.
8. Finally, click the Draw button and use the time slider to visualize the output.
Please consult the VisIT documentation for further explanations on its usage.

Visualizing VTK outputs with Paraview

If the <VTK> XML node was defined, GEOS writes a folder and a .pvd file named after the string defined in name
keyword.
The .pvd file contains references to the .pvtu files. One .pvtu file is output according the frequency defined in the
timeFrequency keyword of the Event that has triggered the output.
One .pvtu contains references to .vtu files. There is as much .vtu file as there were MPI processes used for the
computation.
All these files can be opened with paraview. To have the whole results for every output time steps, you can open the
.pvd file.

Visualizing TimeHistory outputs with MatPlotLib

If the <TimeHistory> XML node was defined, GEOS writes a file named after the string defined in the filename
keyword and formatted as specified by the string defined in the format keyword (only HDF5 is currently supported).
The TimeHistory file contains the collected time history information from each specified time history collector. This
information includes datasets for the time itself, any metadata sets describing index association with specified collection
sets, and the time history information itself.
It is recommended to use MatPlotLib and format-specific accessors (like H5PY for HDF5) to access and easily plot the
time history datat.

1.5.16 pygeosx — GEOS in Python

GEOS can be manipulated and executed through a Python script.
High-level control of GEOS is managed through the top-level pygeosx functions, like initialize and run. GEOS’s
data can be manipulated by getting pylvarray views of LvArray objects living in GEOS’s data repository. These
pylvarray views are fetched by calling Wrapper.value() after getting a Wrapper out of the data repository.

. Warning

The pygeosx module provides plenty of opportunities to crash Python. See the Segmentation Faults section below.

Only Python 3 is supported.

Module Functions
pygeosx.initialize(rank, args)
Initialize GEOS for the first time, with a rank and command-line arguments.
This function should only be called once. To reinitialize, use the reinit function.
Generally the rank is obtained from the mpi4py module and the arguments are obtained from sys.argv.
Returns a Group representing the ProblemManager instance.

1.5. User Guide 555

GEOS Documentation

pygeosx.reinit(args)
Reinitialize GEOS with a new set of command-line arguments.
Returns a Group representing the ProblemManager instance.
pygeosx.apply_initial_conditions()
Apply the initial conditions.
pygeosx.finalize()
Finalize GEOS. After this no calls into pygeosx or to MPI are allowed.
pygeosx.run()
Enter the GEOS event loop.
Runs until hitting a breakpoint defined in the input deck, or until the simulation is complete.
Returns one of the state constants defined below.

GEOS State
pygeosx.UNINITIALIZED

pygeosx.INITIALIZED

pygeosx.READY_TO_RUN
This state indicates that GEOS still has time steps left to run.
pygeosx.COMPLETED
This state indicates that GEOS has completed the current simulation.

Module Classes
class pygeosx.Group
Python interface to geos::dataRepository::Group.
Used to get access to other groups, and ultimately to get wrappers and convert them into Python views of C++
objects.
groups()
Return a list of the subgroups.
wrappers()
Return a list of the wrappers.
get_group(path)

get_group(path, default)
Return the Group at the relative path path; default is optional. If no group exists and default is not
given, raise a ValueError; otherwise return default.
get_wrapper(path)

get_wrapper(path, default)
Return the Wrapper at the relative path path; default is optional. If no Wrapper exists and default is
not given, raise a ValueError; otherwise return default.

556 Chapter 1. Table of Contents

GEOS Documentation

register(callback)
Register a callback on the physics solver.
The callback should take two arguments: the CRSMatrix and the array.
Raise TypeError if the group is not the Physics solver.
class pygeosx.Wrapper
Python interface to geos::dataRepository::WrapperBase.
Wraps a generic C++ object. Use repr to get a description of the type.
value()
Return a view of the wrapped value, or None if it cannot be exported to Python.
A breakdown of the possible return types:
• Instance of a pylvarray class If the wrapped type is one of the LvArray types that have a Python wrapper
type.
• 1D numpy.ndarray If the wrapped type is a numeric constant. The returned array is a shallow copy
and has a single entry.
• str If the wrapped type is a std::string this returns a copy of the string.
• list of str If the wrapped type is a LvArray::Array< std::string, 1, . . . > or a std::vector< std::string
>. This is a copy.
• None If the wrapped type is not covered by any of the above.

Segmentation Faults
Improper use of this module and associated programs can easily cause Python to crash. There are two main causes of
crashes. Both can be avoided by following some general guidelines.

Stale Numpy Views

The pylvarray classes (which may be returned from Wrapper.value()) provide various ways to get Numpy views
of their data. However, those views are only valid as long as the LvArray object’s buffer is not reallocated. The buffer
may be reallocated by invoking methods (the ones that require the pylarray.RESIZEABLE permission) or by calls
into pygeosx. It is strongly recommended that you do not keep Numpy views of LvArray objects around after calls to
pygeosx.

my_array = pygeosx.get_wrapper("path").value()
view = my_array.to_numpy()
my_array.resize(1000)
print(view) # segfault

Destroyed LvArray C++ objects

As mentioned earlier, the classes defined in this module cannot be created in Python; pygeosx must create an LvArray
object in C++, then create a pylvarray view of it. However, the Python view will only be valid as long as the
underlying LvArray C++ object is kept around. If that is destroyed, the Python object will be left holding an invalid
pointer and subsequent attempts to use the Python object will cause undefined behavior. Unfortunately, pygeosx may
destroy LvArray objects without warning. It is therefore strongly recommended that you do not keep pylvarray
objects around after calls to pygeosx. The following code snippet, for instance, could segfault:

1.5. User Guide 557

GEOS Documentation

my_array = pygeosx.get_wrapper("path").value()
pygeosx.run()
view = my_array.to_numpy() # segfault

1.5.17 Indices and tables

• genindex
• modindex
• search

1.6 Developer Guide

Welcome to the GEOS developer guide. This guide serves as a reference for developers contributing to the GEOS
project. The Contributing section provides general details and guidelines for contributing to the GEOS project. The
Code Components section provides an overview of the some basic components that of the GEOS project.

1.6.1 Contributing
Code style
Introduction

GEOS is written in standard c++17. In general, target platforms are:

• Linux
• Mac OS X
Currently, our CI/CD system tests on these platforms:
• Ubuntu 18.04, with gcc 8.0 and clang 8.0.0 + cuda10.1.243
• Centos 7.6.1810, with gcc 8.3.1 + cuda10.1.243
• Centos 7.7, with clang 9.0.0
• Mac OS X, with xcode 11.2

Naming Conventions

File Names

• File names should be PascalCase.

• C++ header files are always named with a file extension of *.hpp.
• C++ header implementation files, which contain templated or inline function definitions, are always named
*Helpers.hpp.
• C++ source files are always named with a file extension of *.cpp.
• C++ class declarations and definitions are contained files with identical names, except for the extensions.
• C++ free function headers and source files are declared/defined in files with identical names, except for the
extension.
For example, a class named “Foo” may be declared in a file named “Foo.hpp”, with inline/templated functions defined
in “FooHelpers.hpp”, with the source implementation contained in Foo.cpp.

558 Chapter 1. Table of Contents

GEOS Documentation

. Warning

There should not be identical filenames that only differ by case. Some filesystems are not case-sensitive, and worse,
some filesystems such as MacOSX are case-preserving but not case sensitive.

Function Names

Function and member function names should be camelCase.

Variable Names

Variables should be camelCase.

Member Names

Member data should be camelCase prefix with “m_” (i.e. double m_dataVariable;)

Class/Struct Names

Please use PascalCase for typenames (i.e. classes)

class MyClass;

class MyClass
{
double m_doubleDataMember;
int m_integerDataMember;
}

Alias/Typedef Names

Alias and typedefs should be the case of the underlying type that they alias. If no clear format is apparent, as is the case
with double, then use camelCase

Namespace Names

Namespaces names are all lower camel case.

Example

One example of would be a for a class named “Foo”, the declaration would be in a header file named “Foo.hpp”

/*
* Foo.hpp
*/

namespace bar
{

class Foo
{
public:
(continues on next page)

1.6. Developer Guide 559

GEOS Documentation

(continued from previous page)

Foo();
private:
double m_myDouble;
}
}

and a source file named “Foo.cpp”

/*
* Foo.cpp
*/
namespace bar
{
Foo::Foo():
m_myDouble(0.0)
{
// some constructor stuff
}
}

Const Keyword

1. All functions and accessors should be declared as “const” functions unless modification to the class is required.
2. In the case of accessors, both a “const” and “non-const” version should be provided.
3. The const keyword should be placed in the location read by the compiler, which is right to left.
The following examples are provided:

int a=0; // regular int

int const b = 0; // const int
int * const c = &a; // const pointer to non const int
int const * const d = &b; // const pointer to const int
int & e = a; // reference to int
int const & f = b; // reference to const int

Code Format

GEOS applies a variant of the BSD/Allman Style. Key points to the GEOS style are:
1. Opening braces (i.e. “{”) go on the next line of any control statement, and are not indented from the control
statement.
2. NO TABS. Only spaces. In case it isn’t clear . . . NO TABS!
3. 2-space indentation

for( int i=0 ; i<10 ; ++i )

{
std::cout << "blah" << std::endl;
}

4. Try to stay under 100 character line lengths. To achieve this apply these rules in order
5. Align function declaration/definitions/calls on argument list

560 Chapter 1. Table of Contents

GEOS Documentation

6. Break up return type and function definition on new line

7. Break up scope resolution operators

void
SolidMechanics_LagrangianFEM::
TimeStepExplicit( real64 const& time_n,
real64 const& dt,
const int cycleNumber,
DomainPartition * const domain )
{
code here
}

As part of the continuous integration testing, this GEOS code style is enforced via the uncrustify tool. While quite
extensive, uncrustify does not enforce every example of the preferred code style. In cases where uncrusitfy is unable to
enforce code style, it will ignore formatting rules. In these cases it is acceptable to proceed with pull requests, as there
is no logical recourse.

Header Guards

Header guard names should consist of the name GEOS, followed by the component name (e.g. dataRepository), and
finally the name of the header file. All characters in the macro should be capitalized.

Git Workflow
The GEOS project is hosted on github here. For instructions on how to clone and build GEOS, please refer to the Quick
Start Guide. Consider consulting https://try.github.io/ for practical references on how to use git.

Git Credentials

Those who want to contribute to GEOS should setup SSH keys for authentication, and connect to github through SSH
as discussed in this article. Before going further, you should test your ssh connection. If it fails (perhaps because of
your institution’s proxy), you may consider the personal access token option as an alternative.

Downloading the Code

Once you have created an ssh-key and you have added it to your Github account you can download the code through
SSH. The following steps clone the repository into your_geosx_dir:

git clone [email protected]:GEOS-DEV/GEOS.git your_geosx_dir

cd your_geosx_dir
git lfs install
git submodule init
git submodule update

If all goes well, you should have a complete copy of the GEOS source at this point. The most common errors people
encounter here have to do with Github not recognizing their authentication settings.

Branching Model

The branching model used in GEOS is a modified Gitflow approach, with some modifications to the merging strategy,
and the treatment of release branches, and hotfix branches.

1.6. Developer Guide 561

GEOS Documentation

In GEOS, there are two main branches, release and develop. The develop branch serves as the main branch for the
development of new features. The release branch serves as the “stable release” branch. The remaining branch types
are described in the following subsections.

ò Note

The early commits in GEOS (up to version 0.2) used a pure Gitflow approach for merging feature branches into
develop. This was done without cleaning the commit history in each feature branch prior to the merge into develop,
resulting in an overly verbose history. Furthermore, as would be expected, having many active feature branches
resulted in a fairly wide (spaghetti) history. At some point in the development process, we chose to switch primarily
to a squash-merge approach which results in a linear develop history. While this fixes the spaghetti history, we do
potentially lose important commit history during the development process. Options for merging are discussed in
the following sections.

Feature Branches

New developments (new features or modifications to features) are branched off of develop into a feature branch.
The naming of feature branches should follow feature/[developer]/[branch-description] if you expect that
only a single developer will contribute to the branch, or feature/[branch-description] if you expect it will be a
collaborative effort. For example, if a developer named neo were to add or modify a code feature expecting that they
would be the only contributor, they would create a branch using the following commands to create the local branch and
push it to the remote repository:

git checkout -b feature/neo/freeYourMind

git push -u origin feature/neo/freeYourMind

However if the branch is a collaborative branch amongst many developers, the appropriate commands would be:

git checkout -b feature/freeYourMind

git push -u origin feature/freeYourMind

When feature branches are ready to be merged into develop, a Pull Request should be created to perform the
review and merging process.
An example lifecycle diagram for a feature branch:

create new feature branch:

git checkout -b feature/neo/freeYourMind

A-------B-------C (develop)
\
\
BA (feature/neo/freeYourMind)

Add commits to 'feature/neo/freeYourMind' and merge back into develop:

A-------B--------C-------D--------E (develop)
\ /
\ /
BA----BB----BC (feature/neo/freeYourMind)

See below for details about Submitting a Pull Request.

562 Chapter 1. Table of Contents

GEOS Documentation

Bugfix Branches

Bugfix branches are used to fix bugs that are present in the develop branch. A similar naming convention to that of
the feature branches is used, replacing “feature” with “bugfix” (i.e. bugfix/neo/squashAgentSmith). Typically,
bugfix branches are completed by a single contributor, but just as with the feature branches, a collaborative effort
may be required resulting a dropping the developer name from the branch name.
When bugfix branches are ready to be merged into develop, a Pull Request should be created to perform the
review and merging process. See below for details about Submitting a Pull Request.

Release Candidate Branches

When develop has progressed to a point where we would like to create a new release, we will create a release
candidate branch with the name consisting of release_major.minor.x number, where the x represents the sequence
of patch tags that will be applied to the branch. For instance if we were releasing version 1.2.0, we would name the
branch release_1.2.x. Once the release candidate is ready, it is merged back into develop. Then the develop
branch is merged into the release branch and tagged. From that point the release branch exists to provide a basis
for maintaining a stable release version of the code. Note that the absence of hotfix branches, the history for release
and develop would be identical.
An example lifecycle diagram for a release candidate branch:

v1.2.0 (tag)
G (release)
^
|
A----B-----C----D-----E-----F-----G------------ (develop)
\ \ /
\ \ /
BA----BB----BC----BD (release_1.2.x)

Hotfix Branches

A hotfix branch fixes a bug in the release branch. It uses the same naming convention as a bugfix branch. The
main difference with a bugfix branch is that the primary target branch is the release branch instead of develop. As
a soft policy, merging a hotfix into a release branch should result in a patch increment for the release sequence of
tags. So if a hotfix was merged into release with a most recent tag of 1.2.1, the merged commit would be tagged
with 1.2.2. Finally, at some point prior to the next major/minor release, the release branch should be merged back
into develop to incorporate any hotfix changes into develop.
An example lifecycle diagram for hotfix branchs:

v1.2.0 v1.2.1 v1.2.2 v1.3.0 (tag)

B------------H1-----------H2 I (release)
^\ /| \ / \ ^
| \ / \ \ / \ |
| BA-----BB \ H1A--H1B \ | (hotfix/xyz)
| \ \ |
A----B-----C-----D----E------F------G----H----I--- (develop)

Documentation Branches

A docs branch is focused on writing and improving the documentation for GEOS. The use of the docs branch name
root applies to both sphinx documentation and doxygen documentation. The docs branch follows the same naming

1.6. Developer Guide 563

GEOS Documentation

conventions as described in the Feature Branches section. The html produced by a documentation branch should be
proofread using sphinx/doxygen prior to merging into develop.

Keeping Your Branch Current

Over the course of a long development effort in a single feature branch, a developer may need to either merge develop
into their feature branch, or rebase their feature branch on develop. We do not have a mandate on how you
keep your branch current, but we do have guidelines on the branch history when merging your branch into develop.
Typically, merging develop into your branch is the easiest approach, but will lead to a complex relationship with
develop with multiple interactions. . . which can lead to a confusing history. Conversely, rebasing your branch onto
develop is more difficult, but will lead to a linear history within the branch. For a complex history, we will perform a
squash merge into develop, thereby the work from the branch will appear as a single commit in develop. For clean
branch histories where the individual commits are meaningful and should be preserved, we have the option to perform
a merge commit in with the PR is merged into develop, with the addition of a merge commit, thus maintaining the
commit history.

Branching off of a Branch

During the development processes, sometimes it is appropriate to create a branch off of a branch. For instance, if there
is a large collaborative development effort on the branch feature/theMatrix, and a developer would like to add a
self-contained and easily reviewable contribution to that effort, he/she should create a branch as follows:

git checkout feature/theMatrix

git checkout -b feature/smith/dodgeBullets
git push -u origin feature/smith/dodgeBullets

If feature/smith/dodgeBullets is intended to be merged into feature/theMatrix, and the commit history of

feature/theMatrix is not changed via git rebase, then the process of merging the changes back into feature/
theMatrix is fairly standard.
However, if feature/theMatrix is merged into develop via a squash merge, and then smith would like to
merge feature/smith/dodgeBullets into develop, there is a substantial problem due to the diverged history of
the branches. Specifically, feature/smith/dodgeBullets branched off a commit in feature/theMatrix that
does not exist in develop (because it was squash-merged). For simplicity, let us assume that the commit hash that
feature/smith/dodgeBullets originated from is CC, and that there were commits CA, CB, CC, CD in feature/
theMatrix. When feature/theMatrix was squash-merged, all of the changes appear in develop as commit G. To
further complicate the situation, perhaps a complex PR was merged after G, resulting in E on develop. The situation is
illustrated by:

A----B----C----D----E----F----G----E (develop)
\ /
CA---CB---CC---CD (feature/theMatrix)
\
CCA--CCB--CCC (feature/smith/dodgeBullets)

In order to successfully merge feature/smith/dodgeBullets into develop, all commits present in feature/
smith/dodgeBullets after CC must be included, while discarding CA, CB, which exist in feature/smith/
dodgeBullets as part of its history, but not in develop.
One “solution” is to perform a git rebase --onto of feature/smith/dodgeBullets onto develop. Specif-
ically, we would like to rebase CCA, CCB, CCC onto G, and proceed with our development of feature/smith/
dodgeBullets. This would look like:

git checkout develop

Keeping Submodules Current

Whenever you switch between branches locally, pull changes from origin and/or merge from the relevant branches,
it is important to update the submodules to move the head to the proper commit.

git submodule update --recursive

You may also wish to modify your git pull behavior to update your submodules recursively for you in one command,
though you forfeit some control granularity to do so. The method for accomplishing this varies between git versions,
but as of git 2.15 you should be able to globally configure git to accomplish this via:

git config --global submodule.recurse true

In some cases, code changes will require to rebaseline the Integrated Tests. If that is the case, you will need
to modify the integrated tests submodule. Instructions on how to modify a submodule are presented in the
following section.

Working on the Submodules

Sometimes it may be necessary to modify one of the submodules. In order to do so, you need to create a pull request
on the submodule repository. The following steps can be followed in order to do so.
Move to the folder of the submodule that you intend to modify.

566 Chapter 1. Table of Contents

GEOS Documentation

cd submodule-folder

Currently the submodule is in detached head mode, so you first need to move to the main branch (either develop or
master) on the submodule repository, pull the latest changes, and then create a new branch.

git checkout <main-branch>

git pull
git checkout -b <branch-name>

You can perform some work on this branch, add and commit the changes and then push the newly created branch to the
submodule repository on which you can eventually create a pull request using the same process discussed above
in Submitting a Pull Request.

git push --set-upstream origin <branch-name>

Resolving Submodule Changes in Primary Branch PRs

When you conduct work on a submodule during work on a primary GEOS branch with an open PR, the merging
procedure requires that the submodule referenced by the GEOS PR branch be consistent with the submodule in the
main branch of the project. This is checked and enforced via our CI.
Thus, in order to merge a PR that includes modifications to submodules, the various PRs for each repository should be
staged and finalized, to the point they are all ready to be merged, with higher-level PRs in the merge hierarchy having
the correct submodule references for the current main branch for their repository.
Starting from the bottom of the submodule hierarchy, the PRs are resolved, after which the higher-level PRs with
reference to a resolved PR must update their submodule references to point to the new main branch of the submodule
with the just-resolved PR merged. After any required automated tests pass, the higher-level PRs can then be merged.
The name of the main branch of each submodule is presented in the table below.

Submodule Main branch

blt develop
LvArray develop
integratedTests develop
hdf5_interface master
PVTPackage master

Sphinx Documentation
Generating the documentation

• To generate the documentation files, you will need to install Sphinx using:

pip -m install sphinx

pip -m install sphinx-design sphinx-argparse sphinxcontrib-plantuml sphinxcontrib.
˓→programoutput sphinx_rtd_theme

pip -m install scipy

• Then you can generate the documentation files with the following commands:

cd /path/to/GEOS/build-your-platform-release
make geosx_docs

1.6. Developer Guide 567

GEOS Documentation

• That will create a new folder

/path/to/GEOS/build-your-platform-release/html/docs/sphinx

which contains all the html files generated.

Documenting the code

The documentation is generated from restructured text files (.rst). Most files can be found in src/docs/sphinx.
Files which are specific to parts of the code, like those describing a specific class, can instead be found in docs subdi-
rectory in the folder containing the source code.
Information about how to write rst files can be found here .

Fixing errors the documentation

As part of the Continuous Integration process, the documentation is built on readthedocs, and any warnings or errors
result in a failure test failure. What follows is a brief guide on how to fix the most common errors.
1. Navigate to the readthedocs build logs. This can be done by clicking on the failed test in the github test summary.

1. Download the logs from the failed test on readthedocs through the “view raw” button.

568 Chapter 1. Table of Contents

GEOS Documentation

#. Perform a case sensitive search for “WARNING:” or “ERROR” to locate the sphinx issues. Note that there will be
numerous doxygen warnings that should be ignored.

Doxygen Documentation
Developer documentation of code is provided in the form of Doxygen-style comment blocks. Doxygen is a tool for
generating html/xml/latex documentation for C++ code from specially marked code comments. Having concise but
high quality documentation of public APIs helps both users and developers of these APIs. We use Doxygen and Ctest
to enforce documentation coverage. If Doxygen produces any warnings, your pull request will fail CI checks! See Git
Workflow for more on pull requests and CI.

Accessing

There are two ways to access Doxygen documentation.

Build locally

Prior to configuring a GEOS build, have Doxygen installed:

sudo apt install doxygen

ò Note

Eventually, doxygen (version 1.8.13) is provided within the thirdPartyLibs repository.

Configure GEOS and go the build directory:

cd GEOS/build-your-platform-release

Build doxygen docs only:

1.6. Developer Guide 569

GEOS Documentation

make geosx_doxygen

Or build all docs:

make geosx_docs

Open in browser:

google-chrome html/doxygen_output/html/index.html

On readthedocs

Go to GEOS documentation, select the version of interest, and follow the Doxygen link at the left-hand-side.

Guidelines

What to document

The following entities declared in project header files within geosx namespace require documentation:
• all classes and structs, including public nested ones
• global functions, variables and type aliases
• public and protected member functions, variables and type aliases in classes
• preprocessor macros
Exceptions are made for:
• overrides of virtual functions in derived types
• implementation details nested in namespace internal
• template specializations in some cases

How to document

The following rules and conventions are used. Some are stricter than others.
1. We use @-syntax for all Doxygen commands (e.g. @brief instead of \brief ).
2. Entities such as type aliases and member variables that typically only require a brief description, can have a
single-line documentation starting with ///.
• @brief is not required for single-line comments.
3. Entities such as classes and functions that typically require either detailed explanation or parameter documenta-
tion, are documented with multiline comment blocks.
• @brief is required for comment blocks.
4. Brief and detailed descriptions should be complete sentences (i.e. start with a capital letter and end with a dot).
5. Prefer concise wording in @brief, e.g. “Does X.” instead of “This is a function that does X.”
6. All functions parameters and return values must be explicitly documented via @param and @return.
• An exception to this rule seem to be copy/move constructor/assignment, where parameter documentation
can be omitted.
7. Add [in] and [out] tags to function parameters, as appropriate.

570 Chapter 1. Table of Contents

GEOS Documentation

8. Function and template parameter descriptions are not full sentences (i.e. not capitalized nor end with a dot).
9. For hierarchies with virtual inheritance, document base virtual interfaces rather than overriding implementations.
10. Documented functions cannot use GEOS_UNUSED_ARG() in their declarations.
11. For empty virtual base implementations that use GEOS_UNUSED_ARG(x) to remove compiler warnings, use
one of two options:
• move empty definition away (e.g. out of class body) and keep GEOS_UNUSED_ARG(x) in definition only;
• put GEOS_UNUSED_VAR(x) into the inline empty body.
12. For large classes, logically group functions using member groups via ///@{ and ///@} and give them group names
and descriptions (if needed) via a @name comment block. Typical groups may include:
• constructors/destructor/assignment operators;
• getter/setter type functions;
• overridable virtual functions;
• any other logically coherent groups (functions related to the same aspect of class behavior).
13. In-header implementation details (e.g. template helpers) often shouldn’t appear in user documentation. Wrap
these into internal namespace.
14. Use /// @cond DO_NOT_DOCUMENT and /// @endcond tags to denote a section of public API that should not
be documented for some reason. This should be used rarely and selectively. An example is in-class helper structs
that must be public but that user should not refer to explicitly.

Example

/// This is a documented macro

#define USEFUL_MACRO

/**
* @brief Short description.
* @tparam T type of input value
* @param[in] x input value explanation
* @return return value explanation
*
* Detailed description goes here.
*
* @note A note warning users of something unexpected.
*/
template<typename T>
int Foo( T const & x );

/**
* @brief Class for showing Doxygen.
* @tparam T type of value the class operates on
*
* This class does nothing useful except show how to use Doxygen.
*/
template<typename T>
class Bar
{
public:
(continues on next page)

1.6. Developer Guide 571

GEOS Documentation

(continued from previous page)

/// A documented member type alias.

using size_type = typename std::vector<T>::size_type;

/**
* @name Constructors/destructors.
*/
///@{

/**
* @brief A documented constructor.
* @param value to initialize the object
*/
explicit Bar( T t );

/**
* @brief A deleted, but still documented copy constructor.
* @param an optionally documented parameter
*/
Bar( Bar const & source ) = delete;

/**
* @brief A defaulted, but still documented move constructor.
* @param an optionally documented parameter
*/
Bar( Bar const & source ) = default;

/**
* @brief A documented desctructor.
* virtual ~Bar() = default;
*/

///@}

/**
* @name Getters for stored value.
*/
///@{

/**
* @brief A documented public member function.
* @return a reference to contained value
*/
T & getValue();

/**
* @copydoc getValue()
*/
T const & getValue() const;

///@}

(continues on next page)

572 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

protected:

/**
* @brief A documented protected pure virtual function.
* @param[in] x the input value
* @param[out] y the output value
*
* Some detailed explanation for users and implementers.
*/
virtual void doSomethingOverridable( int const x, T & y ) = 0;

/// @cond DO_NOT_DOCUMENT

// Some stuff we don't want showing up in Doxygen
struct BarHelper
{};
/// @endcond

private:

/// An optionally documented (not enforced) private member.

T m_value;

};

Current Doxygen

Link to Doxygen Class directory

Direct links to some useful class documentation:
Group API
Wrapper API
ObjectManagerBase API
MeshLevel API
NodeManager API
FaceManager API

Unit Testing
Unit testing is integral to the GEOS development process. While not all components naturally lend themselves to unit
testing (for example a physics solver) every effort should be made to write comprehensive quality unit tests.
Each sub-directory in coreComponents should have a unitTests directory containing the test sources. Each test
consists of a cpp file whose name begins with test followed by a name to describe the test. Please read over the
LvArray unit test documentation as it gives an intro to the Google Test framework and a set of best practices.

GEOS Specific Recommendations

An informative example is testSinglePhaseBaseKernels which tests the single phase flow mobility and accumu-
lation kernels on a variety of inputs.

1.6. Developer Guide 573

GEOS Documentation

TEST( SinglePhaseBaseKernels, mobility )

{
int constexpr NTEST = 3;

real64 const dens[NTEST] = { 800.0, 1000.0, 1500.0 };

real64 const dDens_dPres[NTEST] = { 1e-5, 1e-10, 0.0 };
real64 const visc[NTEST] = { 5.0, 2.0, 1.0 };
real64 const dVisc_dPres[NTEST] = { 1e-7, 0.0, 0.0 };

for( int i = 0; i < NTEST; ++i )

{
SCOPED_TRACE( "Input # " + std::to_string( i ) );

real64 mob;
real64 dMob_dPres;

MobilityKernel::compute( dens[i], dDens_dPres[i], visc[i], dVisc_dPres[i], mob, dMob_

˓→ dPres );

// compute etalon
real64 const mob_et = dens[i] / visc[i];
real64 const dMob_dPres_et = mob_et * (dDens_dPres[i] / dens[i] - dVisc_dPres[i] /␣
˓→visc[i]);

EXPECT_DOUBLE_EQ( mob, mob_et );

EXPECT_DOUBLE_EQ( dMob_dPres, dMob_dPres_et );
}
}

[Source: coreComponents/physicsSolvers/fluidFlow/unitTests/testSinglePhaseMobilityKernel.cpp]
What makes this such a good test is that it depends on very little other than kernels themselves. There is no need to
involve the data repository or parse an XML file. Sometimes however this is not possible, or at least not without a
significant duplication of code. In this case it is better to embed the XML file into the test source as a string instead
of creating a separate XML file and passing it to the test as a command line argument or hard coding the path. One
example of this is testLaplaceFEM which tests the laplacian solver. The embedded XML is shown below.

char const * xmlInput =

R"xml(
<Problem>
<Solvers gravityVector="{ 0.0, 0.0, -9.81 }">
<CompositionalMultiphaseFVM name="compflow"
logLevel="0"
discretization="fluidTPFA"
targetRegions="{region}"
temperature="297.15"
useMass="1">

<NonlinearSolverParameters newtonTol="1.0e-6"
newtonMaxIter="2"/>
<LinearSolverParameters solverType="gmres"
krylovTol="1.0e-10"/>
</CompositionalMultiphaseFVM>
(continues on next page)

574 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

</Solvers>
<Mesh>
<InternalMesh name="mesh"
elementTypes="{C3D8}"
xCoords="{0, 3}"
yCoords="{0, 1}"
zCoords="{0, 1}"
nx="{3}"
ny="{1}"
nz="{1}"
cellBlockNames="{cb1}"/>
</Mesh>
<NumericalMethods>
<FiniteVolume>
<TwoPointFluxApproximation name="fluidTPFA"/>
</FiniteVolume>
</NumericalMethods>
<ElementRegions>
<CellElementRegion name="region" cellBlocks="{*}" materialList="{fluid, rock,␣
˓→relperm, cappressure}" />

</ElementRegions>
<Constitutive>
<CompositionalMultiphaseFluid name="fluid"
phaseNames="{oil, gas}"
equationsOfState="{PR, PR}"
componentNames="{N2, C10, C20, H2O}"
componentCriticalPressure="{34e5, 25.3e5, 14.6e5,␣
˓→220.5e5}"

componentCriticalTemperature="{126.2, 622.0, 782.0,␣

˓→647.0}"

componentAcentricFactor="{0.04, 0.443, 0.816, 0.344}"

componentMolarWeight="{28e-3, 134e-3, 275e-3, 18e-3}"
componentVolumeShift="{0, 0, 0, 0}"
componentBinaryCoeff="{ {0, 0, 0, 0},
{0, 0, 0, 0},
{0, 0, 0, 0},
{0, 0, 0, 0} }"/>
<CompressibleSolidConstantPermeability name="rock"
solidModelName="nullSolid"
porosityModelName="rockPorosity"
permeabilityModelName="rockPerm"/>
<NullModel name="nullSolid"/>
<PressurePorosity name="rockPorosity"
defaultReferencePorosity="0.05"
referencePressure = "0.0"
compressibility="1.0e-9"/>
<BrooksCoreyRelativePermeability name="relperm"
phaseNames="{oil, gas}"
phaseMinVolumeFraction="{0.1, 0.15}"
phaseRelPermExponent="{2.0, 2.0}"
phaseRelPermMaxValue="{0.8, 0.9}"/>
<BrooksCoreyCapillaryPressure name="cappressure"
(continues on next page)

1.6. Developer Guide 575

GEOS Documentation

(continued from previous page)

phaseNames="{oil, gas}"
phaseMinVolumeFraction="{0.2, 0.05}"
phaseCapPressureExponentInv="{4.25, 3.5}"
phaseEntryPressure="{0., 1e8}"
capPressureEpsilon="0.0"/>
<ConstantPermeability name="rockPerm"
permeabilityComponents="{2.0e-16, 2.0e-16, 2.0e-16}"/>
</Constitutive>
<FieldSpecifications>
<FieldSpecification name="initialPressure"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/region/cb1"
fieldName="pressure"
functionName="initialPressureFunc"
scale="5e6"/>
<FieldSpecification name="initialComposition_N2"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/region/cb1"
fieldName="globalCompFraction"
component="0"
scale="0.099"/>
<FieldSpecification name="initialComposition_C10"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/region/cb1"
fieldName="globalCompFraction"
component="1"
scale="0.3"/>
<FieldSpecification name="initialComposition_C20"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/region/cb1"
fieldName="globalCompFraction"
component="2"
scale="0.6"/>
<FieldSpecification name="initialComposition_H20"
initialCondition="1"
setNames="{all}"
objectPath="ElementRegions/region/cb1"
fieldName="globalCompFraction"
component="3"
scale="0.001"/>
</FieldSpecifications>
<Functions>
<TableFunction name="initialPressureFunc"
inputVarNames="{elementCenter}"
coordinates="{0.0, 3.0}"
values="{1.0, 0.5}"/>
</Functions>
</Problem>
(continues on next page)

576 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

)xml";

[Source: coreComponents/physicsSolvers/fluidFlow/unitTests/testCompMultiphaseFlow.cpp]

MPI

Often times it makes sense to write a unit test that is meant to be run with multiple MPI ranks. This can be accomplished
by simply adding the NUM_MPI_TASKS parameter to geos_add_test in the CMake file. For example

geos_add_test( NAME testWithMPI

COMMAND testWithMPI
NUM_MPI_TASKS ${NUMBER_OF_MPI_TASKS} )

With this addition make test or calling ctest directly will run testWithMPI via something analogous to mpirun
-n NUMBER_OF_MPI_TASKS testWithMPI.

Contributing Input Files

As part of the development cycle, functional input files should be introduced into the repository in order to provide
1) testing, 2) examples of proper use of the code. The input files should be modulerized such that the majority of
the input resides in a base file, and the variations in input are contained in specific files for integrated/smoke testing,
and benchmarking. For example if we had a single input file named myProblem.xml, we would break it up into
myProblem_base.xml, myProblem_smoke.xml`', and ``myProblem_benchmark.xml. Each of the smoke/
benchark files should include the base file using an include block as follows:

The files should be placed in the appropriate application specific subdirectory under the GEOS/inputFiles directory.
For example, the beamBending problem input files reside in the inputFiles/solidMechanics directory. The files
then be linked to from the appropriate location in the integratedTests repository as described in the following
section.

Integrated Tests
About

The GEOS integrated test system leverages the Automated Test System (ATS) and GEOS ATS packages to run various
combinations of input files and machine configurations. The output of these runs are then compared to baseline files
and/or analytic solutions to guarantee the accuracy of the code.

Structure

GEOS integrated tests are defined in the GEOS/inputFiles directory, and are organized into folders based on the physical
processes being tested. A test folder can contain any number of .ats configuration files, .xml input files, and supporting
inputs (tables files, meshes, etc.).

- inputFiles/
- main.ats/
- solidMechanics/
- sedov.ats
- sedov.xml
(continues on next page)

1.6. Developer Guide 577

GEOS Documentation

(continued from previous page)

- etc.
- .integrated_tests.yaml

Test baselines are stored as .tar.gz archive and share the same directory structure as GEOS/inputFiles. During
test execution, the geos_ats package will fetch and unpack any necessary baselines described in the top-level .inte-
grated_tests.yaml configuration file.

How to Run the Tests

GEOS CI Pipeline

In most cases, developers will be able to rely on the integrated tests that are run as part of the GEOS CI Pipeline. These
can be triggered if the ci: run integrated tests label is selected for a pull request (this can be added from the right-hand
panel on PR page).
To inspect the results of CI tests, select the Checks tab from the top of the pull request and then select
run_integrated_tests/build_test_deploy from the left-hand panel.

This page will show the full output of GEOS build process and the integrated test suite. At the bottom of this page, the
logs will contain a summary of the test results and a list of any ignored/failed tests.

=======================
Integrated test results
=======================
expected: 0
created: 0
(continues on next page)

578 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

batched: 0
filtered: 104
skipped: 0
running: 0
passed: 215
timedout: 0 (3 ignored)
halted: 0
lsferror: 0
failed: 0
=======================
Ignored tests
=======================
pennyShapedToughnessDominated_smoke_01
pennyShapedViscosityDominated_smoke_01
pknViscosityDominated_smoke_01
=======================
Overall status: PASSED
=======================

The log will provide instructions on where to download the test results and a baseline ID that can be assigned in the
.integrated_tests.yaml file.
. code-block:: sh
Download the bundle at https://storage.googleapis.com/geosx/integratedTests/baseline_
integratedTests-pr3044-4400-e6359ca.tar.gz New baseline ID: baseline_integratedTests-pr3044-4400-
e6359ca

ò Note

Integrated tests within GEOS CI pipeline are run on a shared machine, and may take up to 30 minutes to complete.
It may take some time for the tests to begin if the machine is in use by other developers.

Manual Test Runs

Before running the integrated tests manually, we recommend that you define the following variables in your machine’s
host configuration file:
• ATS_WORKING_DIR : The location where tests should be run (default=*GEOS/[build-
dir]/integratedTests/workingDir*)
• ATS_BASELINE_DIR : The location where test baselines should be stored (default=*GEOS/integratedTests*)

ò Note

The ATS_WORKING_DIR should be located on a file system that is amenable to parallel file IO.

After building GEOS, the integrated tests can be triggered in the GEOS build directory with the following commands:
• make ats_environment : Setup the testing environment (Note: this step is run by default for the other make
targets). This process will install packages required for testing into the python environment defined in your
current host config file. Depending on how you have built GEOS, you may be prompted to manually run the
make pygeosx command and then re-run this step.

1.6. Developer Guide 579

GEOS Documentation

• make ats_run : Run all of the available tests (see the below note on testing resources).
• make ats_clean : Remove any unnecessary files created during the testing process (.vtk, .hdf5 files, etc.)
• make ats_rebaseline : Selectively update the baseline files for tests.
• make ats_rebaseline_failed : Automatically update the baseline files for any failed tests.

ò Note

The make ats_environment and make ats_run steps may require internet access to collect python packages and
baseline files.

ò Note

Running the integrated tests requires significant computational resources. If you are on a shared system, we rec-
ommend that you only run make ats_run within an allocation.

ò Note

We forward any arguments included in the ATS_ARGUMENTS cmake variable to the testing system. For example,
on LLNL Lassen builds we select a couple of runtime options: set(ATS_ARGUMENTS “–ats jsrun_omp –ats
jsrun_bind=packed” CACHE STRING “”)

ò Note

When running test or creating new baselines on LC systems, we recommend that you use the quartz-gcc-12-release
configuration

Override Test Behavior

For cases where you need additional control over the integrated tests behavior, you can use this script in your build
directory: /path/to/GEOS/build-xyz/integratedTests/geos_ats.sh. To run the tests, simply call this script with any desired
arguments (see the output of geos_ats.sh –help for additional details.) Common options for this script include:
• -a/–action : The type of action to run. Common options include: run, veryclean, rebaseline, and rebaselinefailed.
• -r/–restartCheckOverrides : Arguments to pass to the restart check function. Common options include:
skip_missing (ignores any new/missing values in restart files) and exclude parameter1 parameter2 (ignore these
values in restart files).
• –machine : Set the ats machine type name.
• –ats : Pass an argument to the underlying ats framework. Running geos_ats.sh –ats help will show you a list of
available options for your current machine.

Machine Definitions

On many machines, ATS will automatically identify your machine’s configuration and optimize it’s performance. If
the tests fail to run or to properly leverage your machine’s resources, you may need to manually configure the machine.
If you know the appropriate name for your machine in ATS (or the geos_ats package), then you can run ./geos_ats.sh
–machine machine_name –ats help to see a list of potential configuration options.

580 Chapter 1. Table of Contents

GEOS Documentation

The openmpi machine is a common option for non-LC systems. For a system with 32 cores/node, an appropriate run
command might look like:

./geos_ats.sh --machine openmpi --ats openmpi_numnodes 32 --ats openmpi_args=--report-

˓→bindings --ats openmpi_args="--bind-to none" --ats openmpi_install "/path/to/openmpi/

˓→installation"

ò Note

In this example, the path given by openmpi_install should include bin/mpirun.

ò Note

When you have identified a set of arguments that work for your machine, we recommend recording in the
ATS_ARGUMENTS cmake variable in your system host config file.

Test Filtering

An arbitrary number of filter arguments can be supplied to ATS to limit the number of tests to be run. Filter ar-
guments should refer to an ATS test variable and use a python-syntax (e.g.: “‘some_string’ in ats_variable” or
“ats_variable<10”). These can be set via command-line arguments (possible via the ATS_ARGUMENTS variable):

./geos_ats.sh --ats f "np==1" --ats f "'SinglePhaseFVM' in solvers"

or via an environment variable (ATS_FILTER):

export ATS_FILTER="np==1,'SinglePhaseFVM' in solvers"

Common ATS variables that you can filter tests include:

• np : The number of parallel processes for the test
• label : The name of the test case (e.g.: “sedov_01”)
• collection : The name of the parent test folder (e.g.: “contactMechanics”)
• checks : A comma-separated list of checks (e.g.: “curve,restart”)
• solvers : A comma-separated list of solver types (e.g.: “SinglePhaseFVM,SurfaceGenerator”)
• outputs : A comma-separated list of output types (e.g.: “Restart,VTK”)
• constitutive_models : A comma-separated list of constitutive model types (e.g.: “CompressibleSinglePhase-
Fluid,ElasticIsotropic”)

Inspecting Test Results

While the tests are running, the name and size of the active test will be periodically printed out to the
screen. Test result summaries will also be periodically written to the screen and files in /path/to/GEOS/build-
xyz/integratedTests/TestsResults. For most users, we recommend inspecting the test_results.html file in your browser
(e.g.: firefox integratedTests/TestsResults/test_results.html). Tests will be organized by their status variable, which in-
cludes:
• RUNNING : The test is currently running
• NOT RUN : The test is waiting to start

1.6. Developer Guide 581

GEOS Documentation

• PASSED : The test and associated checks succeeded

• FAIL RUN : The test was unable to run (this often occurs when there is an error in the .ats file)
• FAIL CHECK : The test ran to completion, but failed either its restart or curve check
• SKIPPED : The test was skipped (likely due to lack of computational resources)
If each test ends up in the PASSED category, then you are likely done with the integrated testing procedure. However,
if tests end up in any other category, it is your responsibility to address the failure. If you identify that a failure is due
to an expected change in the code (e.g.: adding a new parameter to the xml structure or fixing a bug in an algorithm),
you can follow the rebaselining procedure. Otherwise, you will need to track down and potentially fix the issue that
triggered the failure.

Test Output

Output files from the tests will be stored in the specified working directory (linked here: /path/to/GEOS/build-
xyz/integratedTests/TestsResults). Using the serial beam bending test as an example, key output files include:
• beamBending_01.data : Contains the standard output for all test steps.
• beamBending_01.err : Contains the standard error output for all test steps.
• displacement_history.hdf5 : Contains time history information that is used as an input to the curve check step.
• totalDisplacement_trace.png : A figure displaying the results of the curve check step.
• beamBending.geos.out : Contains the standard output for only the geos run step.
• beamBending_restart_000000010.restartcheck which holds all of the standard output for only the restartcheck
step.
• beamBending_restart_000000010.0.diff.hdf5 which mimmics the hierarchy of the restart file and has links to the
See Restart Check and Curve Check for further details on the test checks and output files.

Restart Check

This check compares a restart file output at the end of a run against a baseline. The python
script that evaluates the diff is included in the geos_ats package, and is located here: integrat-
edTests/scripts/geos_ats_package/geos_ats/helpers/restart_check.py. The script compares the two restart files
and writes out a .restart_check file with the results, as well as exiting with an error code if the files compare differently.
This script takes two positional arguments and a number of optional keyword arguments:
• file_pattern : Regex specifying the restart file. If the regex matches multiple files the one with the greater string
is selected. For example restart_100.hdf5 wins out over restart_088.hdf5.
• baseline_pattern : Regex specifying the baseline file.
• -r/–relative : The relative tolerance for floating point comparison, the default is 0.0.
• -a/–absolute : The absolute tolerance for floating point comparison, the default is 0.0.
• -e/–exclude : A list of regex expressions that match paths in the restart file tree to exclude from comparison. The
default is [.*/commandLine].
• -w/-Werror : Force warnings to be treated as errors, default is false.
• -m/–skip-missing : Ignore values that are missing from either the baseline or target file.
The itself starts off with a summary of the arguments. The script begins by recording the arguments to the .restart_check
file header, and then compares the .root restart files to their baseline. If these match, the script will compare the linked
.hdf5 data files to their baseline. If the script encounters any differences it will output an error message, and record a
summary to the .restart_check file.

582 Chapter 1. Table of Contents

GEOS Documentation

The restart check step can be run in parallel using mpi via

mpirun -n NUM_PROCESSES python -m mpi4py restartcheck.py ...

In this case rank zero reads in the restart root file and then each rank parses a subset of the data files creating a
.$RANK.restartcheck file. Rank zero then merges the output from each of these files into the main .restartcheck file
and prints it to standard output.

Scalar Error Example

An error message for scalar values looks as follows

Error: /datagroup_0000000/sidre/external/ProblemManager/domain/ConstitutiveManager/shale/
˓→YoungsModulus

Scalar values of types float64 and float64 differ: 22500000000.0, 10000022399.9.

Where the first value is the value in the test’s restart file and the second is the value in the baseline.

Array Error Example

An example of an error message for arrays is

Error: /datagroup_0000000/sidre/external/ProblemManager/domain/MeshBodies/mesh1/Level0/
˓→nodeManager/TotalDisplacement

Arrays of types float64 and float64 have 1836 values of which 1200 have differing␣
˓→values.

Statistics of the differences greater than 0:

max_index = (1834,), max = 2.47390764755, mean = 0.514503482629, std = 0.70212888881

This means that the max absolute difference is 2.47 which occurs at value 1834. Of the values that are not equal the
mean absolute difference is 0.514 and the standard deviation of the absolute difference is 0.702.
When the tolerances are non zero the comparison is a bit more complicated. From the FileCompari-
son.compareFloatArrays method documentation

Entries x1 and x2 are considered equal iff

|x1 - x2| <= ATOL or |x1 - x2| <= RTOL * |x2|.
To measure the degree of difference a scaling factor q is introduced. The goal is now to␣
˓→minimize q such that

|x1 - x2| <= ATOL * q or |x1 - x2| <= RTOL * |x2| * q.

If RTOL * |x2| > ATOL
q = |x1 - x2| / (RTOL * |x2|)
else
q = |x1 - x2| / ATOL.
If the maximum value of q over all the entries is greater than 1.0 then the arrays are␣
˓→considered different and an error message is produced.

An sample error message is

Error: /datagroup_0000000/sidre/external/ProblemManager/domain/MeshBodies/mesh1/Level0/
˓→nodeManager/TotalDisplacement

Arrays of types float64 and float64 have 1836 values of which 1200 fail both the␣
˓→relative and absolute tests.

Max absolute difference is at index (1834,): value = 2.07474948094, base_value = 4.

˓→54865712848

(continues on next page)

1.6. Developer Guide 583

GEOS Documentation

(continued from previous page)

Max relative difference is at index (67,): value = 0.00215842135281, base_value = 0.
˓→00591771127792

Statistics of the q values greater than 1.0 defined by the absolute tolerance: N = 1200
max = 16492717650.3, mean = 3430023217.52, std = 4680859258.74
Statistics of the q values greater than 1.0 defined by the relative tolerance: N = 0

The .diff.hdf5 File

Each error generated in the restartcheck step creates a group with three children in the _diff.df5 file. For example the
error given above will generate a hdf5 group

/FILENAME/datagroup_0000000/sidre/external/ProblemManager/domain/MeshBodies/mesh1/Level0/
˓→nodeManager/TotalDisplacement

with datasets baseline, run and message where FILENAME is the name of the restart data file being compared. The
message dataset contains a copy of the error message while baseline is a symbolic link to the baseline dataset and run
is a sumbolic link to the dataset genereated by the run. This allows for easy access to the raw data underlying the diff
without data duplication. For example if you want to extract the datasets into python you could do this:

import h5py
file_path = "beamBending_restart_000000003_diff.hdf5"
path_to_data = "/beamBending_restart_000000011_0000000.hdf5/datagroup_0000000/sidre/
˓→external/ProblemManager/domain/MeshBodies/mesh1/Level0/nodeManager/TotalDisplacement"

f = h5py.File("file_path", "r")
error_message = f["path_to_data/message"]
run_data = f["path_to_data/run"][:]
baseline_data = f["path_to_data/baseline"][:]

# Now run_data and baseline_data are numpy arrays that you may use as you see fit.
rtol = 1e-10
atol = 1e-15
absolute_diff = np.abs(run_data - baseline_data) < atol
hybrid_diff = np.close(run_data, baseline_data, rtol, atol)

When run in parallel each rank creates a .$RANK.diff.hdf5 file which contains the diff of each data file processed by
that rank.

Curve Check

This check compares time history (.hdf5) curves generated during GEOS execution against baseline and/or analytic
solutions. In contrast to restart checks, curve checks are designed to be flexible with regards to things like mesh
construction, time stepping, etc. The python script that evaluates the diff is included in the geos_ats package, and is
located here: integratedTests/scripts/geos_ats_package/geos_ats/helpers/curve_check.py. The script renders the curve
check results as a figure, and will throw an error if curves are out of tolerance. This script takes two positional arguments
and a number of optional keyword arguments:
• filename : Path to the time history file.
• baseline : Path to the baseline file.
• -c/–curve : Add a curve to the check (value) or (value, setname). Multiple curves are allowed.
• -s/–script : Python script instructions for curve comparisons (path, function, value, setname)
• -t/–tolerance : The tolerance for each curve check diffs (||x-y||/N). Default is 0.

584 Chapter 1. Table of Contents

GEOS Documentation

• -w/-Werror : Force warnings to be treated as errors, default is false.

• -o/–output : Output figures to this directory. Default is ./curve_check_figures
• -n/–n-column : Number of columns to use for the output figure. Default is 1.
• -u/–units-time : Time units for plots. Options include milliseconds, seconds (default), minutes, hours, days, years
The curve check script begins by checking the target time history file for expected key values. These include the time
array (“value Time”), location array (“value ReferencePosition setname” or “value elementCenter setname”), and value
array (“value setname”). Any missing values will be recorded as errors in the output.
The script will then run and record any user-requested python script instructions. To do this, python will attempt to
import the file given by path and evaluate the target function, which should accept the time history data as keyword
arguments. Note: to avoid side effects, please ensure that any imported scripts are appropriately guarded if they also
allow direct execution:

if __name__ == '__main__':
main()

This script will then check the size of the time history items, and will attempt to interpolate them if they do not match
(currently, we only support interpolation in time). Finally, the script will compare the time history values to the baseline
values and any script-generated values. If any curves do not match (||x-y||/N > tol), this will be recorded as an error.

Item Not Found Errors

The following error would indicate that the requested baseline file was not found:

baseline file not found: /path/to/baseline/file

This type of error can occur if you are adding a new test, or if you time history output failed.
The following errors would indicate that values were not found in time history files:

Value not found in target file: value

Set not found in target file: setname
Could not find location string for parameter: value, search...

The following error would indicate that a given curve exceeded its tolerance compared to script-generated values:

script_value_setname diff exceeds tolerance: ||t-b||/N=100.0, script_tolerance=1.0

Adding and Modifying Tests

ATS Configuration File

Files with the .ats extension are used to configure the integratedTests. They use a Python 3.x syntax, and have a
set of ATS-related methods loaded into the scope (TestCase, geos, source, etc.). The root configuration file (integrat-
edTests/tests/allTests/main.ats) finds and includes any test definitions in its subdirectories. The remaining configuration
files typically add one or more tests with varying partitioning and input xml files to ATS.
The inputFiles/solidMechanics/sedov.ats file shows how to add three groups of tests. This file begins by defining a set
of common parameters, which are used later:

from geos.ats.test_builder import generate_geos_tests, RestartcheckParameters, TestDeck,␣

˓→CurveCheckParameters

(continues on next page)

1.6. Developer Guide 585

GEOS Documentation

(continued from previous page)

restartcheck_params = {}
restartcheck_params["atol"] = 2.0E-10
restartcheck_params["rtol"] = 2.0E-13

curvecheck_params = {}
curvecheck_params['filename'] = 'veloc_history.hdf5'
curvecheck_params['tolerance'] = 1e-10
curvecheck_params['time_units'] = 'milliseconds'
curvecheck_params['curves'] = [['velocity', 'source']]

It then enters over the requested partitioning schemes:

partitions = ((1, 1, 1), (2, 2, 2), (3, 3, 3))

decks = [
TestDeck(
name="sedov_finiteStrain_smoke",
description="Test the basic sedov problem and restart capabilities",
partitions=partitions,
restart_step=50,
check_step=100,
restartcheck_params=RestartcheckParameters(**restartcheck_params),
curvecheck_params=CurveCheckParameters(**curvecheck_params))
]

generate_geos_tests(decks)

and registers a unique test case with the TestDeck method, which accepts the following arguments:
• name : The name of the test
• description : A brief description of the test
• partitions : A list of partition schemes to be tested
• restart_step : The cycle number where GEOS should test its restart capability
• check_step : The cycle number where GEOS should evaluate output files
• restartcheck_params : Parameters to forward to the restart check (tolerance, etc.)
• curvecheck_params: Parameters to forward to the curve check (tolerance, etc.)

ò Note

An .ats file can create any number of tests and link to any number of input xml files. For any given test step, we
expect that at least one restart or curve check be defined.

Creating a New Test Directory

To add a new set of tests, create a new folder under the GEOS/inputFiles directory. This folder needs to include at
least one .ats file to be included in the integrated tests. Using the sedov example, after creating sedov.ats the directory
should look like

586 Chapter 1. Table of Contents

GEOS Documentation

- inputFiles/solidMechanics
- sedov.ats
- sedov.xml

These changes will be reflected in the new baselines after triggering the manual rebaseline step.

Rebaselining Tests

Occasionally you may need to add or update baseline files in the repository (possibly due to feature changes in the
code). This process is called rebaselining. We suggest the following workflow:
1. Open a pull request for your branch on github and select the ci: run integrated tests label
2. Wait for the tests to finish
3. Download and unpack the new baselines from the link provided at the bottom of the test logs
4. Inspect the test results using the test_results.html file
5. Verify that the changes in the baseline files are desired
6. Update the baseline ID in the GEOS/.integrated_tests.yaml file
7. Add a justification for the baseline changes to the GEOS/BASELINE_NOTES.md file
8. Commit your changes and push the code
9. Wait for the CI tests to re-run and verify that the integrated tests step passed

Tips

Parallel Tests: On some development machines geosxats won’t run parallel tests by default (e.g. on an linux laptop or
workstation), and as a result many baselines will be skipped. We highly recommend running tests and rebaselining on
an MPI-aware platform.
Filtering Checks: A common reason for rebaselining is that you have changed the name of an XML node in the input
files. While the baselines may be numerically identical, the restarts will fail because they contain different node names.
In this situation, it can be useful to add a filter to the restart check script using the geos_ats.sh script (see the -e and -m
options in Override Test Behavior )

Benchmarks
In addition to the integrated tests which track code correctness we have a suite of benchmarks that track performance.

Running the benchmarks

Because performance is system specific we currently only support running the benchmarks on the LLNL machines
Quartz and Lassen. If you are on either of these machines the script benchmarks/runBenchmarks.py can be used
to run the benchmarks.

> python ../benchmarks/runBenchmarks.py --help

usage: runBenchmarks.py [-h] [-t TIMELIMIT] [-o TIMINGCOLLECTIONDIR]
[-e ERRORCOLLECTIONDIR]
geosxPath outputDirectory

positional arguments:
geosxPath The path to the GEOS executable to benchmark.
outputDirectory The parent directory to run the benchmarks in.
(continues on next page)

1.6. Developer Guide 587

GEOS Documentation

(continued from previous page)

optional arguments:
-h, --help show this help message and exit
-t TIMELIMIT, --timeLimit TIMELIMIT
Time limit for the entire script in minutes, the
default is 60.
-o TIMINGCOLLECTIONDIR, --timingCollectionDir TIMINGCOLLECTIONDIR
Directory to copy the timing files to.
-e ERRORCOLLECTIONDIR, --errorCollectionDir ERRORCOLLECTIONDIR
Directory to copy the output from any failed runs to.

At a minimum you need to pass the script the path to the GEOS executable and a directory to run the benchmarks in.
This directory will be created if it doesn’t exist. The script will collect a list of benchmarks to be run and submit a
job to the system’s scheduler for each benchmark. This means that you don’t need to be in an allocation to run the
benchmarks. Note that this is different from the integrated tests where you need to already be in an allocation and an
internal scheduler is used to run the individual tests. Since a benchmark is a measure of performance to get consistent
results it is important that each time a benchmark is run it has access to the same resources. Using the system scheduler
guarantees this.
In addition to whatever outputs the input would normally produce (plot files, restart files, . . . ) each benchmark will
produce an output file output.txt containing the standard output and standard error of the run and a .cali file
containing the Caliper timing data in a format that Spot can read.

ò Note

A future version of the script will be able to run only a subset of the benchmarks.

Specifying a benchmark

A group of benchmarks is specified with a standard GEOS input XML file with an extra Benchmarks block added at
the top level. This block is ignored by GEOS itself and only used by the runBenchmarks.py script.
<Benchmarks>
<quartz>
<Run
name="OMP"
nodes="1"
tasksPerNode="1"
timeLimit="10"
autoPartition="On"/>
<Run
name="MPI_OMP"
autoPartition="On"
timeLimit="10"
nodes="1"
tasksPerNode="2"
scaling="strong"
scaleList="{ 1, 2, 4, 8 }"/>
<Run
name="MPI"
autoPartition="On"
timeLimit="10"
(continues on next page)

588 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

nodes="1"
tasksPerNode="36"
scaling="strong"
scaleList="{ 1, 2, 4, 8 }"/>
</quartz>

[Source: benchmarks/SSLE-small.xml]
The Benchmarks block consists of a block for each machine the benchmarks are to run on. Currently the only options
are quartz, lassen, and crusher.

The Run block

Each machine block contains a number of Run blocks each of which specify a family of benchmarks to run. Each Run
block must have the following required attributes
• name: The name of the family of benchmarks, must be unique among all the other Run blocks on that system.
• nodes: An integer which specifies the base number of nodes to run the benchmark with.
• tasksPerNode: An integer that specifies the number of tasks to launch per node.
Each Run block may contain the following optional attributes
• threadsPerTask: An integer specifying the number of threads to allocate each task.
• timeLimit: An integer specifying the time limit in minutes to pass to the system scheduler when submitting the
benchmark.
• args: containing any extra command line arguments to pass to GEOS.
• autoPartition: Either On or Off, not specifying autoPartition is equivalent to autoPartition="Off".
When auto partitioning is enabled the script will compute the number of x, y and z partitions such that the
the resulting partition is close to a perfect cube as possible, ie with 27 tasks x = 3, y = 3, z = 3 and with
36 tasks x = 4, y = 3, z = 3. This is optimal when the domain itself is a cube, but will be suboptimal
otherwise.
• strongScaling: A list of unique integers specifying the factors to scale the number of nodes by. If N number
are provided then N benchmarks are run and benchmark i uses nodes * strongScaling[ i ] nodes. Not
specifying strongScaling is equivalent to strongScaling="{ 1 }".

1.6. Developer Guide 589

GEOS Documentation

Looking at the example Benchmarks block above on Lassen one benchmark from the OMP_CUDA family will be run
with one node and one task. Four benchmarks from the MPI_OMP_CUDA family will be run with one, two, four and
eight nodes and four tasks per node.
Note that specifying a time limit for each benchmark family can greatly decrease the time spent waiting in the scheduler’s
queue. A good rule of thumb is that the time limit should be twice as long as it takes to run the longest benchmark in
the family.

Adding a benchmark problem

To add a new group of benchmarks you need to create an XML input file describing the problem to be run. Then you
need to add the Benchmarks block described above which specifies the specific benchmarks. Finally add a symbolic
link to the input file in benchmarks and run the benchmarks to make sure everything works as expected.

Viewing the results

Each night the NightlyTests repository runs the benchmarks on both Quartz and Lassen, the timingFiles directory
contains all of the resulting caliper output files. If you’re on LC then these files are duplicated at /usr/gapps/GEOSX/
timingFiles/ and if you have LC access you can view them in Spot. You can also open these files in Python and
analyse them (See Opening Spot caliper files in Python).
If you want to run the benchmarks on your local branch and compare the results with develop you can use the
benchmarks/compareBenchmarks.py python script. This requires that you run the benchmarks on your branch
and on develop. It will print out a table with the initialization time speed up and run time speed up, so a run speed up
of of 2x means your branch runs twice as fast as develop where as a initialization speed up of 0.5x means the set up
takes twice as long.

ò Note

A future version of the script will be able to pull timing results straight from the .cali files so that if you have
access to the NightlyTests timing files you won’t need to run the benchmarks on develop. Furthermore it will be
able to provide more detailed information than just initialization and run times.

Basic profiling with CALIPER

GEOS is equipped with Caliper timers. We integrate Caliper into GEOS by marking source-code sections of interest
such as computational kernels or initialization steps. Caliper is included in the GEOS TPL library and is built by adding
the following cmake configuration to a host-config file.

option( ENABLE_CALIPER "Enables CALIPER" On )

GEOS/Caliper Annotation Macros

The following macros may be used to annotate GEOS:

• GEOS_MARK_SCOPE(name) - Marks a scope with the given name.
• GEOS_MARK_FUNCTION - Marks a function with the name of the function. The name includes the namespace the
function is in but not any of the template arguments or parameters. Therefore overloaded function all show up
as one entry. If you would like to mark up a specific overload use GEOS_MARK_SCOPE with a unique name.
• GEOS_MARK_BEGIN(name) - Marks the beginning of a user defined code region.
• GEOS_MARK_END(name) - Marks the end of user defined code region.
The 2 first macros also generate annotations for NVTX is ENABLE_CUDA_NVTOOLSEXT is activated through
CMake.

590 Chapter 1. Table of Contents

GEOS Documentation

Configuring Caliper

Caliper configuration is done by specifying a string to initialize Caliper with via the -t option. A few options are listed
below but we refer the reader to Caliper Config for the full Caliper tutorial.
• -t runtime-report,max_column_width=200 Will make Caliper print aggregated timing information to
standard out, with a column width large enought that it doesn’t truncate most function names.
• -t runtime-report,max_column_width=200,profile.cuda Does the same as the above, but also instru-
ments CUDA API calls. This is only an option when building with CUDA.
• -t runtime-report,aggregate_across_ranks=false Will make Caliper write per rank timing informa-
tion to standard out. This isn’t useful when using more than one rank but it does provide more information for
single rank runs.
• -t spot() Will make Caliper output a .cali timing file that can be viewed in the Spot web server.

Using Adiak

Adiak is a library that allows the addition of meta-data to the Caliper Spot output, it is enabled with Caliper. This
meta-data allows you to easily slice and dice the timings available in the Spot web server. To export meta-data use the
adiak::value function.
See Adiak API for the full Adiak documentation.

Using Spot

To use Spot you will need an LC account and a directory full of .cali files you would like to analyse. Point your browser
to Spot and open up the directory containing the timing files.

Opening Spot caliper files in Python

An example Python program for analyzing Spot Caliper files in Python is provided below. Note that it requires pandas
and hatchet both of which can be installed with a package manager. In addition it requires that cali-query is in the
PATH variable, this is built with Caliper so we can just point it into the TPLs.

import sys
import subprocess
import json
import os

import pandas as pd
from IPython.display import display, HTML

# Import hatchet, on LC this can be done by adding hatchet to PYTHONPATH

sys.path.append('/usr/gapps/spot/live/hatchet')
import hatchet as ht

# Add cali-query to PATH

cali_query_path = "/usr/gapps/GEOSX/thirdPartyLibs/2020-06-12/[email protected]
˓→release/caliper/bin"

os.environ["PATH"] += os.pathsep + cali_query_path

CALI_FILES = [
{ "cali_file": "/usr/gapps/GEOSX/timingFiles/200612-04342891243.cali", "metric_name":
˓→"avg#inclusive#sum#time.duration"},

(continues on next page)

1.6. Developer Guide 591

GEOS Documentation

(continued from previous page)

{ "cali_file": "/usr/gapps/GEOSX/timingFiles/200611-044740108300.cali", "metric_name":
˓→"avg#inclusive#sum#time.duration"},

grouping_attribute = "prop:nested"
default_metric = "avg#inclusive#sum#time.duration"
query = "select %s,sum(%s) group by %s format json-split" % (grouping_attribute, default_
˓→metric, grouping_attribute)

gf1 = ht.GraphFrame.from_caliper(CALI_FILES[0]['cali_file'], query)

gf2 = ht.GraphFrame.from_caliper(CALI_FILES[1]['cali_file'], query)

# Print the tree representation using the default metric

# Also print the resulting dataframe with metadata
print(gf1.tree(color=True, metric="sum#"+default_metric))
display(HTML(gf1.dataframe.to_html()))

# Print the tree representation using the default metric

# Also print the resulting dataframe with metadata
print(gf2.tree(color=True, metric="sum#"+default_metric))
display(HTML(gf2.dataframe.to_html()))

# Compute the speedup between the first two cali files (exlusive and inclusive metrics␣
˓→only)

gf3 = (gf1 - gf2) / gf2

print(gf3.tree(color=True, metric="sum#"+default_metric))

# Compute the difference between the first two cali files (exclusive and inclusive␣
˓→metrics only)

# Print the resulting tree

gf4 = gf1 - gf2
print(gf4.tree(color=True, metric="sum#"+default_metric))

# Compute the sum of the first two cali files (exclusive and inclusive metrics only)
# Print the resulting tree
gf5 = gf1 + gf2
print(gf5.tree(color=True, metric="sum#"+default_metric))

[Best effort] Developing inside Docker with precompiled TPL binaries

For development purposes, you may want to use the publicly available docker images instead of compiling them your-
self. While this is possible and this page will help you in through this journey, please note that this is not officially
supported by the GEOS team that reserves the right to modify its workflow or delete elements on which you may have
build your own workflow.
There are multiple options to use the exposed docker images.
• A lot of IDE now provide remote development modes (e.g. CLion, VS Code, Eclipse Che and surely others).
Depending on your choice, please read their documentation carefully so you can add their own requirements on
top the TPL images that are already available.
• Another option is to develop directly inside the container (i.e. not remotely). Install your favorite development
inside the image (be mindful of X display issues), connect to the running container and start hacking!
• It is also possible to develop directly in the cloud using GitHub codespaces. This product will let you buy

592 Chapter 1. Table of Contents

GEOS Documentation

a machine in the cloud with an environment already configured to build and run geos. The submodules are
automatically cloned (except for the integratedTests which you may need to init yourself if you really need
them, see .devcontainer/postCreateCommand.sh). You do not need to run the scripts/config-build.py
scripts since cmake and vscode are already configured. Last, run cmake through the vscode interface and start
hacking!
You must first install docker on your machine. Note that there now exists a rootless install that may help you in case you
are not granted extended permissions on your environment. Also be aware that nvidia provides its own nvidia-docker
that grants access to GPUs.
Once you’ve installed docker, you must select from our docker registry the target environment you want to develop into.
• You can select the distribution you are comfortable with, or you may want to mimic (to some extend) a production
environment.
• Our containers are built with a relative CPU agnosticism (still x86_64), so you should be fine.
• Our GPU containers are built for a dedicated compute capability that may not match yours. Please dive into
our configuration files and refer to the official nvidia page to see what matches your needs.
• There may be risks of kernel inconsistency between the container and the host, but if you have relatively modern
systems (and/or if you do not interact directly with the kernel like perf) it should be fine.
• You may have noticed that our docker containers are tagged like 224-965. Please refer to Continuous Integration
process for further information.
Now that you’ve selected your target environment, you must be aware that just running a TPL docker image is not
enough to let you develop. You’ll have to add extra tools.
The following example is for our ubuntu flavors. You’ll notice the arguments IMG, VERSION, ORG. While surely overkill
for most cases, if you develop in GEOS on a regular basis you’ll appreciate being able to switch containers easily. For
example, simply create the image remote-dev-ubuntu20.04-gcc9:224-965 by running

export VERSION=224-965
export IMG=ubuntu20.04-gcc9
export REMOTE_DEV_IMG=remote-dev-${IMG}
docker build --build-arg ORG=geosx --build-arg IMG=${IMG} --build-arg VERSION=${VERSION}␣
˓→-t ${REMOTE_DEV_IMG}:${VERSION} -f /path/to/Dockerfile .

And the Dockerfile is the following (comments are embedded)

1 # Define you base image for build arguments

2 ARG IMG
3 ARG VERSION
4 ARG ORG
5 FROM ${ORG}/${IMG}:${VERSION}
6

7 # Uninstall some packages, install others.

8 # I use those for clion, but VS code would have different requirements.
9 # Use yum's equivalent commands for centos/red-hat images.
10 # Feel free to adapt.
11 RUN apt-get update
12 RUN apt-get remove --purge -y texlive graphviz
13 RUN apt-get install --no-install-recommends -y openssh-server gdb rsync gdbserver ninja-
˓→build

15 # You may need to define your time zone. This is a way to do it. Please adapt to your␣
˓→own needs.

(continues on next page)

1.6. Developer Guide 593

GEOS Documentation

(continued from previous page)

16 RUN ln -fs /usr/share/zoneinfo/America/Los_Angeles /etc/localtime && \
17 dpkg-reconfigure -f noninteractive tzdata
18

19 # You will need cmake to build GEOSX.

20 ARG CMAKE_VERSION=3.23.3
21 RUN apt-get install -y --no-install-recommends curl ca-certificates && \
22 curl -fsSL https://cmake.org/files/v${CMAKE_VERSION%.[0-9]*}/cmake-${CMAKE_VERSION}-
˓→linux-x86_64.tar.gz | tar --directory=/usr/local --strip-components=1 -xzf - && \

23 apt-get purge --auto-remove -y curl ca-certificates

24 RUN apt-get autoremove -y
25

26 # You'll most likely need ssh/sshd too (e.g. CLion and VSCode allow remote dev through␣
˓→ssh).

27 # This is the part where I configure sshd.

29 # The default user is root. If you plan your docker instance to be a disposable␣
˓→environment,

30 # with no sensitive information that a split between root and normal user could protect,
31 # then this is a choice which can make sense. Make your own decision.
32 RUN echo "PermitRootLogin prohibit-password" >> /etc/ssh/sshd_config
33 RUN echo "PermitUserEnvironment yes" >> /etc/ssh/sshd_config
34 RUN mkdir -p -m 700 /root/.ssh
35 # Put your own public key here!
36 RUN echo "ssh-rsa AAAAB... your public ssh key here ...EinP5Q== [email protected]" >
˓→ /root/.ssh/authorized_keys

38 # Some important variables are provided through the environment.

39 # You need to explicitly tell sshd to forward them.
40 # Using these variables and not paths will let you adapt to different installation␣
˓→locations in different containers.

41 # Feel free to adapt to your own convenience.

42 RUN touch /root/.ssh/environment &&\
43 echo "CC=${CC}" >> /root/.ssh/environment &&\
44 echo "CXX=${CXX}" >> /root/.ssh/environment &&\
45 echo "MPICC=${MPICC}" >> /root/.ssh/environment &&\
46 echo "MPICXX=${MPICXX}" >> /root/.ssh/environment &&\
47 echo "MPIEXEC=${MPIEXEC}" >> /root/.ssh/environment &&\
48 echo "OMPI_CC=${CC}" >> /root/.ssh/environment &&\
49 echo "OMPI_CXX=${CXX}" >> /root/.ssh/environment &&\
50 echo "GEOS_TPL_DIR=${GEOS_TPL_DIR}" >> /root/.ssh/environment
51 # If you decide to work as root in your container, you may consider adding
52 # `OMPI_ALLOW_RUN_AS_ROOT=1` and `OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1`
53 # to your environment. This will prevent you from adding the `--allow-run-as-root` option
54 # when you run mpi. Of course, weigh the benefits and risks and make your own decision.
55

56 # In case you want to use `sccache` (https://github.com/mozilla/sccache) to make your␣

˓→builds faster,

57 # you may configure the `sccache` config file at your convenience.

58 # Meanwhile, we provide here a simple local configuration.
59 RUN mkdir -p ${HOME}/.config/sccache
60 RUN printf '[cache.disk]\n\
61 dir = "/tmp/.cache/sccache"\n\
(continues on next page)

594 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

62 size = 3221225472 # 3GB\n' > ${HOME}/.config/sccache/config
63

64 # Default ssh port 22 is exposed. For _development_ purposes,

65 # it can be useful to expose other ports for remote tools.
66 EXPOSE 22 11111 64010-64020
67 # sshd's option -D prevents it from detaching and becoming a daemon.
68 # Otherwise, sshd would not block the process and `docker run` would quit.
69 RUN mkdir -p /run/sshd
70 ENTRYPOINT ["/usr/sbin/sshd", "-D"]

Now that you’ve created the image, you must instantiate it as a container. I like to do

docker run --cap-add=SYS_PTRACE -d --name ${REMOTE_DEV_IMG}-${VERSION} -p 64000:22 -p␣

˓→11111:11111 -p 64010-64020:64010-64020 ${REMOTE_DEV_IMG}:${VERSION}

that creates the container remote-dev-ubuntu20.04-gcc9-224-965, running instance of

remote-dev-ubuntu20.04-gcc9:224-965.
• Note that you’ll have to access your remote development instance though port 64000 (forwarded to standard port
22 by docker).
• Additional port 11111 and ports from 64010 to 64020 will be open if you need them (remote paraview connec-
tion , multiple instances of gdbserver, . . . ).
• Please be aware of how to retrieve your code back: you may want to bind mount volumes and store you code
there (-v/--volume= options of docker run).
• Change docker to nvidia-docker and add the --gpus=... option for GPUs.
You can stop and restart your container with

docker stop ${REMOTE_DEV_IMG}-${VERSION}

docker start ${REMOTE_DEV_IMG}-${VERSION}

Now hack.

[Best effort] Installing GEOS on Windows machines using Docker

In this section, we will install GEOS on a Windows machine using a Docker container with a precompiled version of
GEOS’s third party libraries (TPL). These steps are an adaptation of ref:UsingDocker for the Windows environment.
In the following sections, we will be using Ubuntu based image as an example.

1. Install Docker Desktop

On your Windows machine, follow these steps. Download the most recent installer for Docker Desktop. Before instal-
lation please check the current status of Windows Subsystem for Linux ( WSL ) on your machine as Docker will use
WSL2 as a backend. To do that, open a PowerShell(Admin)

PS > wsl --install

PS > wsl --status
PS > wsl --set-default-version 2
PS > wsl --status

The first command should install WSL2, download an Ubuntu distribution for it and ask for a restart. The following
commands are used to check the status, and if the WSL is still the default one, change it to WSL2. More details on the
installation procedure can be found here.

1.6. Developer Guide 595

GEOS Documentation

Once the WSL2 is set as default, proceed with the Docker Desktop installation.

2. Start Docker Desktop

When launching Docker Desktop for the first time, you should be prompted with a message informing you that it uses
WSL2. Using PowerShell, you can check that Docker and WSL2 are actually running in the background:

PS > Get-Process docker

Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName
------- ------ ----- ----- ------ -- -- -----------
123 11 26084 25608 0.42 13960 1 docker

PS > Get-Process wsl

Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName
------- ------ ----- ----- ------ -- -- -----------
146 8 1412 6848 0.05 14816 1 wsl
146 7 1356 6696 0.02 15048 1 wsl
145 7 1368 6704 0.02 15100 1 wsl
145 7 1352 6716 0.14 15244 1 wsl
146 7 1396 6876 0.02 16156 1 wsl

You should be able to see one docker process and several wsl processes.

3. Preparing DockerFile

Let us now prepare the installation, picking a destination folder and editing our Dockerfile:

PS > cd D:/
PS > mkdir install-geosx-docker
PS > cd install-geosx-docker/
PS > notepad.exe Dockerfile

Let us edit the Dockerfile, which is the declarative file for out container:

1 # Define you base image for build arguments

2 ARG IMG
3 ARG VERSION
4 ARG ORG
5 FROM ${ORG}/${IMG}:${VERSION}
6

7 # Uninstall some packages, install others.

15 # You may need to define your time zone. This is a way to do it. Please adapt to your␣
˓→own needs.

16 RUN ln -fs /usr/share/zoneinfo/America/Los_Angeles /etc/localtime && \

17 dpkg-reconfigure -f noninteractive tzdata
18

(continues on next page)

596 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

19 # You will need cmake to build GEOSX.
20 ARG CMAKE_VERSION=3.23.3
21 RUN apt-get install -y --no-install-recommends curl ca-certificates && \
22 curl -fsSL https://cmake.org/files/v${CMAKE_VERSION%.[0-9]*}/cmake-${CMAKE_VERSION}-
˓→linux-x86_64.tar.gz | tar --directory=/usr/local --strip-components=1 -xzf - && \

23 apt-get purge --auto-remove -y curl ca-certificates

24 RUN apt-get autoremove -y
25

26 # You'll most likely need ssh/sshd too (e.g. CLion and VSCode allow remote dev through␣
˓→ssh).

27 # This is the part where I configure sshd.

29 # The default user is root. If you plan your docker instance to be a disposable␣
˓→environment,

38 # Some important variables are provided through the environment.

39 # You need to explicitly tell sshd to forward them.
40 # Using these variables and not paths will let you adapt to different installation␣
˓→locations in different containers.

41 # Feel free to adapt to your own convenience.

56 # In case you want to use `sccache` (https://github.com/mozilla/sccache) to make your␣

˓→builds faster,

57 # you may configure the `sccache` config file at your convenience.

58 # Meanwhile, we provide here a simple local configuration.
59 RUN mkdir -p ${HOME}/.config/sccache
60 RUN printf '[cache.disk]\n\
61 dir = "/tmp/.cache/sccache"\n\
62 size = 3221225472 # 3GB\n' > ${HOME}/.config/sccache/config
63

64 # Default ssh port 22 is exposed. For _development_ purposes,

(continues on next page)

1.6. Developer Guide 597

GEOS Documentation

(continued from previous page)

This file enriches a base image already containing the GEOS’s TPL as well as extra utils, such as cmake and preparing
for ssh connexion. In the end, we will be able to run it in a detached mode, and connect to it to run and develop in
GEOS.
There are two things you may have noticed reading through the Dockerfile :
• It has environment variables to be passed to it to select the proper image to pull, namely ${ORG}, ${IMG} and
${VERSION}, we’ll then have to declare them

PS> $env:VERSION='224-965'
PS> $env:IMG='ubuntu20.04-gcc9'
PS> $env:REMOTE_DEV_IMG="remote-dev-${env:IMG}"

Please note the preposition of env: in the windows formalisme. The ${ORG} variable will be hard-coded as geosx.
The last variable will be use as the image name. 224-965 refers to a specific version of the TPLs which may not be up
to date. Please refer to Continuous Integration process for further info.
• You’ll need to generate a ssh-key to be able to access the container without the need for defining a password.
This can be done from the PowerShell,

PS > ssh-keygen.exe
PS > cat [path-to-gen-key]/[your-key].pub

The first command will prompt you with a message asking you to complete the desired path for the key as well as a
passphrase, with confirmation. More details on ssh-key generation.

4. Build the image and run the container

The preliminary tasks are now done. Let us build the image that will be containerized.

PS> cd [path-to-dockerfile-folder]/
PS > docker build --build-arg ORG=geosx --build-arg IMG=${env:IMG} --build-arg VERSION=$
˓→{env:VERSION} -t ${env:REMOTE_DEV_IMG}:${env:VERSION} -f Dockerfile .

As described above, we are passing our environment variables in the building stage, which offer the flexibility of
changing the version or image by a simple redefinition. A log updating or pulling the different layers should be displayed
afterwards and on the last line the image id. We can check that the image is created using PowerShell CLI:

PS > docker images

or using the Docker Desktop

598 Chapter 1. Table of Contents

GEOS Documentation

Now that we have the image build, let us run a container from,

PS > docker run --cap-add=SYS_PTRACE -d --name ${env:REMOTE_DEV_IMG}-${env:VERSION} -p␣

˓→64000:22 --mount 'type=bind,source=D:/install_geosx_docker/,target=/app' ${env:REMOTE_

˓→DEV_IMG}:${env:VERSION}

Note that in addition to the detached flag (-d) and the name tage (--name), we provide Docker with the port the
container should be associated to communicate with ssh port 22, as well as a binding between a host mount point (D:/
install_geosx_docker/) and a container mount point (/app) to have a peristent storage for our development/geosx
builds. More details on the –mount options
A similar step can be achieved using the Docker Desktop GUI in the image tabs, clicking on the run button and filling
the same information in the interface,

Coming back to our PowerShell terminal, we can check that our container is running and trying to ssh to it.

PS > docker ps -a
CONTAINER ID IMAGE COMMAND CREATED ␣
˓→ STATUS PORTS NAMES
1efffac66c4c remote-dev-ubuntu20.04-gcc9:224-965 "/usr/sbin/sshd -D" Less than a␣
˓→second ago Up 18 seconds 0.0.0.0:64000->22/tcp, :::64000->22/tcp remote-dev-
˓→ubuntu20.04-gcc9-224-965

PS > ssh root@localhost -p 64000

Enter passphrase for key 'C:\***********/.ssh/id_rsa':
Welcome to Ubuntu 18.04.5 LTS (GNU/Linux 5.10.16.3-microsoft-standard-WSL2 x86_64)

* Documentation: https://help.ubuntu.com
* Management: https://landscape.canonical.com
* Support: https://ubuntu.com/advantage
This system has been minimized by removing packages and contents that are
not required on a system that users do not log into.

(continues on next page)

1.6. Developer Guide 599

GEOS Documentation

(continued from previous page)

To restore this content, you can run the 'unminimize' command.

The programs included with the Ubuntu system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by

applicable law.

root@b105f9ead860:~# cd /app && ls

We are now logged into our container and can start Quick Start Guide.

ò Note

Note that :
1. You might be prompted that you miss certificates to clone, this can be resolved by installing
ca-certificates and updating them
2. It might occur that git-lfs is missing then install it
PS > apt install ca-certificates && update-ca-certificates
PS > apt install git-lfs

From there you should be able to develop in your container or access it from an IDE, e.g. VSCode or MSVC19.

5. Running a case

Once the code is configured and compiled, let us check the status of the build,

root@b105f9ead860:~# cd [path-to-build]/ && ./bin/geosx --help

Trying to launch a case using mpirun, you might get the following warning

root@b105f9ead860:/tmp# mpirun -np 4 /app/code/GEOS/build-environment-debug/bin/geosx -i␣

˓→[geosx-case].xml -x 4 -y1 -z1

--------------------------------------------------------------------------
mpirun has detected an attempt to run as root.
Running at root is *strongly* discouraged as any mistake (e.g., in
defining TMPDIR) or bug can result in catastrophic damage to the OS
file system, leaving your system in an unusable state.

You can override this protection by adding the --allow-run-as-root

option to your cmd line. However, we reiterate our strong advice
against doing so - please do so at your own risk.
--------------------------------------------------------------------------

A possible workaround is to create a new user account and a run folder from this account

root@b105f9ead860:~# adduser runner

root@b105f9ead860:~# su runner
runner@b105f9ead860:/root$ mkdir -p /tmp/geosx && cd /tmp/geosx/
(continues on next page)

600 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

runner@b105f9ead860:/tmp/geosx$ cp [path-to-case]/[geosx-case].xml .
runner@b105f9ead860:/tmp/geosx$ ${MPIEXEC} -np 4 /app/code/GEOS/build-environment-debug/
˓→bin/geosx -i [geosx-case].xml -x 4 -y 1 -z 1

How to work interactively on the CI Machines

When developing with GEOS, developers may sometimes face compilation errors or test failures that only manifest in
specific Continuous Integration (CI) builds. To effectively troubleshoot these issues, it’s advisable to debug directly
in the target environment. The preferred method involves using Docker to locally replicate the problematic image.
However, for those without Docker access on their machines, (or for cases inherently related to the CI configuration),
an alternative is to establish a connection to the CI machines. Here are the steps to do so:

Step 1: Adding a GHA to establish a connection

First, as much as you can, try to reduce the number of jobs you’re triggering by commenting out the configurations you
do not require for your debugging. Then in your branch, add the following GHA step to the .github/build_and_test.yml
(see full documentation of the action here <https://github.com/lhotari/action-upterm>_).

- name: ssh
uses: lhotari/action-upterm@v1
with:
## limits ssh access and adds the ssh public key for the user which triggered the␣
˓→workflow

limit-access-to-actor: true
## limits ssh access and adds the ssh public keys of the listed GitHub users
limit-access-to-users: GitHubLogin

The action should be added after whichever step triggers an error. In case of a build failure it is best to add the action
after the build, test and deploy step. It is also important to prevent the job to exit upon failure. For instance, it is
suggested to comment the following lines in the build, test and deploy step.

set -e

exit ${EXIT_STATUS}

You can now commit the changes and push them to your remote branch.

Step 2: Inspect the CI and grab server address

Run lhotari/action-upterm@v1
upterm

Auto-generating ~/.ssh/known_hosts by attempting connection to uptermd.upterm.dev

Pseudo-terminal will not be allocated because stdin is not a terminal.

Warning: Permanently added 'uptermd.upterm.dev' (ED25519) to the list of known hosts.

[email protected]: Permission denied (publickey).

Adding actor "GitHubLogin" to allowed users.

Fetching SSH keys registered with GitHub profiles: GitHubLogin
Fetched 2 ssh public keys
(continues on next page)

1.6. Developer Guide 601

GEOS Documentation

(continued from previous page)

Creating a new session. Connecting to upterm server ssh://uptermd.upterm.dev:22
Created new session successfully
Entering main loop
=== Q16OBOFBLODJVA3TRXPL
Command: tmux new -s upterm -x 132 -y 43
Force Command: tmux attach -t upterm

Host: ssh://uptermd.upterm.dev:22
SSH Session: ssh␣
˓→Q16oBofblOdjVa3TrXPl:ZTc4NGUxMWRiMjI5MDgudm0udXB0ZXJtLmludGVybmFsOjIyMjI=@uptermd.

˓→upterm.dev

Step 3: Connect to the machine via ssh

You can now open a terminal in your own machine and sshe to the upterm server, e.g.,

ssh Q16oBofblOdjVa3TrXPl:ZTc4NGUxMWRiMjI5MDgudm0udXB0ZXJtLmludGVybmFsOjIyMjI=@uptermd.
˓→upterm.dev

Step 4: Run the docker container interactively

Once you are connected to the machine it is convenient to follow these steps to interactively run the docker container:

docker ps -a

The id of the existing docker container will be displayed and you can use it to commit the container.

docker commit <id> debug_image

and then run it interactively, e.g.

docker run -it --volume=/home/runner/work/GEOS/GEOS:/tmp/geos -e ENABLE_HYPRE=ON -e␣

˓→ENABLE_HYPRE_DEVICE=CUDA -e ENABLE_TRILINOS=OFF --cap-add=SYS_PTRACE --entrypoint /bin/

˓→bash debug_image

Step 5: Cancel the workflow

Once you are done, do not forget to cancel the workflow!

1.6.2 Code Components

The main code components are described here.

Data Repository
The GEOS “Data Repository” is intended to provide the building blocks for the code structure within GEOS. The
“Data Repository” provides a general capability to store arbitrary data and objects in a hierarchical structure, similar to
a standard file system. The “Wrapper” object is a generic container for any object, and provides a standard interface for
accessing an object and performing standard operations. The “Group” object is a container for “Wrapper” and other
“Group” objects.
The components/classes of the data structure that a developer should have some knowledge of are:

602 Chapter 1. Table of Contents

GEOS Documentation

Group

dataRepository::Group serves as a base class for most objects in GEOS. In GEOS, the Group may be thought of as
an analogy to the file folder in a hierachical filesystem-like structure. As such, a Group is used as a container class that
holds a collection of other Groups, or sub-Groups, a pointer to the parent of the Group, and a collection of Wrappers.
The Group also defines a general capability to create and traverse/access the objects in the hierarchy. The Wrappers
contained in a Group may be of arbitrary type, but in the case of an LvArray object, a Group size and capacity may
be translated down to array, thereby keeping a collection of wrapped Array objects that will resize in unison with the
Group. Each group has a string “name” that defines its key in the parent Group. This key string must be unique in the
scope of the parent Group.

Implementation Details

Some noteworthy implementation details inside the declaration of dataRepository::Group are:

/// The default key type for entries in the hierarchy.

using keyType = string;

/// The default index type for entries the hierarchy.

using indexType = localIndex;

• In the GEOS repository, the keyType is specified to be a string for all collection objects, while the indexType
is specified to be a localIndex. The types are set in the common/DataTypes.hpp file, but are typically a
string and a std::ptrdiff_t respectively.

/// The template specialization of MappedVector to use for the collection of sub-Group␣
˓→objects.
using subGroupMap = MappedVector< Group, Group *, keyType, indexType >;

/// The template specialization of MappedVector to use for the collection wrappers␣
˓→objects.
using wrapperMap = MappedVector< WrapperBase, WrapperBase *, keyType, indexType >;

• The subGroupMap and wrapperMap aliases represent the type of container that the collection of sub-Group s and
Wrapper s are stored in for each Group. These container types are template specializations of the MappedVector
class, which store a pointer to a type, and provides functionality for a key or index based lookup. More details
may be found in the documentation for MappedVector.

/// The parent Group that contains "this" Group in its "sub-Group" collection.
Group * m_parent = nullptr;

/// Specification that this group will have the same m_size as m_parent.
integer m_sizedFromParent;

/// The container for the collection of all wrappers continued in "this" Group.
wrapperMap m_wrappers;

/// The container for the collection of all sub-groups contained in "this" Group.
subGroupMap m_subGroups;

/// The size/length of this Group...and all Wrapper<> that are are specified to have␣
˓→the same size as their
/// owning group.
indexType m_size;
(continues on next page)

1.6. Developer Guide 603

GEOS Documentation

(continued from previous page)

/// The capacity for wrappers in this group...and all Wrapper<> that are specified to␣
˓→have the same size as their
/// owning group.
indexType m_capacity;

/// The name/key of this Group in its parent collection of sub-Groups.

string m_name;

/// Verbosity flag for group logs

integer m_logLevel;

• The m_parent member is a pointer to the Group that contains the current Group as part of its collection of
sub-Group s.

. Warning

The existence of the non-const m_parent gives the current Group access to alter the parent Group. Special
care should be taken to avoid using this access whenever possible. Remember. . . with great power comes
great responsibility.

• The m_wrappers member is the collection of Wrappers contained in the current Group.
• The m_subGroups member is the collection of Group s contained in the current Group.
• The m_size and m_capacity members are used to set the size and capacity of any objects contained in the
m_wrappers collection that have been specified to be set by their owning Group. This is typically only useful
for Array types and is implemented within the WrapperBase object.
• The m_name member is the key of this Group in the collection of m_parent->m_subGroups. This key is unique
in the scope of m_parent, so some is required when constructing the hierarchy.

Interface Functions

The public interface for dataRepository::Group provides functionality for constructing a hierarchy, and traversing
that hierarchy, as well as accessing the contents of objects stored in the Wrapper containers stored within a Group.

Adding New Groups

To add new sub-Group s there are several registerGroup functions that add a new Group under the calling Group
scope. A listing of these functions is provided:

/**
* @name Sub-group registration interface
*/
///@{

/**
* @brief Register a new Group as a sub-group of current Group.
*
* @tparam T The type of the Group to add/register. This should be a type that derives␣
˓→from Group.

* @param[in] name The name of the group to use as a string key.

(continues on next page)

604 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

* @param[in] newObject A unique_ptr to the object that is being registered.
* @return A pointer to the newly registered Group.
*
* Registers a Group or class derived from Group as a subgroup of this Group and takes␣
˓→ownership.

*/
template< typename T = Group >
T & registerGroup( string const & name, std::unique_ptr< T > newObject )
{
newObject->m_parent = this;
return dynamicCast< T & >( *m_subGroups.insert( name, newObject.release(), true ) );
}

/**
* @brief @copybrief registerGroup(string const &,std::unique_ptr<T>)
*
* @tparam T The type of the Group to add/register. This should be a type that derives␣
˓→from Group.

* @param[in] name The name of the group to use as a string key.

*/
template< typename T = Group >
T & registerGroup( string const & name, T * newObject )
{ return dynamicCast< T & >( *m_subGroups.insert( name, newObject, false ) ); }

/**
* @brief @copybrief registerGroup(string const &,std::unique_ptr<T>)
*
* @tparam T The type of the Group to add/register. This should be a type that derives␣
˓→from Group.

* @param[in] name The name of the group to use as a string key.

* @return A pointer to the newly registered Group.
*
* Creates and registers a Group or class derived from Group as a subgroup of this␣
˓→Group.

*/
template< typename T = Group >
T & registerGroup( string const & name )
{ return registerGroup< T >( name, std::make_unique< T >( name, this ) ); }

/**
* @brief @copybrief registerGroup(string const &,std::unique_ptr<T>)
*
* @tparam T The type of the Group to add/register. This should be a type that derives␣
˓→from Group.

* @param keyIndex A KeyIndexT object that will be used to specify the name of
* the new group. The index of the KeyIndex will also be set.
(continues on next page)

1.6. Developer Guide 605

GEOS Documentation

(continued from previous page)

* @return A pointer to the newly registered Group, or @c nullptr if no group was␣
˓→registered.

*
* Creates and registers a Group or class derived from Group as a subgroup of this␣
˓→Group.

*/
template< typename T = Group >
T & registerGroup( subGroupMap::KeyIndex const & keyIndex )
{
T & rval = registerGroup< T >( keyIndex.key(), std::make_unique< T >( keyIndex.key(),
˓→ this ) );

keyIndex.setIndex( m_subGroups.getIndex( keyIndex.key() ) );

return rval;
}

/**
* @brief @copybrief registerGroup(string const &,std::unique_ptr<T>)
*
* @tparam T The type of the Group to add/register. This should be a type that derives␣
˓→from Group.

* @tparam TBASE The type whose type catalog will be used to look up the new sub-group␣
˓→type

* @param[in] name The name of the group to use as a string key.

* @param[in] catalogName The catalog name of the new type.
* @return A pointer to the newly registered Group.
*
* Creates and registers a Group or class derived from Group as a subgroup of this␣
˓→Group.

*/
template< typename T = Group, typename TBASE = Group >
T & registerGroup( string const & name, string const & catalogName )
{
std::unique_ptr< TBASE > newGroup = TBASE::CatalogInterface::Factory( catalogName,␣
˓→name, this );

return registerGroup< T >( name, std::move( newGroup ) );

}

/**
* @brief Removes a child group from this group.
* @param name the name of the child group to remove from this group.
*/
void deregisterGroup( string const & name );

/**
* @brief Creates a new sub-Group using the ObjectCatalog functionality.
* @param[in] childKey The name of the new object type's key in the
* ObjectCatalog.
* @param[in] childName The name of the new object in the collection of
* sub-Groups.
* @return A pointer to the new Group created by this function.
*/
virtual Group * createChild( string const & childKey, string const & childName );
(continues on next page)

606 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

///@}

These functions all take in a name for the new Group, which will be used as the key when trying to access the Group in
the future. Some variants create a new Group, while some variants take in an existing Group . The template argument
is to specify the actaul type of the Group as it it is most likely a type that derives from Group that is we would like to
create in the repository. Please see the doxygen documentation for a detailed description of each option.

Getting Groups

The collection of functions to retrieve a Group and their descriptions are taken from source and shown here:

/**
* @name Sub-group retrieval methods.
*
* This collection of functions are used to get a sub-Group from the current group.␣
˓→Various methods

* for performing the lookup are provided (localIndex, string, KeyIndex), and each␣
˓→have their

* advantages and costs. The lowest cost lookup is the "localIndex" lookup. The␣
˓→KeyIndex lookup

* will add a cost for checking to make sure the index stored in KeyIndex is valid (a␣
˓→string

* compare, and a hash if it is incorrect). The string lookup is the full cost hash␣
˓→lookup every

* time that it is called.

*
* The template parameter specifies the "type" that the caller expects to lookup, and␣
˓→thus attempts

* to cast the pointer that is stored in m_subGroups to a pointer of the desired type.␣
˓→If this

* cast fails, then a @p nullptr is returned. If no template parameter is specified␣

˓→then a default

* type of Group is assumed.

*/
///@{

/**
* @brief Return a pointer to a sub-group of the current Group.
* @tparam T The type of subgroup.
* @tparam KEY The type of the lookup.
* @param key The key used to perform the lookup.
* @return A pointer to @p T that refers to the sub-group, if the Group does not exist␣
˓→or it

* has an incompatible type a @c nullptr is returned.

*/
template< typename T = Group, typename KEY = void >
T * getGroupPointer( KEY const & key )
{ return dynamicCast< T * >( m_subGroups[ key ] ); }

/**
* @copydoc getGroupPointer(KEY const &)
(continues on next page)

1.6. Developer Guide 607

GEOS Documentation

(continued from previous page)

*/
template< typename T = Group, typename KEY = void >
T const * getGroupPointer( KEY const & key ) const
{ return dynamicCast< T const * >( m_subGroups[ key ] ); }

/**
* @brief Return a reference to a sub-group of the current Group.
* @tparam T The type of subgroup.
* @tparam KEY The type of the lookup.
* @param key The key used to perform the lookup.
* @return A reference to @p T that refers to the sub-group.
* @throw std::domain_error If the Group does not exist is thrown.
*/
template< typename T = Group, typename KEY = void >
T & getGroup( KEY const & key )
{
Group * const child = m_subGroups[ key ];
GEOS_THROW_IF( child == nullptr,
"Group " << getDataContext() << " has no child named " << key <<␣
˓→std::endl

<< dumpSubGroupsNames(),
std::domain_error );
T * const castedChild = dynamicCast< T * >( child );
GEOS_THROW_IF( castedChild == nullptr,
GEOS_FMT( "{} was expected to be a '{}'.",
child->getDataContext(), LvArray::system::demangleType< T >
˓→() ),

BadTypeError );
return *castedChild;
}

/**
* @copydoc getGroup( KEY const & )
*/
template< typename T = Group, typename KEY = void >
T const & getGroup( KEY const & key ) const
{
Group const * const child = m_subGroups[ key ];
GEOS_THROW_IF( child == nullptr,
"Group " << getDataContext() << " has no child named " << key <<␣
˓→std::endl

<< dumpSubGroupsNames(),
std::domain_error );
T const * const castedChild = dynamicCast< T const * >( child );
GEOS_THROW_IF( castedChild == nullptr,
GEOS_FMT( "{} was expected to be a '{}'.",
child->getDataContext(), LvArray::system::demangleType< T >
˓→() ),

BadTypeError );
return *castedChild;
}

(continues on next page)

608 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

/**
* @brief Retrieve a group from the hierarchy using a path.
* @tparam T type of subgroup
* @param[in] path a unix-style string (absolute, relative paths valid)
* to lookup the Group to return. Absolute paths search
* from the tree root, while relative - from current group.
* @return A reference to @p T that refers to the sub-group.
* @throw std::domain_error If the Group doesn't exist.
*/
template< typename T = Group >
T & getGroupByPath( string const & path )
{ return dynamicCast< T & >( const_cast< Group & >( getBaseGroupByPath( path ) ) ); }

/**
* @copydoc getGroupByPath(string const &)
*/
template< typename T = Group >
T const & getGroupByPath( string const & path ) const
{ return dynamicCast< T const & >( getBaseGroupByPath( path ) ); }

/**
* @name Wrapper registration interface
*/
///@{

/**
* @brief Create and register a Wrapper around a new object.
* @tparam T The type of the object allocated.
* @tparam TBASE The type of the object that the Wrapper holds.
* @param[in] name the name of the wrapper to use as a string key
* @param[out] rkey a pointer to a index type that will be filled with the new
* Wrapper index in this Group
* @return A reference to the newly registered/created Wrapper
*/
template< typename T, typename TBASE=T >
Wrapper< TBASE > & registerWrapper( string const & name,
wrapperMap::KeyIndex::index_type * const rkey =␣
˓→nullptr );

/**
* @copybrief registerWrapper(string const &,wrapperMap::KeyIndex::index_type * const)
* @tparam T the type of the wrapped object
* @tparam TBASE the base type to cast the returned wrapper to
* @param[in] viewKey The KeyIndex that contains the name of the new Wrapper.
* @return A reference to the newly registered/created Wrapper
*/
template< typename T, typename TBASE=T >
Wrapper< TBASE > & registerWrapper( Group::wrapperMap::KeyIndex const & viewKey );

(continues on next page)

1.6. Developer Guide 609

GEOS Documentation

(continued from previous page)

/**
* @brief Register a Wrapper around a given object and take ownership.
* @tparam T the type of the wrapped object
* @param[in] name the name of the wrapper to use as a string key
* @param[in] newObject an owning pointer to the object that is being registered
* @return A reference to the newly registered/created Wrapper
* @note Not intended to register a @p WrapperBase instance. Use dedicated member␣
˓→function instead.

*/
template< typename T >
Wrapper< T > & registerWrapper( string const & name, std::unique_ptr< T > newObject );

/**
* @brief Register a Wrapper around an existing object, does not take ownership of the␣
˓→object.

* @tparam T the type of the wrapped object

* @param[in] name the name of the wrapper to use as a string key
* @param[in] newObject a pointer to the object that is being registered
* @return A reference to the newly registered/created Wrapper
* @note Not intended to register a @p WrapperBase instance. Use dedicated member␣
˓→function instead.

*/
template< typename T >
Wrapper< T > & registerWrapper( string const & name,
T * newObject );

/**
* @brief Register and take ownership of an existing Wrapper.
* @param wrapper A pointer to the an existing wrapper.
* @return An un-typed pointer to the newly registered/created wrapper
*/
WrapperBase & registerWrapper( std::unique_ptr< WrapperBase > wrapper );

/**
* @brief Removes a Wrapper from this group.
* @param name the name of the Wrapper to remove from this group.
*/
void deregisterWrapper( string const & name );

///@}

Getting Wrappers/Wrapped Objects

/**
* @name Untyped wrapper retrieval methods
*
* These functions query the collection of Wrapper objects for the given
* index/name/KeyIndex and returns a WrapperBase pointer to the object if
* it exists. If it is not found, nullptr is returned.
*/
///@{
(continues on next page)

610 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

/**
* @brief Return a reference to a WrapperBase stored in this group.
* @tparam KEY The lookup type.
* @param key The value used to lookup the wrapper.
* @return A reference to the WrapperBase that resulted from the lookup.
* @throw std::domain_error if the wrapper doesn't exist.
*/
template< typename KEY >
WrapperBase const & getWrapperBase( KEY const & key ) const
{
WrapperBase const * const wrapper = m_wrappers[ key ];
GEOS_THROW_IF( wrapper == nullptr,
"Group " << getDataContext() << " has no wrapper named " << key <<␣
˓→std::endl

<< dumpWrappersNames(),
std::domain_error );

* @tparam LOOKUP_TYPE type of value used for wrapper lookup
* @param lookup value for wrapper lookup
* @return reference to @p T
* @throw A std::domain_error if the Wrapper does not exist.
*/
template< typename T, typename LOOKUP_TYPE >
GEOS_DECLTYPE_AUTO_RETURN
getReference( LOOKUP_TYPE const & lookup ) const
{ return getWrapper< T >( lookup ).reference(); }

/**
* @copydoc getReference(LOOKUP_TYPE const &) const
*/
template< typename T, typename LOOKUP_TYPE >
T & getReference( LOOKUP_TYPE const & lookup )
{ return getWrapper< T >( lookup ).reference(); }

Looping Interface

/**
* @name Functor-based subgroup iteration
*
* These functions loop over sub-groups and executes a functor that uses the sub-group␣
˓→as an

* argument. The functor is only executed if the group can be cast to a certain type␣
˓→specified

* by the @p ROUPTYPE/S pack. The variadic list consisting of @p GROUPTYPE/S will be␣
˓→used recursively

* to check if the group is able to be cast to the one of these types. The first type␣
˓→in the

* @p GROUPTYPE/S list will be used to execute the functor, and the next sub-group␣
˓→will be processed.

*/
///@{

/**
* @brief Apply the given functor to subgroups that can be casted to one of specified␣
˓→types.

* @tparam GROUPTYPE the first type that will be used in the attempted casting of␣
˓→group.

* @tparam GROUPTYPES a variadic list of types that will be used in the attempted␣
˓→casting of group.

* @tparam LAMBDA the type of functor to call

* @param[in] lambda the functor to call on subgroups
*/
template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LAMBDA >
void forSubGroups( LAMBDA && lambda )
{
for( auto & subGroupIter : m_subGroups )
{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( *subGroupIter.second, [&](␣
(continues on next page)

614 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

˓→auto & castedSubGroup )
{
lambda( castedSubGroup );
} );
}
}

/**
* @copydoc forSubGroups(LAMBDA &&)
*/
template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LAMBDA >
void forSubGroups( LAMBDA && lambda ) const
{
for( auto const & subGroupIter : m_subGroups )
{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( *subGroupIter.second, [&](␣
˓→auto const & castedSubGroup )

{
lambda( castedSubGroup );
} );
}
}

/**
* @brief Apply the given functor to subgroups that can be casted to one of specified␣
˓→types.

* @tparam GROUPTYPE the first type that will be used in the attempted casting of␣
˓→group.

* @tparam GROUPTYPES a variadic list of types that will be used in the attempted␣
˓→casting of group.

* @tparam LAMBDA the type of functor to call

* @param[in] lambda the functor to call on subgroups
*/
template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LAMBDA >
void forSubGroupsIndex( LAMBDA && lambda )
{
localIndex counter = 0;
for( auto & subGroupIter : m_subGroups )
{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( *subGroupIter.second,
[&]( auto & castedSubGroup )
{
lambda( counter, castedSubGroup );
} );
++counter;
}
}

/**
* @copydoc forSubGroupsIndex(LAMBDA &&)
*/
(continues on next page)

1.6. Developer Guide 615

GEOS Documentation

(continued from previous page)

template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LAMBDA >
void forSubGroupsIndex( LAMBDA && lambda ) const
{
localIndex counter = 0;
for( auto const & subGroupIter : m_subGroups )
{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( *subGroupIter.second,
[&]( auto const &␣
˓→castedSubGroup )

{
lambda( counter, castedSubGroup );
} );
++counter;
}
}

/**
* @copybrief forSubGroups(LAMBDA &&)
* @tparam GROUPTYPE the first type that will be used in the attempted casting␣
˓→of group.

* @tparam GROUPTYPES a variadic list of types that will be used in the␣

˓→attempted casting of group.

* @tparam LOOKUP_CONTAINER type of container of subgroup lookup keys (names or␣

˓→indices), must support range-based for

* loop
* @tparam LAMBDA type of functor callable with an index in lookup container␣
˓→and a reference to casted

* subgroup
* @param[in] subGroupKeys container with subgroup lookup keys (e.g. names or␣
˓→indices) to apply the functor to

* @param[in] lambda the functor to call

*/
template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LOOKUP_
˓→CONTAINER, typename LAMBDA >

void forSubGroups( LOOKUP_CONTAINER const & subGroupKeys, LAMBDA && lambda )

{
localIndex counter = 0;

for( auto const & subgroup : subGroupKeys )

{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( getGroup( subgroup ), [&](␣
˓→auto & castedSubGroup )

{
lambda( counter, castedSubGroup );
} );
++counter;
}
}

/**
* @copybrief forSubGroups(LAMBDA &&)
* @tparam GROUPTYPE the first type that will be used in the attempted casting␣
(continues on next page)

616 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

˓→of group.
* @tparam GROUPTYPES a variadic list of types that will be used in the␣
˓→attempted casting of group.

* @tparam LOOKUP_CONTAINER type of container of subgroup lookup keys (names or␣

˓→indices), must support range-based for

* loop
* @tparam LAMBDA type of functor callable with an index in lookup container␣
˓→and a reference to casted

* subgroup
* @param[in] subGroupKeys container with subgroup lookup keys (e.g. names or␣
˓→indices) to apply the functor to

* @param[in] lambda the functor to call

*/
template< typename GROUPTYPE = Group, typename ... GROUPTYPES, typename LOOKUP_
˓→CONTAINER, typename LAMBDA >

void forSubGroups( LOOKUP_CONTAINER const & subGroupKeys, LAMBDA && lambda ) const
{
localIndex counter = 0;
for( auto const & subgroup : subGroupKeys )
{
applyLambdaToContainer< GROUPTYPE, GROUPTYPES... >( getGroup( subgroup ), [&](␣
˓→auto const & castedSubGroup )

{
lambda( counter, castedSubGroup );
} );
++counter;
}
}
///@}

/**
* @name Functor-based wrapper iteration
*
* These functions loop over the wrappers contained in this group, and executes a␣
˓→functor that

* uses the Wrapper as an argument. The functor is only executed if the Wrapper can be␣
˓→casted to

* a certain type specified by the @p TYPE/S pack. The variadic list consisting of
* @p TYPE/S will be used recursively to check if the Wrapper is able to be casted to␣
˓→the

* one of these types. The first type in the @p WRAPPERTYPE/S list will be used to␣
˓→execute the

* functor, and the next Wrapper will be processed.

*/
///@{

/**
* @brief Apply the given functor to wrappers.
* @tparam LAMBDA the type of functor to call
* @param[in] lambda the functor to call
*/
template< typename LAMBDA >
(continues on next page)

1.6. Developer Guide 617

GEOS Documentation

(continued from previous page)

void forWrappers( LAMBDA && lambda )
{
for( auto & wrapperIter : m_wrappers )
{
lambda( *wrapperIter.second );
}
}

/**
* @copydoc forWrappers(LAMBDA &&)
*/
template< typename LAMBDA >
void forWrappers( LAMBDA && lambda ) const
{
for( auto const & wrapperIter : m_wrappers )
{
lambda( *wrapperIter.second );
}
}

/**
* @brief Apply the given functor to wrappers that can be cast to one of specified␣
˓→types.

* @tparam TYPE the first type that will be used in the attempted casting of Wrapper
* @tparam TYPES a variadic list of types that will be used in the attempted casting␣
˓→of Wrapper

* @tparam LAMBDA the type of functor to call

* @param[in] lambda the functor to call
*/
template< typename TYPE, typename ... TYPES, typename LAMBDA >
void forWrappers( LAMBDA && lambda )
{
for( auto & wrapperIter : m_wrappers )
{
applyLambdaToContainer< Wrapper< TYPE >, Wrapper< TYPES >... >( *wrapperIter.
˓→second,

std::forward<␣
˓→LAMBDA >( lambda ));

}
}

/**
* @brief Apply the given functor to wrappers that can be cast to one of specified␣
˓→types.

* @tparam TYPE the first type that will be used in the attempted casting of Wrapper
* @tparam TYPES a variadic list of types that will be used in the attempted casting␣
˓→of Wrapper

* @tparam LAMBDA the type of functor to call

* @param[in] lambda the functor to call
*/
template< typename TYPE, typename ... TYPES, typename LAMBDA >
void forWrappers( LAMBDA && lambda ) const
(continues on next page)

618 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

{
for( auto const & wrapperIter : m_wrappers )
{
applyLambdaToContainer< Wrapper< TYPE >, Wrapper< TYPES >... >( *wrapperIter.
˓→second,

std::forward<␣
˓→LAMBDA >( lambda ));

}
}

///@}

Doxygen API documentation

Group API

Wrapper

This class encapsulates an object for storage in a Group and provides an interface for performing some common oper-
ations on that object.

Description

In the filesystem analogy, a Wrapper may be thought of as a file that stores actual data. Each Wrapper belong to a
single Group much like a file belongs to a filesystem directory. In general, more than one wrapper in the tree may refer
to the same wrapped object, just like symlinks in the file system may refer to the same file. However, only one wrapper
should be owning the data (see below).
In the XML input file, Wrapper correspond to attribute of an XML element representing the containing Group. See
XML Input for the relationship between XML input files and Data Repository.
Wrapper<T> is templated on the type of object it encapsulates, thus providing strong type safety when retrieving the ob-
jects. As each Wrapper class instantiation will be a distinct type, Wrapper derives from a non-templated WrapperBase
class that defines a common interface. WrapperBase is the type of pointer that is stored in the MappedVector container
within a Group.
WrapperBase provides several interface functions that delegate the work to the wrapped object if it supports the corre-
sponding method signature. This allows a collection of heterogeneous wrappers (i.e. over different types) to be treated
uniformly. Examples include:
• size()
• resize(newSize)
• reserve(newCapacity)
• capacity()
• move(LvArray::MemorySpace)
A Wrapper may be owning or non-owning, depending on how it’s constructed. An owning Wrapper will typically
either take a previously allocated object via std::unique_ptr<T> or no pointer at all and itself allocate the object. It
will delete the wrapped object when destroyed. A non-owning Wrapper may be used to register with the data repository
objects that are not directly heap-allocated, for example data members of other objects. It will take a raw pointer as
input and not delete the wrapped object when destroyed.

1.6. Developer Guide 619

GEOS Documentation

Attributes

Each instance of Wrapper has a set of attributes that control its function in the data repository. These attributes are:
• InputFlags
A strongly typed enum that defines the relationship between the Wrapper and the XML input. Possible values
are:

Value Explanation
FALSE Data is not read from XML input (default).
OPTIONAL Data is read from XML if an attribute matching Wrapper’s name is found.
REQUIRED Data is read from XML and an error is raised if the attribute is not found.

Other values of InputFlags enumeration are reserved for Group objects.

ò Note

A runtime error will occur when attempting to read from XML a wrapped type T that does not have operator>>
defined.

• RestartFlags
Enumeration that describes how the Wrapper interacts with restart files.

Value Explanation
NO_WRITE Data is not written into restart files.
WRITE Data is written into restart files but not read upon restart.
WRITE_AND_READ Data is both written and read upon restart (default).

ò Note

A runtime error will occur when attempting to write a wrapped type T that does not support buffer packing. There-
fore, when registering custom types (i.e. not a basic C++ type or an LvArray container) we recommend setting the
flag to NO_WRITE. A future documentation topic will explain how to extend buffer packing capabilities to custom
user-defined types.

• PlotLevel
Enumeration that describes how the Wrapper interacts with plot (visualization) files.

Value Explanation
LEVEL_0 Data always written to plot files.
LEVEL_1 Data written to plot when plotLevel>=1 is specified in input.
LEVEL_2 Data written to plot when plotLevel>=2 is specified in input.
LEVEL_3 Data written to plot when plotLevel>=3 is specified in input.
NOPLOT Data never written to plot files.

620 Chapter 1. Table of Contents

GEOS Documentation

ò Note

Only data stored in LvArray’s Array<T> containers is currently written into plot files.

Default Values

Wrapper supports setting a default value for its wrapped object. The default value is used if a wrapper with
InputFlags::OPTIONAL attribute does not match an attribute in the input file. For LvArray containers it is also
used as a default value for new elements upon resizing the container.
Default value can be set via one of the following two methods:
• setDefaultValue sets the default value but does not affect the actual value stored in the wrapper.
• setApplyDefaultValue sets the default value and applies it to the stored value.

ò Note

A runtime error is raised if a default value is not set for a wrapper with InputFlags::OPTIONAL attribute.

The type DefaultValue<T> is used to store the default value for the wrapper.

v Todo

DefaultValue is actually not a type but an alias for another internal struct. As such, it cannot currently be spe-
cialized for a user’s custom type.

Doxygen API documentation

Wrapper API

ObjectCatalog

The “ObjectCatalog” is a collection of classes that acts as a statically initialized factory. It functions in a similar
manner to a classic factory method, except that there is no maintained list of derived objects that is required to create
new objects. In other words, there is no case-switch/if-elseif block to maintain. Instead, the ObjectCatalog creates
a “catalog” of derived objects using a std::unordered_map. The “catalog” is filled when new types are declared
through the declaration of a helper class named CatalogEntryConstructor.
The key functional features of the “ObjectCatalog” concept may be summarized as:
• Anonymous addition of new objects to the catalog. Because we use a statically initialized singleton map ob-
ject to store the catalog, no knowledge of the contents of the catalog is required in the main code. Therefore
if a proprietary/sensitive catalog entry is desired, it is only required that the object definition be outside of
the main repository and tied into the build system through some non-specific mechanism (i.e. a link in the
src/externalComponents directory) and the catalog entry will be registered in the catalog without sharing any
knowledge of its existence. Then a proprietary input file may refer to the object to call for its creation.
• Zero maintenance catalog. Again, because we use a singleton map to store the catalog, there is no updating of
code required to add new entries into the catalog. The only modifications required are the actual source files of
the catalog entry, as described in the Usage section below.

1.6. Developer Guide 621

GEOS Documentation

Implementation Details

There are three key objects that are used to provide the ObjectCatalog functionality.

CatalogInterface

The CatalogInterface class provides the base definitions and interface for the ObjectCatalog concept. It is tem-
plated on the common base class of all derived objects that are creatable by the “ObjectCatalog”. In addition,
CatalogInterface is templated on a variadic parameter pack that allows for an arbitrary constructor argument list as
shown in the declaration shown below:

template< typename BASETYPE, typename ... ARGS >

class CatalogInterface

The CatalogInterface also defines the actual catalog type using the template arguments:

typedef std::unordered_map< std::string,

std::unique_ptr< CatalogInterface< BASETYPE, ARGS... > > >␣
˓→CatalogType;

The CatalogInterface::CatalogType is a std::unordered_map with a string “key” and a value type that is a
pointer to the CatalogInterface that represents a specific combination of BASETYPE and constructor arguments.
After from setting up and populating the catalog, which will be described in the “Usage” section, the only interface
with the catalog will typically be when the Factory() method is called. The definition of the method is given as:

static std::unique_ptr< BASETYPE > factory( std::string const & objectTypeName,

ARGS... args )
{
// We stop the simulation if the product is not found
if( !hasKeyName( objectTypeName ) )
{
std::list< typename CatalogType::key_type > keys = getKeys();
string const tmp = stringutilities::join( keys.cbegin(), keys.cend(), ",\n" );

string errorMsg = "Could not find keyword \"" + objectTypeName + "\" in this␣
˓→context. ";
errorMsg += "Please be sure that all your keywords are properly spelled or that␣
˓→input file parameters have not changed.\n";

errorMsg += "All available keys are: [\n" + tmp + "\n]";

GEOS_ERROR( errorMsg );
}

// We also stop the simulation if the builder is not here.

CatalogInterface< BASETYPE, ARGS... > const * builder = getCatalog().at(␣
˓→objectTypeName ).get();

if( builder == nullptr )

{
const string errorMsg = "\"" + objectTypeName + "\" could be found. But the␣
˓→builder is invalid.\n";

GEOS_ERROR( errorMsg );
}

return builder->allocate( args ... );

}

622 Chapter 1. Table of Contents

GEOS Documentation

It can be seen that the static Factory method is simply a wrapper that calls the virtual Allocate method on a the
catalog which is returned by getCatalog(). The usage of the Factory method will be further discussed in the Usage
section.

ò Note

The method for organizing constructing new objects relies on a common constructor list between the derived type
and the BASETYPE. This means that there is a single catalog for each combination of BASETYPE and the variadic
parameter pack representing the constructor arguments. In the future, we can investigate removing this restriction
and allowing for construction of a hierarchy of objects with an arbitrary constructor parameter list.

CatalogEntry

The CatalogEntry class derives from CatalogInterface and adds the a TYPE template argument to the arguments
of the CatalogInterface.

template< typename BASETYPE, typename TYPE, typename ... ARGS >

class CatalogEntry final : public CatalogInterface< BASETYPE, ARGS... >

The TYPE template argument is the type of the object that you would like to be able to create with the “Ob-
jectCatalog”. TYPE must be derived from BASETYPE and have a constructor that matches the variadic param-
eter pack specified in the template parameter list. The main purpose of the CatalogEntry is to override the
CatalogInterface::Allocate() virtual function s.t. when key is retrieved from the catalog, then it is possible
to create a new TYPE. The CatalogEntry::Allocate() function is a simple creation of the underlying TYPE as
shown by its definition:

virtual std::unique_ptr< BASETYPE > allocate( ARGS... args ) const override

{
#if OBJECTCATALOGVERBOSE > 0
GEOS_LOG( "Creating type " << LvArray::system::demangle( typeid(TYPE).name())
<< " from catalog of " << LvArray::system::demangle(␣
˓→typeid(BASETYPE).name()));

#endif
#if ( __cplusplus >= 201402L )
return std::make_unique< TYPE >( args ... );
#else
return std::unique_ptr< BASETYPE >( new TYPE( args ... ) );
#endif
}

CatalogEntryConstructor

The CatalogEntryConstructor is a helper class that has a sole purpose of creating a new CatalogEntry and
adding it to the catalog. When a new CatalogEntryConstructor is created, a new CatalogEntry entry is created
and inserted into the catalog automatically.

Usage

Creating A New Catalog

When creating a new “ObjectCatalog”, it typically is done within the context of a specific BASETYPE. A simple example
of a class hierarchy in which we would like to use the “ObjectCatalog” to use to generate new objects is given in the
unit test located in testObjectCatalog.cpp.

1.6. Developer Guide 623

GEOS Documentation

The base class for this example is defined as:

class Base
{
public:
Base( int & junk, double const & junk2 )
{
GEOS_LOG( "calling Base constructor with arguments ("<<junk<<" "<<junk2<<")" );
}

virtual ~Base()
{
GEOS_LOG( "calling Base destructor" );
}

using CatalogInterface = dataRepository::CatalogInterface< Base, int &, double const &␣

˓→ >;
static CatalogInterface::CatalogType & getCatalog()
{
static CatalogInterface::CatalogType catalog;
return catalog;
}

virtual string getCatalogName() = 0;

};

There a couple of things to note in the definition of Base:

• Base has a convenience alias to use in place of the fully templated CatalogInterface name.
• Base defines a getCatalog() function that returns a static instantiation of a
CatalogInterface::CatalogType. The CatalogInterface::getCatalog() function actually calls
this function within the base class. This means that the base class actually owns the catalog, and the
CatalogInterface is only operating on that Base::getCatalog(), and that the definition of this function is
required.

Adding A New Type To The Catalog

Once a Base class is defined with the required features, the next step is to add a new derived type to the catalog defined
in Base. There are three requirements for the new type to be registered in the catalog:
• The derived type must have a constructor with the arguments specified by the variadic parameter pack specified
in the catalog.
• There must be a static function static string catalogName() that returns the name of the type that will be
used to as keyname when it is registered Base’s catalog.
• The new type must be registered with the catalog held in Base. To accomplish this, a convenience macro
REGISTER_CATALOG_ENTRY() is provided. The arguments to this macro are the name type of Base, the type of
the derived class, and then the variadic pack of constructor arguments.
A pair of of simple derived class that have the required methods are used in the unit test.
class Derived1 : public Base
{
public:
Derived1( int & junk, double const & junk2 ):
(continues on next page)

624 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Base( junk, junk2 )
{
GEOS_LOG( "calling Derived1 constructor with arguments ("<<junk<<" "<<junk2<<")" );
}

~Derived1()
{
GEOS_LOG( "calling Derived1 destructor" );
}
static string catalogName() { return "derived1"; }
string getCatalogName() { return catalogName(); }

};
REGISTER_CATALOG_ENTRY( Base, Derived1, int &, double const & )

class Derived2 : public Base

{
public:
Derived2( int & junk, double const & junk2 ):
Base( junk, junk2 )
{
GEOS_LOG( "calling Derived2 constructor with arguments ("<<junk<<" "<<junk2<<")" );
}

~Derived2()
{
GEOS_LOG( "calling Derived2 destructor" );
}
static string catalogName() { return "derived2"; }
string getCatalogName() { return catalogName(); }

};
REGISTER_CATALOG_ENTRY( Base, Derived2, int &, double const & )

Allocating A New Object From The Catalog

The test function in the unit test shows how to allocate a new object of one of the derived types from Factory method.
Note the call to Factory is scoped by Base::CatalogInterface, which is an alias to the full templated instantiation
of CatalogInterface. The arguments for Factory

TEST( testObjectCatalog, testRegistration )

{
GEOS_LOG( "EXECUTING MAIN" );
int junk = 1;
double junk2 = 3.14;

// allocate a new Derived1 object

std::unique_ptr< Base >
derived1 = Base::CatalogInterface::factory( "derived1", junk, junk2 );

// allocate a new Derived2 object

(continues on next page)

1.6. Developer Guide 625

GEOS Documentation

(continued from previous page)

std::unique_ptr< Base >
derived2 = Base::CatalogInterface::factory( "derived2", junk, junk2 );

EXPECT_STREQ( derived1->getCatalogName().c_str(),
Derived1::catalogName().c_str() );

EXPECT_STREQ( derived2->getCatalogName().c_str(),
Derived2::catalogName().c_str() );
GEOS_LOG( "EXITING MAIN" );
}

The unit test creates two new objects of type Derived1 and Derived2 using the catalogs Factory method. Then the
test checks to see that the objects that were created are of the correct type. This unit test has some extra output to screen
to help with understanding of the sequence of events. The result of running this test is:

$ tests/testObjectCatalog
Calling constructor for CatalogEntryConstructor< Derived1 , Base , ... >
Calling constructor for CatalogInterface< Base , ... >
Calling constructor for CatalogEntry< Derived1 , Base , ... >
Registered Base catalog component of derived type Derived1 where Derived1::catalogName()␣
˓→= derived1

Calling constructor for CatalogEntryConstructor< Derived2 , Base , ... >

Calling constructor for CatalogInterface< Base , ... >
Calling constructor for CatalogEntry< Derived2 , Base , ... >
Registered Base catalog component of derived type Derived2 where Derived2::catalogName()␣
˓→= derived2

Running main() from gtest_main.cc

[==========] Running 1 test from 1 test case.
[----------] Global test environment set-up.
[----------] 1 test from testObjectCatalog
[ RUN ] testObjectCatalog.testRegistration
EXECUTING MAIN
Creating type Derived1 from catalog of Base
calling Base constructor with arguments (1 3.14)
calling Derived1 constructor with arguments (1 3.14)
Creating type Derived2 from catalog of Base
calling Base constructor with arguments (1 3.14)
calling Derived2 constructor with arguments (1 3.14)
EXITING MAIN
calling Derived2 destructor
calling Base destructor
calling Derived1 destructor
calling Base destructor
[ OK ] testObjectCatalog.testRegistration (0 ms)
[----------] 1 test from testObjectCatalog (0 ms total)

[----------] Global test environment tear-down

[==========] 1 test from 1 test case ran. (0 ms total)
[ PASSED ] 1 test.
Calling destructor for CatalogEntryConstructor< Derived2 , Base , ... >
Calling destructor for CatalogEntryConstructor< Derived1 , Base , ... >
Calling destructor for CatalogEntry< Derived2 , Base , ... >
(continues on next page)

626 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

Calling destructor for CatalogInterface< Base , ... >
Calling destructor for CatalogEntry< Derived1 , Base , ... >
Calling destructor for CatalogInterface< Base , ... >

In the preceding output, it is clear that the static catalog in Base::getCatalog() is initialized prior the execution of
main, and destroyed after the completion of main. In practice, there have been no indicators of problems due to the use
of a statically initialized/deinitialized catalog.

Mapped Vector

A superposition of a contiguous and an associative container.

Description

The container stores pointers to objects (which are themselves heap-allocated). Each element may be optionally owned
by the container, in which case it will be deleted upon removal or container destruction. The pointers are stored in a
contiguous memory allocation, and thus are accessible through an integral index lookup. In addition, there is a map
that provides a key lookup capability to the container if that is the preferred interface.
The container template has four type parameters:
• T is the object type pointed to by container entries
• T_PTR is a pointer-to-T type which must be either T * (default) or std::unique_ptr<T>
• KEY_TYPE is the type of key used in associative lookup
• INDEX_TYPE is the type used in index lookup

Element access

MappedVector provides three main types of data access using [] operator:

• Index lookup is the fastest way of element random access if the ordinal index is known.
• Key lookup is similar to key lookup of any associative container and incurs similar cost.
• KeyIndex lookup uses a special type, KeyIndex, that contains both a key and an index. Initially the index is
unknown and the key is used for the lookup. The KeyIndex is modified during lookup, storing the index located.
If the user persists the KeyIndex object, they may reuse it in subsequent accesses and get the benefit of direct
index access.
In addition to these, an STL-conformant iterator interface is available via begin() and end() methods. The type
iterated over is a key-pointer pair (provided as value_type alias).

Doxygen API documentation

MappedVector API

XML Input
In this document, you will learn how GEOS classes interact with external information parsed from XML files, and how
to add a new XML block that can be interpreted by GEOS. Flow solvers and relative permeability are used as examples.

1.6. Developer Guide 627

GEOS Documentation

GEOS data structure overview

Group : the base class of GEOS

All GEOS classes derive from a base class called dataRepository::Group. The Group class provides a way to
organize all GEOS objects in a filesystem-like structure. One could think of Group s as file folders that can bear data
(stored in Wrapper s), have a parent folder (another Group), and have possibly multiple subfolders (referred to as
the subgroups). Below, we briefly review the data members of the Group class that are essential to understand the
correspondence between the GEOS data structure and the XML input. For more details, we refer the reader to the
extensive documentation of the Data Repository, including the Group class documentation.
In the code listing below, we see that each Group object is at minimum equipped with the following member properties:
• A pointer to the parent Group called m_parent (member classes are prefixed by m_),
• The Group ‘s own data, stored for flexibility in an array of generic data Wrapper s called m_wrappers,
• A map of one or many children (also of type Group) called m_subGroups.
• The m_size and m_capacity members, that are used to set the size and capacity of any objects contained.
• The name of the Group, stored as a string in m_name. This name can be seen as the object unique ID.

/// The parent Group that contains "this" Group in its "sub-Group" collection.
Group * m_parent = nullptr;

/// Specification that this group will have the same m_size as m_parent.
integer m_sizedFromParent;

/// The container for the collection of all wrappers continued in "this" Group.
wrapperMap m_wrappers;

/// The container for the collection of all sub-groups contained in "this" Group.
subGroupMap m_subGroups;

/// The size/length of this Group...and all Wrapper<> that are are specified to have␣
˓→the same size as their
/// owning group.
indexType m_size;

/// The capacity for wrappers in this group...and all Wrapper<> that are specified to␣
˓→have the same size as their
/// owning group.
indexType m_capacity;

/// The name/key of this Group in its parent collection of sub-Groups.

string m_name;

/// Verbosity flag for group logs

integer m_logLevel;

//END_SPHINX_INCLUDE_02

/// Restart flag for this group... and subsequently all wrappers in this group.

[Source: src/coreComponents/dataRepository/Group.hpp]

628 Chapter 1. Table of Contents

GEOS Documentation

A few words about the ObjectCatalog

What is an ObjectCatalog and why do we need it?

Some classes need external information (physical and/or algorithmic parameters for instance) provided by the user to
be instantiated. This is the case when the m_input_flags data member of one of the Group ‘s Wrapper s has an entry
set to REQUIRED (we will illustrate this below). In this situation, the required information must be supplied in the XML
input file, and if it is absent, an error is raised by GEOS.
To connect the external (XML) and internal (C++) data structures, GEOS uses an ObjectCatalog that maps keys
(of type string) to the corresponding classes (one unique key per mapped class). These string keys, referred to as
catalogName s, are essential to transfer the information from the XML file to the factory functions in charge of object
instantiation (see below).
What is a CatalogName?
The catalogName of an object is a key (of type string) associated with this object’s class. On the one hand, in
the XML file, the key is employed by the user as an XML tag to specify the type of object (e.g., the type of solver,
constitutive model, etc) to create and use during the simulation. On the other hand, internally, the key provides a way
to access the appropriate factory function to instantiate an object of the desired class.
Most of the time, the catalogName and the C++ class name are identical. This helps make the code easier to debug
and allows the XML/C++ correspondence to be evident. But strictly speaking, the catalogName can be anything, as
long as it refers uniquely to a specific class. The catalogName must not be confused with the object’s name (m_name
is a data member of the class that stores the object’s unique ID, not its class key). You can have several objects of the
same class and hence the same catalogName, but with different names (i.e. unique ID): several fluid models, several
solvers, etc.
How can I add my new externally-accessible class to the ObjectCatalog?
Let us consider a flow solver class derived from FlowSolverBase, that itself is derived from PhysicsSolverBase.
To instantiate and use this solver, the developer needs to make the derived flow solver class reachable from the XML
file, via an XML tag. Internally, this requires adding the derived class information to ObjectCatalog, which is
achieved with two main ingredients: 1) a CatalogName() method in the class that lets GEOS know what to search for
in the internal ObjectCatalog to instantiate an object of this class, 2) a macro that specifies where to search in the
ObjectCatalog.
1. To let GEOS know what to search for in the catalog to instantiate an object of the derived class, the developer
must equip the class with a CatalogName() method that returns a string. In this document, we have referred
to this returned string as the object’s catalogName, but in fact, the method CatalogName() is what matters
since the ObjectCatalog contains all the CatalogName() return values. Below, we illustrate this with the
CompositionalMultiphaseFlow solver. The first code listing defines the class name, which in this case is the
same as the catalogName shown in the second listing.

/**
* @class CompositionalMultiphaseBase
*
* A compositional multiphase solver
*/
class CompositionalMultiphaseBase : public FlowSolverBase
{

[Source: src/coreComponents/physicsSolvers/fluidFlow/CompositionalMultiphaseBase.hpp]
2. To let GEOS know where to search in the ObjectCatalog, a macro needs to be added at the end of the .cpp
file implementing the class. This macro (illustrated below) must contain the type of the base class (in this case,

1.6. Developer Guide 629

GEOS Documentation

PhysicsSolverBase), and the name of the derived class (continuing with the example used above, this is
CompositionalMultiphaseFlow). As a result of this construct, the ObjectCatalog is not a flat list of string
s mapping the C++ classes. Instead, the ObjectCatalog forms a tree that reproduces locally the structure of
the class diagram, from the base class to the derived classes.

REGISTER_CATALOG_ENTRY( PhysicsSolverBase, CompositionalMultiphaseFVM, string const &,␣

˓→Group * const )

[Source: src/coreComponents/physicsSolvers/fluidFlow/CompositionalMultiphaseFVM.cpp]
Summary: All GEOS objects form a filesystem-like structure. If an object needs to be accessible externally,
it must be registered in the ObjectCatalog. This is done by adding CatalogName() method that returns
a string key to the object’s class, and by adding the appropriate macro. The catalog has the same tree
structure as the class diagram.

Registration: parsing XML input files to instantiate GEOS objects

In this section, we describe with more details the connection between internal GEOS objects and external XML tags
parsed from parameter files. We call this process Registration. The registration process works in three steps:
1. The XML document is parsed. Each time a new XML tag is found, the current local scope of the ObjectCatalog
is inspected. The goal is to find a catalogName string that matches the XML tag.
2. If it is the case (the current local scope of the ObjectCatalog contains a catalogName identical to the XML
tag), then the code creates a new instance of the class that the catalogName refers to. This new object is inserted
in the Group tree structure at the appropriate location, as a subgroup.
3. By parsing the XML attributes of the tag, the new object properties are populated. Some checks are performed
to ensure that the data supplied is conform, and that all the required information is present.
Let’s look at this process in more details.

Creating a new object and giving it a Catalog name

Consider again that we are registering a flow solver deriving from FlowSolverBase, and assume that this solver is
called CppNameOfMySolver. This choice of name is not recommended (we want names that reflect what the solver
does!), but for this particular example, we just need to know that this name is the class name inside the C++ code.
To specify parameters of this new solver from an XML file, we need to be sure that the XML tag and the catalogName
of the class are identical. Therefore, we equip the CppNameOfMySolver class with a CatalogName() method that
returns the solver catalogName (=XML name). Here, this method returns the string “XmlNameOfMySolver”.
We have deliberately distinguished the class name from the catalog/XML name for the sake of clarity in this example.
It is nevertheless a best practice to use the same name for the class and for the catalogName. This is the case below
for the existing CompositionalMultiphaseFVM class.

class CompositionalMultiphaseFVM : public CompositionalMultiphaseBase

{

/**
* @brief name of the solver in the object catalog
* @return string that contains the catalog name to generate a new object through the␣
˓→object catalog.

*/
static string catalogName() { return "CompositionalMultiphaseFVM"; }
/**
* @copydoc PhysicsSolverBase::getCatalogName()
(continues on next page)

630 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

*/
string getCatalogName() const override { return catalogName(); }

[Source: src/coreComponents/physicsSolvers/fluidFlow/CompositionalMultiphaseFVM.hpp]

Parsing XML and searching the ObjectCatalog in scope

Now that we have implemented a CatalogName() method returning a specific key (of type string), we can have a
block in our XML input file with a tag that corresponds to the catalogName “XmlNameOfMySolver”. This is how
the XML block would look like.
<Problem>
<Solvers
gravityVector="{ 0.0, 0.0, -9.81 }">
<XmlNameOfMySolver name="nameOfThisSolverInstance"
verboseLevel="1"
gravityFlag="1"
temperature="297.15" />
<LinearSolverParameters newtonTol="1.0e-6"
maxIterNewton="15"
useDirectSolver="1"/>
</XmlNameOfMySolver>
</Solvers>
</Problem>

Here, we see that the XML structure defines a parent node “Problem”, that has (among many others) a child node
“Solvers”. In the “Solvers” block, we have placed the new solver block as a child node of the “Solvers” block with
the XML tag corresponding to the catalogName of the new class. We will see in details next how the GEOS internal
structure constructed from this block mirrors the XML file structure.

Instantiating the new solver

Above, we have specified an XML block with the tag “XmlNameOfMySolver”. Now, when reading the XML file and
encountering an “XmlNameOfMySolver” solver block, we add a new instance of the class CppNameOfMySolver in
the filesystem structure as explained below.
We saw that in the XML file, the new solver block appeared as child node of the XML block “Solvers”. The internal
construction mirrors this XML structure. Specifically, the new object of class CppNameOfMySolver is registered as a
subgroup (to continue the analogy used so far, as a subfolder) of its parent Group, the class PhysicsSolverManager
(that has a catalogName “Solvers”). To do this, the method CreateChild of the PhysicsSolverManager class is
used.
// Variable values in this example:
// --------------------------------
// childKey = "XmlNameOfMySolver" (string)
// childName = "nameOfThisSolverInstance" (string)
// PhysicsSolverBase::CatalogInterface = the Catalog attached to the base Solver class
// hasKeyName = bool method to test if the childKey string is present in the Catalog
// registerGroup = method to create a new instance of the solver and add it to the group␣
˓→tree

Group * PhysicsSolverManager::createChild( string const & childKey, string const &␣

˓→childName )

(continues on next page)

1.6. Developer Guide 631

GEOS Documentation

(continued from previous page)

{
Group * rval = nullptr;
if( PhysicsSolverBase::CatalogInterface::hasKeyName( childKey ) )
{
GEOS_LOG_RANK_0( GEOS_FMT( "{}: adding {} {}", getName(), childKey, childName ) );
rval = &registerGroup( childName,
PhysicsSolverBase::CatalogInterface::factory( childKey,␣
˓→childName, this ) );

}
return rval;
}

[Source: src/coreComponents/physicsSolvers/PhysicsSolverManager.cpp]
In the code listing above, we see that in the PhysicsSolverManager class, the ObjectCatalog is searched to find
the catalogName “CompositionalMultiphaseFlow” in the scope of the PhysicsSolverBase class. Then, the factory
function of the base class PhysicsSolverBase is called. The catalogName (stored in childKey) is passed as an
argument of the factory function to ensure that it instantiates an object of the desired derived class.
As explained above, this is working because 1) the XML tag matches the catalogName of the
CompositionalMultiphaseFlow class and 2) a macro is placed at the end of the .cpp file implementing the
CompositionalMultiphaseFlow class to let the ObjectCatalog know that CompositionalMultiphaseFlow is
a derived class of PhysicsSolverBase.
Note that several instances of the same type of solver can be created, as long as they each have a different name.

Filling the objects with data (wrappers)

After finding and placing the new solver Group in the filesystem hierarchy, properties are read and stored. This is done
by registering data wrappers. We refer to the documentation of the Data Repository for additional details about the
Wrapper s. The method used to do that is called registerWrapper and is placed in the class constructor when the
data is required in the XML file. Note that some properties are registered at the current (derived) class level, and other
properties can also be registered at a base class level.
Here, the only data (=wrapper) that is defined at the level of our CppNameOfMySolver class is temperature, and every-
thing else is registered at the base class level. We register a property of temperature, corresponding to the member class
m_temperature of CppNameOfMySolver. The registration also checks if a property is required or optional (here, it
is required), and provides a brief description that will be used in the auto-generated code documentation.

this->registerWrapper( viewKeyStruct::inputTemperatureString(), &m_inputTemperature ).

setInputFlag( InputFlags::REQUIRED ).
setDescription( "Temperature" );
//END_SPHINX_INCLUDE_00

[Source: src/coreComponents/physicsSolvers/fluidFlow/CompositionalMultiphaseBase.cpp]
This operation is done recursively if XML tags are nested.

To summarize:

• Every class in GEOS derive from a Group in a filesystem-like structure. A Group must have a parent Group,
can have data (in Wrapper s), and can have one or many children (the subgroups). There is an ObjectCatalog
in which the classes derived from Group are identified by a key called the catalogName.
• When parsing XML input files, GEOS inspects each object’s scope in the ObjectCatalog to find classes with
the same catalogName as the XML tag. Once it finds an XML tag in the ObjectCatalog, it registers it inside

632 Chapter 1. Table of Contents

GEOS Documentation

the filesystem structure.

• In the registration process, properties from the XML file are parsed and used to allocate member data Wrapper
s and fully instantiate the Group class.
• If XML tags are nested, subgroups are allocated and processed in a nested manner.
The correspondence between XML and class hierarchy is thus respected, and the internal object hierarchy mirrors the
XML structure.

Example: adding a new relative permeability model

This example is taken from the class BrooksCoreyRelativePermeability, derived from

RelativePermeabilityBase.

Implement a CatalogName function (.hpp):

As explained above we add the class to the ObjectCatalog in two steps. First we implement the CatalogName
function:

static string catalogName() { return "BrooksCoreyRelativePermeability"; }

[source: src/coreComponents/constitutive/relativePermeability/BrooksCoreyRelativePermeability.hpp]
Then in the .cpp file we add the macro to register the catalog entry:

REGISTER_CATALOG_ENTRY( ConstitutiveBase, BrooksCoreyRelativePermeability, string const &

˓→, Group * const )

[source: src/coreComponents/constitutive/relativePermeability/BrooksCoreyRelativePermeability.cpp]
Now every time a “BrooksCoreyRelativePermeability” string is encountered inside a Relative Permeability
catalog, we will instantiate a class BrooksCoreyRelativePermeability.

Declare the Wrapper s keys (.hpp):

When attaching properties (i.e. data Wrapper s) to a class, a similar registration process must be done. Every property
is accessed through its ViewKey namespace. In this namespace, we define string s that correspond to the tags of
XML attributes of the “BrooksCoreyRelativePermeability” block.

struct viewKeyStruct : RelativePermeabilityBase::viewKeyStruct

{
static constexpr char const * phaseMinVolumeFractionString() { return
˓→"phaseMinVolumeFraction"; }

static constexpr char const * phaseRelPermExponentString() { return

˓→"phaseRelPermExponent"; }

static constexpr char const * phaseRelPermMaxValueString() { return

˓→"phaseRelPermMaxValue"; }

static constexpr char const * volFracScaleString() { return "volFracScale"; }

} vieKeysBrooksCoreyRelativePermeability;

[source: src/coreComponents/constitutive/relativePermeability/BrooksCoreyRelativePermeability.hpp]

1.6. Developer Guide 633

GEOS Documentation

Declare data members (.hpp):

The data members are defined in the class. They will ultimately contain the data read from the XML file (other data
members not read from the XML file can also exist).

array1d< real64 > m_phaseMinVolumeFraction;

array1d< real64 > m_phaseRelPermExponent;
array1d< real64 > m_phaseRelPermMaxValue;

real64 m_volFracScale;

[source: src/coreComponents/constitutive/relativePermeability/BrooksCoreyRelativePermeability.hpp]

Implement the data registration process (registerWrapper):

The registration process done in the class constructor puts everything together. It connects the attributes values in the
XML file to class member data. For instance, in the listing below, the first registerWrapper call means that we want
to read in the XML file the attribute value corresponding to the attribute tag ‘’phaseMinVolumeFraction” defined in
the .hpp file, and that we want to store the read values into the m_phaseMinVolumeFraction data members. We see
that this input is not required. If it is absent from the XML file, the default value is used instead. The short description
that completes the registration will be added to the auto-generated documentation.

BrooksCoreyRelativePermeability::BrooksCoreyRelativePermeability( string const & name,

Group * const parent )
: RelativePermeabilityBase( name, parent )
{
registerWrapper( viewKeyStruct::phaseMinVolumeFractionString(), &m_
˓→phaseMinVolumeFraction ).

setApplyDefaultValue( 0.0 ).
setInputFlag( InputFlags::OPTIONAL ).
setDescription( "Minimum volume fraction value for each phase" );

registerWrapper( viewKeyStruct::phaseRelPermExponentString(), &m_phaseRelPermExponent␣

˓→).
setApplyDefaultValue( 1.0 ).
setInputFlag( InputFlags::OPTIONAL ).
setDescription( "Minimum relative permeability power law exponent for each phase" );

registerWrapper( viewKeyStruct::phaseRelPermMaxValueString(), &m_phaseRelPermMaxValue␣

˓→).
setApplyDefaultValue( 0.0 ).
setInputFlag( InputFlags::OPTIONAL ).
setDescription( "Maximum relative permeability value for each phase" );

registerWrapper( viewKeyStruct::volFracScaleString(), &m_volFracScale ).

setApplyDefaultValue( 1.0 ).
setDescription( "Factor used to scale the phase relative permeability, defined as:␣
˓→one minus the sum of the phase minimum volume fractions." );

[source: src/coreComponents/constitutive/relativePermeability/BrooksCoreyRelativePermeability.cpp]

634 Chapter 1. Table of Contents

GEOS Documentation

The XML block

We are ready to use the relative permeability model in GEOS. The corresponding XML block (child node of the
“Constitutive” block) reads:

With this construct, we instruct the ConstitutiveManager class (whose catalogName is “Constitutive”) to instan-
tiate a subgroup of type BrooksCoreyRelativePermeability. We also fill the data members of the values that we
want to use for the simulation. For a simulation with multiple regions, we could define multiple relative permeability
models in the “Constitutive” XML block (yielding multiple relperm subgroups in GEOS), with a unique name attribute
for each model.
For more examples on how to contribute to GEOS, please read Adding a new Physics Solver

Input Schema Generation

A schema file is a useful tool for validating input .xml files and constructing user-interfaces. Rather than manually
maintaining the schema during development, GEOS is designed to automatically generate one by traversing the docu-
mentation structure.
To generate the schema, run GEOS with the input, schema, and the (optional) schema_level arguments, i.e.: geosx -i
input.xml -s schema.xsd. There are two ways to limit the scope of the schema:
1. Setting the verbosity flag for an object in the documentation structure. If the schema-level argument is used, then
only objects (and their children) and attributes with (verbosity < schema-level) will be output.
2. By supplying a limited input xml file. When GEOS builds its data structure, it will only include objects that are
listed within the xml (or those that are explicitly appended when those objects are initialized). The code will add
all available attributes for these objects to the schema.
To take advantage of this design it is necessary to use the automatic xml parsing approach that relies upon the docu-
mentation node. If values are read in manually, then the schema can not be used to validate xml those inputs.
Note: the lightweight xml parser that is used in GEOS cannot be used to validate inputs with the schema directly. As
such, it is necessary to use an external tool for validation, such as the geosx_tools python module.

Working with data in GEOS

In GEOS, data is typically registered in the Data Repository. This allows for the writing/reading of data to/from
restart and plot files. Any object that derives from Group may have data registered on it through the methods de-
scribed in Group. Similarly, accessing data from outside the scope of an object is possible through one of the various
Group::get(). Of course, for temporary data that does not need to persist between cycles, or across physics packages,
you may simply define member or local variable which will not be registered with the Data Repository.

1.6. Developer Guide 635

GEOS Documentation

Working with data on the Mesh objects

The mesh objects in GEOS such as the FaceManager or NodeManager, are derived from ObjectManagerBase, which
in turn derives from Group. The important distinction is that ObjectManagerBase contains various members that are
useful when defining mesh object managers. When considering data that is attached to a mesh object, we group the
data into two categories:
• Intrinsic data is data that is required to describe the object. For instance, to define a Node, the NodeManager con-
tains an array of positions corresponding to each Node it contains. Thus the ReferencePosition is Intrinsic
data. Intrinsic data is almost always a member of the mesh object, and is registered on the mesh object in the
constructor of mesh object itself.
• Field data (or Extrinsic data) is data that is not required to define the object. For instance, a physics package
may request that a Velocity value be stored on the nodes. Appropriately the data will be registered on the
NodeManager. However, this data is not required to define a Node, and is viewed as Fields or Extrinsic.
Field data is never a member of the mesh object, and is typically registered on the mesh object outside of the
definition of the mesh object (i.e. from a physics solver).

Registering Intrinsic data on a Mesh Object

As mentioned above, Intrinsic data is typically a member of the mesh object, and is registered in the constructor
of the mesh Object. Taking the NodeManager and the referencePosition as an example, we point out that the
reference position is actually a member in the NodeManager.

/**
* @brief Get the mutable reference position array. This table will contain all the␣
˓→node coordinates.

* @return reference position array

*/
array2d< real64, nodes::REFERENCE_POSITION_PERM > & referencePosition() { return m_
˓→referencePosition; }

/**
* @brief Provide an immutable arrayView of the reference position. This table will␣
˓→contain all the node coordinates.

* @return an immutable arrayView of the reference position.

arrayView2d< real64 const, nodes::REFERENCE_POSITION_USD > referencePosition() const

{ return m_referencePosition; }

This member is registered in the constructor for the NodeManager.

NodeManager::NodeManager( string const & name,

Group * const parent ):
ObjectManagerBase( name, parent ),
m_referencePosition( 0, 3 )
{
registerWrapper( viewKeyStruct::referencePositionString(), &m_referencePosition );

Finally in order to access this data, the NodeManager provides explicit accessors.

/**
* @brief Get the mutable reference position array. This table will contain all the␣
˓→node coordinates.

(continues on next page)

636 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

* @return reference position array
*/
array2d< real64, nodes::REFERENCE_POSITION_PERM > & referencePosition() { return m_
˓→referencePosition; }

/**
* @brief Provide an immutable arrayView of the reference position. This table will␣
˓→contain all the node coordinates.

* @return an immutable arrayView of the reference position.

arrayView2d< real64 const, nodes::REFERENCE_POSITION_USD > referencePosition() const

{ return m_referencePosition; }

Thus the interface for Intrinsic data is set by the object that it is a part of, and the developer may only access the
data through the accesssors from outside of the mesh object class scope.

Registering Field data on a Mesh Object

To register Field data, there are many ways a developer may proceed. We will use the example of
registering a totalDisplacement on the NodeManager from the SolidMechanics solver. The most
general approach is to define a string key and call one of the Group::registerWrapper() functions from
PhysicsSolverBase::registerDataOnMesh(). Then when you want to use the data, you can call
Group::getReference(). For example this would look something like:

void SolidMechanicsLagrangianFEM::registerDataOnMesh( Group * const MeshBodies )

{
for( auto & mesh : MeshBodies->GetSubGroups() )
{
NodeManager & nodes = mesh.second->groupCast< MeshBody * >()->getMeshLevel( 0 ).
˓→getNodeManager();

nodes.registerWrapper< array2d< real64, nodes::TOTAL_DISPLACEMENT_PERM > >(␣

˓→ keys::totalDisplacement ).
setPlotLevel( PlotLevel::LEVEL_0 ).
setRegisteringObjects( this->getName()).
setDescription( "An array that holds the total displacements on the nodes." ).
reference().resizeDimension< 1 >( 3 );
}
}

and

arrayView2d< real64, nodes::TOTAL_DISPLACEMENT_USD > const & u = nodes.getReference<␣

˓→array2d< real64, nodes::TOTAL_DISPLACEMENT_PERM > >( keys::totalDisplacement );

... do something with u

This approach is flexible and extendible, but is potentially error prone due to its verbosity and lack of information
centralization. Therefore we also provide a more controlled/uniform method by which to register and extract commonly
used data on the mesh. The trait approach requires the definition of a traits struct for each data object that
will be supported. To apply the trait approach to the example use case shown above, there should be the following
definition somewhere in a header file:

1.6. Developer Guide 637

GEOS Documentation

namespace fields
{
struct totalDisplacement
{
static constexpr auto key = "totalDisplacement";
using DataType = real64;
using Type = array2d< DataType, nodes::TOTAL_DISPLACEMENT_PERM >;
static constexpr DataType defaultValue = 0;
static constexpr auto plotLevel = dataRepository::PlotLevel::LEVEL_0;

/// Description of the data associated with this trait.

static constexpr auto description = "An array that holds the total displacements on␣
˓→the nodes.";

};
}

Also note that you should use the DECLARE_FIELD C++ macro that will perform this tedious task for you. Then the
registration is simplified as follows:

void SolidMechanicsLagrangianFEM::registerDataOnMesh( Group * const MeshBodies )

{
for( auto & mesh : MeshBodies->GetSubGroups() )
{
NodeManager & nodes = mesh.second->groupCast< MeshBody * >()->getMeshLevel( 0 ).
˓→getNodeManager();

nodes.registerField< fields::totalDisplacement >( this->getName() ).resizeDimension<␣

˓→1 >( 3 );

}
}

And to extract the data, the call would be:

arrayView2d< real64, nodes::TOTAL_DISPLACEMENT_USD > const & u = nodes.getField<␣

˓→fields::totalDisplacement >();

... do something with u

The end result of the trait approach to this example is that the developer has defined a standard specification for
totalDisplacement, which may be used uniformly across the code.

Mesh Hierarchy
In GEOS, the mesh structure consists of a hierarchy of classes intended to encapsulate data and functionality for each
topological type. Each class in the mesh hierarchy represents a distinct topological object, such as a nodes, edges,
faces, elements, etc. The mesh data structure is illustrated in an object instantiation hierarchy. The object instantiation
hierarchy differs from a “class hierarchy” in that it shows how instantiations of each class relate to each other in the
data hierarchy rather than how each class type relates to each other in an inheritance diagram.
To illustrate the mesh hierarchy, we propose to present it along with a model with two regions (Top and Bottom) (Fig.
1.96).

638 Chapter 1. Table of Contents

matrix sparsity pattern can be constructed.

Thus, each instance of DofManager only supports one type of numbering. If both types are required, the user is advised
to maintain two separate instances of DofManager.
DofManager allocates a separate “DOF index” array for each field on the mesh. It is an array of global indices, where
each value represents the first DoF index for that field and location (or equivalently, the row and column offset of that
location’s equations and variables for the field in the matrix). For example, if index array for a field with 3 components
contains the value N, global DoF numbers for that location will be N, N+1, N+2. DoF on ghosted locations have the
same indices as on the owning rank. The array is stored under a generated key, which can be queried from the DoF
manager, and is typically used in system assembly.

Methods

The main methods of DoF Manager are:

• setDomain: sets the domain containing mesh bodies to operate on domain identifies the global domain

void setDomain( DomainPartition * const domain );

• addField: creates a new set of DoF, labeled field, with specific location. Default number of components
is 1, like for pressure in flux. Default regions is the empty string, meaning all domain.

void addField( string const & fieldName,

Location const location,
localIndex const components,
arrayView1d< string const > const & regions );

• addCoupling: creates a coupling between two fields (rowField and colField) according to a given
connectivity in the regions defined by regions. Both fields (row and column) must have already been defined
on the regions where is required the coupling among them. Default value for regions is the whole intersection
between the regions where the first and the second fields are defined. This method also creates the coupling
between colField and rowField, i.e. the transpose of the rectangular sparsity pattern. This default behaviour
can be disabled by passing symmetric = false.

void addCoupling( string const & rowField,

string const & colField,
Connectivity const connectivity,
arrayView1d< string const > const & regions,
bool const symmetric );

• reorderByRank: finish populating field and coupling information and apply DoF re-numbering

void reorderByRank();

• getKey: returns the “key” associated with the field, that can be used to access the index array on the mesh object
manager corresponding to field’s location.

string const & getKey( string const & fieldName );

• clear: removes all fields, releases memory and re-opens the DofManager

void clear();

• setSparsityPattern: populates the sparsity for the given rowField and colField into matrix. Closes the
matrix if closePattern is true.

1.6. Developer Guide 643

GEOS Documentation

void setSparsityPattern( MATRIX & matrix,

string const & rowField,
string const & colField,
bool closePattern = true) const;

• setSparsityPattern: populates the sparsity for the full system matrix into matrix. Closes the matrix if
closePattern is true.

void setSparsityPattern( MATRIX & matrix,

bool closePattern = true ) const;

• numGlobalDofs: returns the total number of DoFs across all processors for the specified name field (if given)
or all fields (if empty).

globalIndex numGlobalDofs( string const & field = "" ) const;

• numLocalDofs: returns the number of DoFs on this process for the specified name field (if given) or all fields
(if empty).

localIndex numLocalDofs( string const & field = "" ) const;

• printFieldInfo: prints a short summary of declared fields and coupling to the output stream os.

void printFieldInfo( std::ostream & os = std::cout ) const;

Example

Here we show how the sparsity pattern is computed for a simple 2D quadrilateral mesh with 6 elements. Unknowns
are pressure, located on the element center, and displacements (x and y components), located on the nodes. For fluxes,
a two-point flux approximation (TPFA) is used. The representation of the sparsity pattern of the CL matrix (connec-
tors/locations) for the simple mesh, shown in Fig. 1.99, is reported in Fig. 1.100. It can be noticed that the two unknowns
for the displacements x and y are grouped together. Elements are the connectivity for DoF on nodes (Finite Element
Method for displacements) and on elements (pressures). Faces are the connectivity for DoF on elements (Finite Volume
Method for pressure), being the flux computation based on the pressure on the two adjacent elements.

Fig. 1.99: Small 2D quadrilateral mesh used for this examples. Nodes are label with black numbers, elements with
light gray numbers and faces with italic dark gray numbers.

Fig. 1.100: Sparsity pattern of the binary matrix connections/locations.

The global sparsity pattern, shown in Fig. 1.101, is obtained through the symbolic multiplication of the transpose of
the matrix CL and the matrix itself, i.e. P = CT
L CL .

Fig. 1.101: Sparsity pattern of the global matrix, where red and green entries are related to the displacement field and
to the pressure field, respectively. Blue entries represent coupling blocks.

Real mesh and patterns

Now we build the pattern of the Jacobian matrix for a simple 3D mesh, shown in Fig. 1.102. Fields are:
• displacement (location: node, connectivity: element) defined on the blue, orange and red regions;

644 Chapter 1. Table of Contents

GEOS Documentation

• pressure (location: element, connectivity: face) defined on the green, orange and red regions;
• mass matrix (location: element, connectivity: element) defined on the green region only.
Moreover, following coupling are imposed:
• displacement-pressure (connectivity: element) on the orange region only;
• pressure-mass matrix and transpose (connectivity: element) everywhere it is possibile.

Fig. 1.102: Real mesh used to compute the Jacobian pattern.

Fig. 1.103 shows the global pattern with the field-based ordering of unknowns. Different colors mean different fields.
Red unkwnons are associated with displacement, yellow ones with pressure and blue ones with mass matrix. Orange
means the coupling among displacement and pressure, while green is the symmetric coupling among pressure and mass
matrix.

Fig. 1.103: Global pattern with field-based ordering. Red is associated with displacement unknowns, yellow with
pressure ones and blue with those of mass matrix field. Orange means the coupling among displacement and pressure,
while green is the symmetric coupling among pressure and mass matrix.

Fig. 1.104 shows the global pattern with the MPI rank-based ordering of unknowns. In this case, just two processes are
used. Again, different colors indicate different ranks.

Fig. 1.104: Global pattern with MPI rank-based ordering. Red unkwnons are owned by rank 0 and green ones by rank
1. Blue indicates the coupling among the two processes.

LvArray
Use in GEOS

LvArray containers are used in GEOS as primary storage mechanism for mesh topology, field data and any other type of
“large” data sets (i.e. ones that scale with the size of the problem). When allocating a new field, using one of LvArray
containers is mandatory if the data is meant to be used in any computational kernel. The file common/DataTypes.hpp
provides shorthand aliases for commonly used containers:

/**
* @name Aliases for LvArray::Array class family.
*/
///@{

/// Multidimensional array type. See LvArray:Array for details.

template< typename T,
int NDIM,
typename PERMUTATION=camp::make_idx_seq_t< NDIM > >
using Array = LvArray::Array< T, NDIM, PERMUTATION, localIndex, LvArray::ChaiBuffer >;

/// Multidimensional array view type. See LvArray:ArrayView for details.

template< typename T,
int NDIM,
int USD = NDIM - 1 >
using ArrayView = LvArray::ArrayView< T, NDIM, USD, localIndex, LvArray::ChaiBuffer >;

/// Multidimensional array slice type. See LvArray:ArraySlice for details.

(continues on next page)

1.6. Developer Guide 645

GEOS Documentation

(continued from previous page)

template< typename T, int NDIM, int USD = NDIM - 1 >
using ArraySlice = LvArray::ArraySlice< T, NDIM, USD, localIndex >;

/// Multidimensional stack-based array type. See LvArray:StackArray for details.

template< typename T, int NDIM, int MAXSIZE, typename PERMUTATION=camp::make_idx_seq_t<␣
˓→NDIM > >

using StackArray = LvArray::StackArray< T, NDIM, PERMUTATION, localIndex, MAXSIZE >;

///@}

/**
* @name Short-hand aliases for commonly used array types.
*/
///@{

/// Alias for a local (stack-based) rank-1 tensor type

using R1Tensor = Tensor< real64, 3 >;
/// Alias for a local (stack-based) rank-1 tensor type using 32 bits integers
using R1Tensor32 = Tensor< real32, 3 >;

/// Alias for a local (stack-based) rank-2 Voigt tensor type

using R2SymTensor = Tensor< real64, 6 >;

/// Alias for 1D array.

template< typename T >
using array1d = Array< T, 1 >;

/// Alias for 1D array view.

template< typename T >
using arrayView1d = ArrayView< T, 1 >;

/// Alias for 1D array slice.

template< typename T, int USD = 0 >
using arraySlice1d = ArraySlice< T, 1, USD >;

/// Alias for 1D stack array.

template< typename T, int MAXSIZE >
using stackArray1d = StackArray< T, 1, MAXSIZE >;

/// Alias for 2D array.

template< typename T, typename PERMUTATION=camp::make_idx_seq_t< 2 > >
using array2d = Array< T, 2, PERMUTATION >;

/// Alias for 2D array view.

template< typename T, int USD = 1 >
using arrayView2d = ArrayView< T, 2, USD >;

/// Alias for 2D array slice.

template< typename T, int USD = 1 >
using arraySlice2d = ArraySlice< T, 2, USD >;

(continues on next page)

646 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

/// Alias for 2D stack array.
template< typename T, int MAXSIZE >
using stackArray2d = StackArray< T, 2, MAXSIZE >;

/// Alias for 3D array.

template< typename T, typename PERMUTATION=camp::make_idx_seq_t< 3 > >
using array3d = Array< T, 3, PERMUTATION >;

/// Alias for 3D array view.

template< typename T, int USD=2 >
using arrayView3d = ArrayView< T, 3, USD >;

/// Alias for 3D array slice.

template< typename T, int USD=2 >
using arraySlice3d = ArraySlice< T, 3, USD >;

/// Alias for 3D stack array.

template< typename T, int MAXSIZE >
using stackArray3d = StackArray< T, 3, MAXSIZE >;

/// Alias for 4D array.

template< typename T, typename PERMUTATION=camp::make_idx_seq_t< 4 > >
using array4d = Array< T, 4, PERMUTATION >;

/// Alias for 4D array view.

template< typename T, int USD=3 >
using arrayView4d = ArrayView< T, 4, USD >;

/// Alias for 4D array slice.

template< typename T, int USD=3 >
using arraySlice4d = ArraySlice< T, 4, USD >;

/// Alias for 4D stack array.

template< typename T, int MAXSIZE >
using stackArray4d = StackArray< T, 4, MAXSIZE >;

/// Alias for 5D array.

template< typename T, typename PERMUTATION=camp::make_idx_seq_t< 5 > >
using array5d = Array< T, 5, PERMUTATION >;

/// Alias for 5D array view.

template< typename T, int USD=4 >
using arrayView5d = ArrayView< T, 5, USD >;

/// Alias for 5D array slice.

template< typename T, int USD=4 >
using arraySlice5d = ArraySlice< T, 5, 4 >;

/// Alias for 5D stack array.

template< typename T, int MAXSIZE >
using stackArray5d = StackArray< T, 5, MAXSIZE >;

(continues on next page)

1.6. Developer Guide 647

GEOS Documentation

(continued from previous page)

///@}

/**
* @name Aliases for sorted arrays and set types.
*/
///@{

/// A set of local indices.

template< typename T >
using set = std::set< T >;

/// A sorted array of local indices.

template< typename T >
using SortedArray = LvArray::SortedArray< T, localIndex, LvArray::ChaiBuffer >;

/// A sorted array view of local indices.

template< typename T >
using SortedArrayView = LvArray::SortedArrayView< T, localIndex, LvArray::ChaiBuffer >;

///@}

/**
* @name Aliases for LvArray::ArrayOfArrays class family.
*/
///@{

/// Array of variable-sized arrays. See LvArray::ArrayOfArrays for details.

template< typename T, typename INDEX_TYPE=localIndex >
using ArrayOfArrays = LvArray::ArrayOfArrays< T, INDEX_TYPE, LvArray::ChaiBuffer >;

/// View of array of variable-sized arrays. See LvArray::ArrayOfArraysView for details.

template< typename T, typename INDEX_TYPE=localIndex, bool CONST_SIZES=std::is_const< T >
˓→::value >

using ArrayOfArraysView = LvArray::ArrayOfArraysView< T, INDEX_TYPE const, CONST_SIZES,␣

˓→LvArray::ChaiBuffer >;

/// Array of variable-sized sets. See LvArray::ArrayOfSets for details.

template< typename T, typename INDEX_TYPE=localIndex >
using ArrayOfSets = LvArray::ArrayOfSets< T, INDEX_TYPE, LvArray::ChaiBuffer >;

/// View of array of variable-sized sets. See LvArray::ArrayOfSetsView for details.

template< typename T, typename INDEX_TYPE=localIndex >
using ArrayOfSetsView = LvArray::ArrayOfSetsView< T, INDEX_TYPE const,␣
˓→LvArray::ChaiBuffer >;

/// Alias for Sparsity pattern class.

template< typename COL_INDEX, typename INDEX_TYPE=localIndex >
using SparsityPattern = LvArray::SparsityPattern< COL_INDEX, INDEX_TYPE,␣
˓→LvArray::ChaiBuffer >;

/// Alias for Sparsity pattern View.

template< typename COL_INDEX, typename INDEX_TYPE=localIndex >
(continues on next page)

648 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

using SparsityPatternView = LvArray::SparsityPatternView< COL_INDEX, INDEX_TYPE const,␣
˓→LvArray::ChaiBuffer >;

/// Alias for CRS Matrix class.

template< typename T, typename COL_INDEX=globalIndex >
using CRSMatrix = LvArray::CRSMatrix< T, COL_INDEX, localIndex, LvArray::ChaiBuffer >;

/// Alias for CRS Matrix View.

template< typename T, typename COL_INDEX=globalIndex >
using CRSMatrixView = LvArray::CRSMatrixView< T, COL_INDEX, localIndex const,␣
˓→LvArray::ChaiBuffer >;

///@}

LvArray documentation

Please refer to the full LvArray documentation for details on each of the classes.

Kernel interface
Finite Element Method Kernel Interface

The finite element method kernel interface (FEMKI) specifies an API for the launching of computational kernels for
solving physics discretized using the finite element method. Using this approach, a set of generic element looping
pattens and kernel launching functions may be implemented, and reused by various physics solvers that contain kernels
conforming to the FEMKI.
There are several main components of the FEMKI:
1. A collection of element looping functions that provide various looping patterns, and call the launch function.
2. The kernel interface, which is specified by the finiteElement::KernelBase class. Each physics solver will define
a class that contains its kernels functions, most likely deriving, or conforming to the API specified by the Ker-
nelBase class. Also part of this class will typically be a nested StackVariables class that defines a collection
of stack variables for use in the various kernel interface functions.
3. A launch function, which launches the kernel, and calls the kernel interface functions conforming to the interface
defined by KernelBase. This function is actually a member function of the Kernel class, so it may be overridden
by a specific physics kernel, allowing complete customization of the interface, while maintaining the usage of
the looping patterns.

A Generic Element Looping Pattern

One example of a looping pattern is the regionBasedKernelApplication function.

The contents of the looping function are displayed here:

/**
* @brief Performs a loop over specific regions (by type and name) and calls a kernel␣
˓→launch on the subregions

* with compile time knowledge of sub-loop bounds such as number of nodes and␣
˓→quadrature points per element.

* @tparam POLICY The RAJA launch policy to pass to the kernel launch.
* @tparam CONSTITUTIVE_BASE The common base class for constitutive pass-thru/dispatch␣
˓→which gives the kernel

(continues on next page)

1.6. Developer Guide 649

GEOS Documentation

(continued from previous page)

* launch compile time knowledge of the constitutive model. This is achieved through a␣
˓→call to the

* ConstitutivePassThru function which should have a specialization for CONSTITUTIVE_

˓→BASE implemented in

* order to perform the compile time dispatch.

* @tparam SUBREGION_TYPE The type of subregion to loop over. TODO make this a parameter␣
˓→pack?

* @tparam KERNEL_FACTORY The type of @p kernelFactory, typically an instantiation of @c␣

˓→KernelFactory, and

* must adhere to that interface.

* @param mesh The MeshLevel object.
* @param targetRegions The names of the target regions(of type @p SUBREGION_TYPE) to␣
˓→apply the @p KERNEL_TEMPLATE.

* @param finiteElementName The name of the finite element.

* @param constitutiveStringName The key to the constitutive model name found on the␣
˓→Region.

* @param kernelFactory The object used to construct the kernel.

* @return The maximum contribution to the residual, which may be used to scale the␣
˓→residual.

*
* @details Loops over all regions Applies/Launches a kernel specified by the @p KERNEL_
˓→TEMPLATE through

* #::geos::finiteElement::KernelBase::kernelLaunch().
*/
template< typename POLICY,
typename CONSTITUTIVE_BASE,
typename SUBREGION_TYPE,
typename KERNEL_FACTORY >
static
real64 regionBasedKernelApplication( MeshLevel & mesh,
arrayView1d< string const > const & targetRegions,
string const & finiteElementName,
string const & constitutiveStringName,
KERNEL_FACTORY & kernelFactory )
{
GEOS_MARK_FUNCTION;
// save the maximum residual contribution for scaling residuals for convergence␣
˓→criteria.

real64 maxResidualContribution = 0;

NodeManager & nodeManager = mesh.getNodeManager();

EdgeManager & edgeManager = mesh.getEdgeManager();
FaceManager & faceManager = mesh.getFaceManager();
ElementRegionManager & elementRegionManager = mesh.getElemManager();

// Loop over all sub-regions in regions of type SUBREGION_TYPE, that are listed in the␣
˓→ targetRegions array.
elementRegionManager.forElementSubRegions< SUBREGION_TYPE >( targetRegions,
[&constitutiveStringName,
&maxResidualContribution,
&nodeManager,
&edgeManager,
(continues on next page)

650 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

&faceManager,
&kernelFactory,
&finiteElementName]
( localIndex const␣
˓→targetRegionIndex, auto & elementSubRegion )
{
localIndex const numElems = elementSubRegion.size();

// Get the constitutive model...and allocate a null constitutive model if required.

constitutive::ConstitutiveBase * constitutiveRelation = nullptr;

constitutive::NullModel * nullConstitutiveModel = nullptr;
if( elementSubRegion.template hasWrapper< string >( constitutiveStringName ) )
{
string const & constitutiveName = elementSubRegion.template getReference< string >
˓→( constitutiveStringName );

constitutiveRelation = &elementSubRegion.template getConstitutiveModel(␣

˓→constitutiveName );

}
else
{
nullConstitutiveModel = &elementSubRegion.template registerGroup<␣
˓→constitutive::NullModel >( "nullModelGroup" );

constitutiveRelation = nullConstitutiveModel;
}

// Call the constitutive dispatch which converts the type of constitutive model into␣
˓→a compile time constant.
constitutive::ConstitutivePassThru< CONSTITUTIVE_BASE >::execute(␣
˓→*constitutiveRelation,

[&
˓→maxResidualContribution,

&nodeManager,
&edgeManager,
&faceManager,
targetRegionIndex,
&kernelFactory,
&elementSubRegion,
&
˓→finiteElementName,

numElems]
( auto &␣
˓→castedConstitutiveRelation )

{
FiniteElementBase &
subRegionFE = elementSubRegion.template getReference< FiniteElementBase >(␣
˓→finiteElementName );

finiteElement::FiniteElementDispatchHandler< SELECTED_FE_TYPES >::dispatch3D(␣

˓→subRegionFE,
[&
˓→maxResidualContribution,

(continues on next page)

1.6. Developer Guide 651

GEOS Documentation

(continued from previous page)

&
˓→ nodeManager,
&
˓→ edgeManager,
&
˓→ faceManager,
␣
˓→ targetRegionIndex,
&
˓→ kernelFactory,
&
˓→ elementSubRegion,
␣
˓→ numElems,
&
˓→ castedConstitutiveRelation] ( auto const finiteElement )
{
auto kernel = kernelFactory.createKernel( nodeManager,
edgeManager,
faceManager,
targetRegionIndex,
elementSubRegion,
finiteElement,
castedConstitutiveRelation );

using KERNEL_TYPE = decltype( kernel );

// Call the kernelLaunch function, and store the maximum contribution to the␣
˓→residual.
maxResidualContribution =
std::max( maxResidualContribution,
KERNEL_TYPE::template kernelLaunch< POLICY, KERNEL_TYPE >( numElems,␣
˓→kernel ) );

} );
} );

// Remove the null constitutive model (not required, but cleaner)

if( nullConstitutiveModel )
{
elementSubRegion.deregisterGroup( "nullModelGroup" );
}

} );

return maxResidualContribution;
}

This pattern may be used with any kernel class that either:
1. Conforms to the KernelBase interface by defining each of the kernel functions in KernelBase.
2. Defines its own kernelLaunch function that conforms the the signature of KernelBase::kernelLaunch. This
option essentially allows for a custom kernel that does not conform to the interface defined by KernelBase and
KernelBase::kernelLaunch.

652 Chapter 1. Table of Contents

GEOS Documentation

The KernelBase::kernelLaunch Interface

The kernelLaunch function is a member of the kernel class itself. As mentioned above, a physics implementation
may use the existing KernelBase interface, or define its own. The KernelBase::kernelLaunch function defines
a launching policy, and an internal looping pattern over the quadrautre points, and calls the functions defined by the
KernelBase as shown here:

template< typename POLICY,

typename KERNEL_TYPE >
static
real64
kernelLaunch( localIndex const numElems,
KERNEL_TYPE const & kernelComponent )
{
GEOS_MARK_FUNCTION;

// Define a RAJA reduction variable to get the maximum residual contribution.

RAJA::ReduceMax< ReducePolicy< POLICY >, real64 > maxResidual( 0 );

forAll< POLICY >( numElems,

[=] GEOS_HOST_DEVICE ( localIndex const k )
{
typename KERNEL_TYPE::StackVariables stack;

kernelComponent.setup( k, stack );
// #pragma unroll
for( integer q=0; q<numQuadraturePointsPerElem; ++q )
{
kernelComponent.quadraturePointKernel( k, q, stack );
}
maxResidual.max( kernelComponent.complete( k, stack ) );
} );
return maxResidual.get();
}

Each of the KernelBase functions called in the KernelBase::kernelLaunch function are intended to provide a
certain amount of modularity and flexibility for the physics implementations. The general purpose of each function is
described by the function name, but may be further descibed by the function documentation found here.

Constitutive models
In GEOS, all constitutive models defining fluid and rock properties are implemented in the namespace constitutive
and derived from a common base class, ConstitutiveBase. All objects are owned and handled by the
ConstitutiveManager.

Standalone models

Standalone constitutive models implement constitutive laws such as:

• mechanical material models (linear elasticity, plasticity, etc.),
• PVT fluid behaviors,
• relative permeability relationships,
• porosity and permeability dependencies on state variables,

1.6. Developer Guide 653

GEOS Documentation

• contact laws.

Storage, allocation, and update of properties

Each constitutive model owns, as member variables, LvArray::Array containers that hold the properties (or fields)
and their derivatives with respect to the other fields needed to update each property. Each property is stored as an array
with the first dimension representing the elementIndex and the second dimension storing the index of the integration
point. These dimensions are determined by the number of elements of the subregion on which each constitutive model
is registered, and by the chosen discretization method. Vector and tensor fields have an additional dimension to identify
their components. Similarly, an additional dimension is necessary for multiphase fluid models with properties defined
for each component in each phase. For example, a single-phase fluid model where density and viscosity are functions
of the fluid pressure has the following members:
array2d< real64 > m_density;
array2d< real64 > m_dDensity_dPressure;
array2d< real64 > m_dDensity_dTemperature;

array2d< real64 > m_density_n;

array2d< real64 > m_viscosity;

array2d< real64 > m_dViscosity_dPressure;
array2d< real64 > m_dViscosity_dTemperature;

array2d< real64 > m_internalEnergy;

array2d< real64 > m_internalEnergy_n;
array2d< real64 > m_dInternalEnergy_dPressure;
array2d< real64 > m_dInternalEnergy_dTemperature;

array2d< real64 > m_enthalpy;

array2d< real64 > m_dEnthalpy_dPressure;
array2d< real64 > m_dEnthalpy_dTemperature;

Resizing all fields of the constitutive models happens during the initialization phase by the ConstitutiveManger
through a call to ConstitutiveManger::hangConstitutiveRelation, which sets the appropriate subRegion as
the parent Group of each constitutive model object. This function also resizes all fields based on the size of the subregion
and the number of quadrature points on it, by calling CONSTITUTIVE_MODEL::allocateConstitutiveData. For
the single phase fluid example used before, this call is:
void SingleFluidBase::allocateConstitutiveData( Group & parent,
localIndex const␣
˓→numConstitutivePointsPerParentIndex )

{
ConstitutiveBase::allocateConstitutiveData( parent,␣
˓→numConstitutivePointsPerParentIndex );

resize( parent.size() );

m_density.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_dDensity_dPressure.resize( parent.size(), numConstitutivePointsPerParentIndex );
m_dDensity_dTemperature.resize( parent.size(), numConstitutivePointsPerParentIndex );
m_density_n.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_viscosity.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_dViscosity_dPressure.resize( parent.size(), numConstitutivePointsPerParentIndex );
(continues on next page)

654 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

m_dViscosity_dTemperature.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_internalEnergy.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_internalEnergy_n.resize( parent.size(), numConstitutivePointsPerParentIndex );
m_dInternalEnergy_dPressure.resize( parent.size(), numConstitutivePointsPerParentIndex␣
˓→);

m_dInternalEnergy_dTemperature.resize( parent.size(),␣
˓→numConstitutivePointsPerParentIndex );

m_enthalpy.resize( parent.size(), numConstitutivePointsPerParentIndex );

m_dEnthalpy_dPressure.resize( parent.size(), numConstitutivePointsPerParentIndex );
m_dEnthalpy_dTemperature.resize( parent.size(), numConstitutivePointsPerParentIndex );
}

Any property or field stored on a constitutive model must be updated within a computational kernel to ensure that host
and device memory in GPUs are properly synced, and that any updates are performed on device. Some properties
are updated within finite element kernels of specific physics (such as stress in a mechanics kernel). Consequently, for
each constitutive model class, a corresponding nameOfTheModelUpdates, which only contains LvArray::arrayView
containers to the data, can be captured by value inside computational kernels. For example, for the single phase fluid
model Updates are:

/**
* @brief Base class for single-phase fluid model kernel wrappers.
*/
class SingleFluidBaseUpdate
{
public:

/**
* @brief Get number of elements in this wrapper.
* @return number of elements
*/
GEOS_HOST_DEVICE
localIndex numElems() const { return m_density.size( 0 ); }

/**
* @brief Get number of gauss points per element.
* @return number of gauss points per element
*/
GEOS_HOST_DEVICE
localIndex numGauss() const { return m_density.size( 1 ); };

protected:

/**
* @brief Constructor.
* @param density fluid density
* @param dDens_dPres derivative of density w.r.t. pressure
* @param viscosity fluid viscosity
* @param dVisc_dPres derivative of viscosity w.r.t. pressure
*/
SingleFluidBaseUpdate( arrayView2d< real64 > const & density,
(continues on next page)

1.6. Developer Guide 655

GEOS Documentation

(continued from previous page)

arrayView2d< real64 > const & dDens_dPres,
arrayView2d< real64 > const & viscosity,
arrayView2d< real64 > const & dVisc_dPres )
: m_density( density ),
m_dDens_dPres( dDens_dPres ),
m_viscosity( viscosity ),
m_dVisc_dPres( dVisc_dPres )
{}

/**
* @brief Copy constructor.
*/
SingleFluidBaseUpdate( SingleFluidBaseUpdate const & ) = default;

/**
* @brief Move constructor.
*/
SingleFluidBaseUpdate( SingleFluidBaseUpdate && ) = default;

/**
* @brief Deleted copy assignment operator
* @return reference to this object
*/
SingleFluidBaseUpdate & operator=( SingleFluidBaseUpdate const & ) = delete;

/**
* @brief Deleted move assignment operator
* @return reference to this object
*/
SingleFluidBaseUpdate & operator=( SingleFluidBaseUpdate && ) = delete;

/// Fluid density

arrayView2d< real64 > m_density;

/// Derivative of density w.r.t. pressure

arrayView2d< real64 > m_dDens_dPres;

/// Fluid viscosity

arrayView2d< real64 > m_viscosity;

/// Derivative of viscosity w.r.t. pressure

arrayView2d< real64 > m_dVisc_dPres;

Because Updates classes are responsible for updating the fields owned by the constitutive models, they also implement
all functions needed to perform property updates, such as:

private:
/**
* @brief Compute fluid properties and derivatives at a single point.
* @param[in] pressure the target pressure value
* @param[out] density fluid density
(continues on next page)

656 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

* @param[out] dDensity_dPressure fluid density derivative w.r.t. pressure
* @param[out] viscosity fluid viscosity
* @param[out] dViscosity_dPressure fluid viscosity derivative w.r.t. pressure
*/
GEOS_HOST_DEVICE
virtual void compute( real64 const pressure,
real64 & density,
real64 & dDensity_dPressure,
real64 & viscosity,
real64 & dViscosity_dPressure ) const = 0;

/**
* @brief Compute fluid properties and derivatives at a single point.
* @param[in] pressure the target pressure value
* @param[in] temperature the target temperature value
* @param[out] density fluid density
* @param[out] dDensity_dPressure fluid density derivative w.r.t. pressure
* @param[out] dDensity_dTemperature fluid density derivative w.r.t. temperature
* @param[out] viscosity fluid viscosity
* @param[out] dViscosity_dPressure fluid viscosity derivative w.r.t. pressure
* @param[out] dViscosity_dTemperature fluid viscosity derivative w.r.t. temperature
* @param[out] internalEnergy fluid internal energy
* @param[out] dInternalEnergy_dPressure fluid internal energy derivative w.r.t.␣
˓→pressure

* @param[out] dInternalEnergy_dTemperature fluid internal energy derivative w.r.t.␣

˓→temperature

* @param[out] enthalpy fluid enthalpy

* @param[out] dEnthalpy_dPressure fluid enthalpy derivative w.r.t. pressure
* @param[out] dEnthalpy_dTemperature fluid enthalpy derivative w.r.t. temperature
*/
GEOS_HOST_DEVICE
virtual void compute( real64 const pressure,
real64 const temperature,
real64 & density,
real64 & dDensity_dPressure,
real64 & dDensity_dTemperature,
real64 & viscosity,
real64 & dViscosity_dPressure,
real64 & dViscosity_dTemperature,
real64 & internalEnergy,
real64 & dInternalEnergy_dPressure,
real64 & dInternalEnergy_dTemperature,
real64 & enthalpy,
real64 & dEnthalpy_dPressure,
real64 & dEnthalpy_dTemperature ) const = 0;

/**
* @brief Update fluid state at a single point.
* @param[in] k element index
* @param[in] q gauss point index
* @param[in] pressure the target pressure value
*/
(continues on next page)

1.6. Developer Guide 657

GEOS Documentation

(continued from previous page)

GEOS_HOST_DEVICE
virtual void update( localIndex const k,
localIndex const q,
real64 const pressure ) const = 0;

/**
* @brief Update fluid state at a single point.
* @param[in] k element index
* @param[in] q gauss point index
* @param[in] pressure the target pressure value
* @param[in] temperature the target temperature value
*/
GEOS_HOST_DEVICE
virtual void update( localIndex const k,
localIndex const q,
real64 const pressure,
real64 const temperature ) const = 0;

};

Compound models

Compound constitutive models are employed to mimic the behavior of a material that requires a combination of con-
stitutive models linked together. These compound models do not hold any data. They serve only as an interface with
the individual models that they couple.

Coupled Solids

CoupledSolid models are employed to represent porous materials that require both a mechanical behavior and con-
stitutive laws that describe the dependency of porosity and permeability on the primary unknowns.
The base class CoupledSolidBase implements some basic behaviors and is used to access a generic CoupledSolid
in a physics solver:
geos::constitutive::CoupledSolidBase const & solid =
getConstitutiveModel< geos::constitutive::CoupledSolidBase >( subRegion, subRegion.
˓→template getReference< string >( viewKeyStruct::solidNamesString() ) );

Additionally, a template class defines a base CoupledSolid model templated on the types of solid, porosity, and
permeability models:
template< typename SOLID_TYPE,
typename PORO_TYPE,
typename PERM_TYPE >
class CoupledSolid : public CoupledSolidBase

While physics solvers that need a porous material only interface with a compound model, this one has access to the
standalone models needed:
protected:
SOLID_TYPE const & getSolidModel() const
{ return this->getParent().template getGroup< SOLID_TYPE >( m_solidModelName ); }

(continues on next page)

658 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

PORO_TYPE const & getPorosityModel() const
{ return this->getParent().template getGroup< PORO_TYPE >( m_porosityModelName ); }

PERM_TYPE const & getPermModel() const

{ return this->getParent().template getGroup< PERM_TYPE >( m_permeabilityModelName ); }

There are two specializations of a CoupledSolid:

• CompressibleSolid: this model is used whenever there is no need to define a full mechanical model, but only
simple correlations that compute material properties (like porosity or permeability). This model assumes that
the solid model is of type NullModel and is only templated on the types of porosity and permeability models.
• PorousSolid: this model is used to represent a full porous material where the porosity and permeability models
need to be aware of the mechanical response of the material.

PVT Package Hierarchy

The architecture of the PVT package is as follows

Fig. 1.105: Architecture of the PVT package

The color scheme is:

• Green is for computational flash classes
• Purple is for data classes
• Orange is for fluid models (black oil, free water. . . )
• Light blue are for computational system (algorithms and data combined)
Only classes exposed in the public interface of the PVT package is meant to be used outside the PVT package.
• PHASE_TYPE, EOS_TYPE and COMPOSITIONAL_FLASH_TYPE enums are meant to be used to select the models
one wants to use.
• ScalarPropertyAndDerivatives and VectorPropertyAndDerivatives are utility classes used to return
the results. Those classes should eventually be replaced by LvArray.
• MultiphaseSystemProperties agglomerates the result of the computation.
• MultiphaseSystem is responsible for performing the computation and serving the results.
• MultiphaseSystemBuilder builds the system.

1.6. Developer Guide 659

GEOS Documentation

Fig. 1.106: Public interface of the PVT package

Adding a new Physics Solver

In this tutorial, you will learn how to construct a new GEOS Physics Solver class. We will use LaplaceFEM solver,
computing the solution of the Laplace problem in a specified material, as a starting point.
𝐷* ∆𝑋 = 𝑓 in Ω
𝑋=𝑋 𝑔
on Γ𝑔
It is advised to read XML Input preliminary to this tutorial. The goal of this document is to explain how to develop
a new solver that solves Laplace’s equation with a constant diffusion coefficient that is specified by users in the XML
input.
For readability, member functions in the text will be referenced by their names but their arguments will be omitted.

LaplaceFEM overview

The LaplaceFEM solver can be found in ./src/coreComponents/physicsSolvers/simplePDE/. Let us inspect

declarations in LaplaceFEM.hpp and implementations in LaplaceFEM.cpp before diving into specifying a new solver
class that meets our needs.

Declaration file (reference)

The included header is physicsSolvers/simplePDE/LaplaceBaseH1.hpp which declares the base class

LaplaceBaseH1, shared by all Laplace solvers. Moreover, physicsSolver/simplePDE/LaplaceBaseH1.hpp in-
cludes the following headers:
• common/EnumStrings.hpp which includes facilities for enum-string conversion (useful for reading enum val-
ues from input);
• physicsSolver/PhysicsSolverBase.hpp which declares the abstraction class shared by all physics solvers.
• managers/FieldSpecification/FieldSpecificationManager.hpp which declares a manager used to
access and to set field on the discretized domain.
Let us jump forward to the class enum and variable as they contain the data used specifically in the implementation of
LaplaceFEM.

660 Chapter 1. Table of Contents

GEOS Documentation

class enums and variables (reference)

The class exhibits two member variables:

• m_fieldName which stores the name of the diffused variable (e.g. the temperature) as a string;
• m_timeIntegrationOption an enum value allowing to dispatch with respect to the transient treatment.
TimeIntegrationOption is an enum specifying the transient treatment which can be chosen respectively between
SteadyState and ImplicitTransient depending on whether we are interested in the transient state.

enum class TimeIntegrationOption : integer

{
SteadyState,
ImplicitTransient
};

In order to register an enumeration type with the Data Repository and have its value read from input, we must define
stream insertion/extraction operators. This is a common task, so GEOS provides a facility for automating it. Upon
including common/EnumStrings.hpp, we can call the following macro at the namespace scope (in this case, right
after the LaplaceBaseH1 class definition is complete):

ENUM_STRINGS( LaplaceBaseH1::TimeIntegrationOption,
"SteadyState",
"ImplicitTransient" );

Once explained the main variables and enum, let us start reading through the different member functions:

class LaplaceFEM : public LaplaceBaseH1

{
public:
/// The default nullary constructor is disabled to avoid compiler auto-generation:
LaplaceFEM() = delete;

/// The constructor needs a user-defined "name" and a parent Group (to place this␣
˓→instance in the
/// tree structure of classes)
LaplaceFEM( const string & name,
Group * const parent );

/// Destructor
virtual ~LaplaceFEM() override;

/// "CatalogName()" return the string used as XML tag in the input file. It ties the␣
˓→XML tag with
/// this C++ classes. This is important.
static string catalogName() { return "LaplaceFEM"; }
/**
* @copydoc PhysicsSolverBase::getCatalogName()
*/
string getCatalogName() const override { return catalogName(); }

Start looking at the class LaplaceFEM constructor and destructor declarations shows the usual string name and Group*
pointer to parent that are required to build the global file-system like structure of GEOS (see Group : the base class of
GEOS for details). It can also be noted that the nullary constructor is deleted on purpose to avoid compiler automatic
generation and user misuse.

1.6. Developer Guide 661

GEOS Documentation

The next method catalogName() is static and returns the key to be added to the Catalog for this type of solver (see
A few words about the ObjectCatalog for details). It has to be paired with the following macro in the implementation
file.
REGISTER_CATALOG_ENTRY( PhysicsSolverBase, LaplaceFEM, string const &, Group * const )

Finally, the member function registerDataOnMesh() is declared in the LaplaceBaseH1 class as

/// This method ties properties with their supporting mesh
virtual void registerDataOnMesh( Group & meshBodies ) override final;

It is used to assign fields onto the discretized mesh object and will be further discussed in the Implementation File
(reference) section.
The next block consists in solver interface functions. These member functions set up and specialize every time step
from the system matrix assembly to the solver stage.
virtual void
setupSystem( DomainPartition & domain,
DofManager & dofManager,
CRSMatrix< real64, globalIndex > & localMatrix,
ParallelVector & rhs,
ParallelVector & solution,
bool const setSparsity = false ) override;

virtual void
assembleSystem( real64 const time,
real64 const dt,
DomainPartition & domain,
DofManager const & dofManager,
CRSMatrixView< real64, globalIndex const > const & localMatrix,
arrayView1d< real64 > const & localRhs ) override;

Furthermore, the following functions are inherited from the base class.
virtual real64 solverStep( real64 const & time_n,
real64 const & dt,
integer const cycleNumber,
DomainPartition & domain ) override;

virtual void
implicitStepSetup( real64 const & time_n,
real64 const & dt,
DomainPartition & domain ) override;

virtual void
setupDofs( DomainPartition const & domain,
DofManager & dofManager ) const override;

virtual void
applyBoundaryConditions( real64 const time,
real64 const dt,
DomainPartition & domain,
DofManager const & dofManager,
CRSMatrixView< real64, globalIndex const > const &␣
(continues on next page)

662 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

˓→localMatrix,
arrayView1d< real64 > const & localRhs ) override;

virtual void
applySystemSolution( DofManager const & dofManager,
arrayView1d< real64 const > const & localSolution,
real64 const scalingFactor,
real64 const dt,
DomainPartition & domain ) override;

virtual void updateState( DomainPartition & domain ) override final;

virtual void
resetStateToBeginningOfStep( DomainPartition & GEOS_UNUSED_PARAM( domain ) )␣
˓→override;

virtual void
implicitStepComplete( real64 const & time,
real64 const & dt,
DomainPartition & domain ) override;

/// This method is specific to this Laplace solver.

/// It is used to apply Dirichlet boundary condition
/// and called when the base class applyBoundaryConditions() is called.
virtual void applyDirichletBCImplicit( real64 const time,
DofManager const & dofManager,
DomainPartition & domain,
CRSMatrixView< real64, globalIndex const >␣
˓→const & localMatrix,

arrayView1d< real64 > const & localRhs );

Eventually, applyDirichletBCImplicit() is the working specialized member functions called when

applyBoundaryConditions() is called in this particular class override.
Browsing the base class PhysicsSolverBase, it can be noted that most of the solver in-
terface functions are called during either PhysicsSolverBase::linearImplicitStep() or
PhysicsSolverBase::nonlinearImplicitStep() depending on the solver strategy chosen.
Switching to protected members, postInputInitialization() is a central member function and will be called by
Group object after input is read from XML entry file. It will set and dispatch solver variables from the base class
PhysicsSolverBase to the most derived class. For LaplaceFEM, it will allow us to set the right time integration
scheme based on the XML value as will be further explored in the next Implementation File (reference) section.
Let us focus on a struct that plays an important role: the viewKeyStruct structure.

viewKeyStruct structure (reference)

This embedded instantiated structure is a common pattern shared by all solvers. It stores dataRepository::ViewKey
type objects that are used as binding data between the input XML file and the source code.
struct viewKeyStruct : public PhysicsSolverBase::viewKeyStruct
{
static constexpr char const * timeIntegrationOption() { return "timeIntegrationOption
˓→"; }

(continues on next page)

1.6. Developer Guide 663

GEOS Documentation

(continued from previous page)

static constexpr char const * fieldVarName() { return "fieldName"; }
};

We can check that in the LaplaceFEM companion integratedTest

In the following section, we will see where this binding takes place.

Implementation File (reference)

Switching to implementation, we will focus on few implementations, leaving details to other tutorials. The LaplaceFEM
constructor is implemented as follows.

LaplaceFEM::LaplaceFEM( const string & name,

Group * const parent ):
LaplaceBaseH1( name, parent )
{}

As we see, it calls the LaplaceBaseH1 constructor, that is implemented as follows.

LaplaceBaseH1::LaplaceBaseH1( const string & name,

Group * const parent ):
PhysicsSolverBase( name, parent ),
m_fieldName( "primaryField" ),
m_timeIntegrationOption( TimeIntegrationOption::ImplicitTransient )
{
this->registerWrapper( viewKeyStruct::timeIntegrationOption(), &m_
˓→timeIntegrationOption ).

setInputFlag( InputFlags::REQUIRED ).
setDescription( "Time integration method. Options are:\n* " + EnumStrings<␣
˓→TimeIntegrationOption >::concat( "\n* " ) );

this->registerWrapper( viewKeyStruct::fieldVarName(), &m_fieldName ).

setRTTypeName( rtTypes::CustomTypes::groupNameRef ).
setInputFlag( InputFlags::REQUIRED ).
setDescription( "Name of field variable" );

Checking out the constructor, we can see that the use of a registerWrapper<T>(...) allows us to register the key
value from the enum viewKeyStruct defining them as:
• InputFlags::OPTIONAL if they are optional and can be provided;
• InputFlags::REQUIRED if they are required and will throw error if not;

664 Chapter 1. Table of Contents

GEOS Documentation

and their associated descriptions for auto-generated docs.

void LaplaceBaseH1::registerDataOnMesh( Group & meshBodies )
{
meshBodies.forSubGroups< MeshBody >( [&] ( MeshBody & meshBody )
{
NodeManager & nodes = meshBody.getBaseDiscretization().getNodeManager();

nodes.registerWrapper< real64_array >( m_fieldName ).

setApplyDefaultValue( 0.0 ).
setPlotLevel( PlotLevel::LEVEL_0 ).
setDescription( "Primary field variable" );
} );
}

registerDataOnMesh() is browsing all subgroups in the mesh Group object and for all nodes in the sub group:
• register the observed field under the chosen m_fieldName key;
• apply a default value;
• set the output verbosity level (here PlotLevel::LEVEL_0);
• set the field associated description for auto generated docs.

void LaplaceFEM::assembleSystem( real64 const GEOS_UNUSED_PARAM( time_n ),

real64 const dt,
DomainPartition & domain,
DofManager const & dofManager,
CRSMatrixView< real64, globalIndex const > const &␣
˓→localMatrix,

arrayView1d< real64 > const & localRhs )

{
forDiscretizationOnMeshTargets( domain.getMeshBodies(), [&] ( string const &,
MeshLevel & mesh,
arrayView1d< string␣
˓→const > const & regionNames )

{
NodeManager & nodeManager = mesh.getNodeManager();
string const dofKey = dofManager.getKey( m_fieldName );
arrayView1d< globalIndex const > const &
dofIndex = nodeManager.getReference< array1d< globalIndex > >( dofKey );

LaplaceFEMKernelFactory kernelFactory( dofIndex, dofManager.rankOffset(),␣

˓→ localMatrix, localRhs, dt, m_fieldName );

string const dummyString = "dummy";

finiteElement::
regionBasedKernelApplication< parallelDevicePolicy< >,
constitutive::NullModel,
CellElementSubRegion >( mesh,
regionNames,
this->
˓→getDiscretizationName(),

dummyString,
kernelFactory );
(continues on next page)

1.6. Developer Guide 665

GEOS Documentation

(continued from previous page)

} );

assembleSystem() will be our core focus as we want to change the diffusion coefficient from its hard coded value
to a XML read user-defined value. One can see that this method is in charge of constructing in a parallel fashion
the FEM system matrix. Bringing nodeManager and ElementRegionManager from domain local MeshLevel ob-
ject together with FiniteElementDiscretizationManager from the NumericalMethodManager, it uses nodes
embedded loops on degrees of freedom in a local index embedded loops to fill a matrix and a rhs container.
As we spotted the place to change in a code to get a user-defined diffusion coefficient into the game, let us jump to
writing our new LaplaceDiffFEM solver.

ò Note

We might want to remove final keyword from postInputInitialization() as it will prevent you from overrid-
ing it.

Start doing your own Physic solver

As we will extend LaplaceFEM capabilities, we will derive publicly from it.

Declaration File

As there is only few places where we have to change, the whole declaration file is reported below and commented
afterwards.
#include "physicsSolvers/simplePDE/LaplaceFEM.hpp"

namespace geos
{

class LaplaceDiffFEM : public LaplaceFEM

{
public:

LaplaceDiffFEM() = delete;

LaplaceDiffFEM( const string& name,

Group * const parent );

virtual ~LaplaceDiffFEM() override;

static string catalogName() { return "LaplaceDiffFEM"; }

virtual void
assembleSystem( real64 const time,
real64 const dt,
DomainPartition * const domain,
DofManager const & dofManager,
ParallelMatrix & matrix,
(continues on next page)

666 Chapter 1. Table of Contents

GEOS Documentation

(continued from previous page)

ParallelVector & rhs ) override;

struct viewKeyStruct : public LaplaceFEM::viewKeyStruct

{
dataRepository::ViewKey diffusionCoeff = { "diffusionCoeff" };
} laplaceDiffFEMViewKeys;

protected:
virtual void postInputInitialization() override final;

private:
real64 m_diffusion;

};

We intend to have a user-defined diffusion coefficient, we then need a real64 class variable m_diffusion to store it.
Consistently with LaplaceFEM, we will also delete the nullary constructor and declare a constructor with the same
arguments for forwarding to Group master class. Another mandatory step is to override the static CatalogName()
method to properly register any data from the new solver class.
Then as mentioned in Implementation File (reference), the diffusion coefficient is used when assembling the matrix
coefficient. Hence we will have to override the assembleSystem() function as detailed below.
Moreover, if we want to introduce a new binding between the input XML and the code we will have to work on the
three struct viewKeyStruct , postInputInitialization() and the constructor.
Our new solver viewKeyStruct will have its own structure inheriting from the LaplaceFEM one to have the
timeIntegrationOption and fieldName field. It will also create a diffusionCoeff field to be bound to the
user defined homogeneous coefficient on one hand and to our m_diffusion class variable on the other.

Implementation File

As we have seen in Implementation File (reference), the first place where to implement a new register from XML input
is in the constructor. The diffusionCoeff entry we have defined in the laplaceDiffFEMViewKeys will then be
asked as a required input. If not provided, the error thrown will ask for it described asked an “input uniform diffusion
coefficient for the Laplace equation”.

LaplaceDiffFEM::LaplaceDiffFEM( const string& name,

Group * const parent ):
LaplaceFEM( name, parent ), m_diffusion(0.0)
{
registerWrapper<string>(laplaceDiffFEMViewKeys.diffusionCoeff.Key()).
setInputFlag(InputFlags::REQUIRED).
setDescription("input uniform diffusion coeff for the laplace equation");
}

Another important spot for binding the value of the XML read parameter to our m_diffusion is in
postInputInitialization().

void LaplaceDiffFEM::postInputInitialization()
{
LaplaceFEM::postInputInitialization();
(continues on next page)

1.6. Developer Guide 667

GEOS Documentation

(continued from previous page)

string sDiffCoeff = this->getReference<string>(laplaceDiffFEMViewKeys.diffusionCoeff);

this->m_diffusion = std::stof(sDiffCoeff);
}

Now that we have required, read and bind the user-defined diffusion value to a variable, we can use it in the construction
of our matrix into the overridden assembleSystem().

// begin element loop, skipping ghost elements

for( localIndex k=0 ; k<elementSubRegion->size() ; ++k )
{
if(elemGhostRank[k] < 0)
{
element_rhs = 0.0;
element_matrix = 0.0;
for( localIndex q=0 ; q<n_q_points ; ++q)
{
for( localIndex a=0 ; a<numNodesPerElement ; ++a)
{
elemDofIndex[a] = dofIndex[ elemNodes( k, a ) ];

for( localIndex b=0 ; b<numNodesPerElement ; ++b)

{
element_matrix(a,b) += detJ[k][q] *
m_diffusion *
+ Dot( dNdX[k][q][a], dNdX[k][q][b] );
}

}
}
matrix.add( elemDofIndex, elemDofIndex, element_matrix );
rhs.add( elemDofIndex, element_rhs );
}
}

This completes the implementation of our new solver LaplaceDiffFEM.

Nonetheless, the compiler should complain that m_fieldName is privately as inherited from LaplaceFEM. One should
then either promote m_fieldName to protected or add a getter in LaplaceFEM class to correct the error. The getter
option has been chosen and the fix in our solver is then:

array1d<globalIndex> const & dofIndex =

nodeManager->getReference< array1d<globalIndex> >( dofManager.getKey( getFieldName() )␣
˓→);

Note: For consistency do not forget to change LaplaceFEM to LaplaceDiffFEM in the guards comments

Last steps

After assembling both declarations and implementations for our new solver, the final steps go as:
• add declarations to parent CMakeLists.txt (here add to physicsSolvers_headers );
• add implementations to parent CMakeLists.txt (here add to physicsSolvers_sources);

668 Chapter 1. Table of Contents

GEOS Documentation

• check that Doxygen comments are properly set in our solver class;
• uncrustify it to match the code style by going to the build folder and running the command: make uncrustify_style;
• write unit tests for each new features in the solver class;
• write an integratedTests for the solver class.

1.7 Doxygen
The GEOS c++ API in is documented using doxygen. The doxygen class list pages
Developers may find it helpful to review the Code Components described in the Developer Guide before diving into
the doxygen.
Some key doxygen pages are linked below:
Group API
Wrapper API
ObjectManagerBase API
PhysicsSolverBase API

1.8 Build Guide

Welcome to the GEOS build guide.

1.8.1 System prerequisites

To configure and build GEOS you will need the following tools available on your system.

List of prerequisites
Minimal requirements:
• CMake build system generator (3.23.1+).
• build tools (GNU make or ninja on Linux, XCode on MacOS).
• a C++ compiler with full c++17 standard support (gcc 12+ or clang 13.0+ are recommended).
• python 3.9-3.11 (versions 3.12+ are untested).
• zlib, blas and lapack libraries
• any compatible MPI runtime and compilers (if building with MPI)
If you want to build from a repository check out (instead of a release tarball):
• git (2.20+ is tested, but most versions should work fine)
If you plan on building bundled third-party library (TPLs) dependencies yourself:
• Compatible C and Fortran compilers
If you will be checking out and running integrated tests (a submodule of GEOS, currently not publicly available):
• git-lfs (Git Large File Storage extension)
• h5py and mpi4py python modules
If you are interested in building Doxygen documentation:

1.7. Doxygen 669

GEOS Documentation

• GNU bison
• LaTeX
• ghostscript
• Graphviz
In order for XML validation to work (executed as an optional build step):
• xmllint

Installing prerequisites
On a local development machine with sudo/root privileges, most of these dependencies can be installed with a system
package manager. For example, on a Debian-based system (check your package manager for specific package names):

sudo apt install build-essential git git-lfs gcc g++ gfortran cmake libopenmpi-dev␣
˓→libblas-dev liblapack-dev zlib1g-dev python3 python3-h5py python3-mpi4py libxml2-utils

On HPC systems it is typical for these tools to be installed by system administrators and provided via modules. To list
available modules, type:

module avail

Then load the appropriate modules using module load command. Please contact your system administrator if you
need help choosing or installing appropriate modules.

1.8.2 Third-party dependencies

GEOS makes use of multiple third-party libraries (TPLs) and tools, some of which are mandatory and some optional.
We only test against specific versions, and sometimes even require development snapshots (specific git commits). Not
all of these guarantee backwards compatibility, so we strongly recommend building with these specific versions.

List of third-party libraries and tools

The two tables below lists the dependencies with their specific versions and relevant CMake variables. Some of these
libraries may have their own system prerequisites.

Libraries

The following libraries are linked to by GEOS:

670 Chapter 1. Table of Contents

GEOS Documentation

Name Ver- Enable op- Path vari- Description

sion tion able
Adiak 0.2.0 ADIAK_DIR Library for collecting metadata from HPC application runs, and
ENABLE_CALIPER
distributing that metadata to subscriber tools.
Caliper 2.4.0 CALIPER_DIRInstrumentation and performance profiling library.
ENABLE_CALIPER
con- 0.5.0 mandatory CONDUIT_DIRSimplified Data Exchange for HPC Simulations.
duit
CHAI 2.2.2 mandatory CHAI_DIRCopy-hiding array abstraction to automatically migrate data be-
tween memory spaces.
RAJA 0.12.1 mandatory RAJA_DIR Collection of C++ software abstractions that enable architecture
portability for HPC applications.
hdf5 1.10.5 mandatory HDF5_DIR High-performance data management and storage suite.
math- 2015- ENABLE_MATHPRESSO Mathematical Expression Parser and JIT Compiler.
MATHPRESSO_DIR
presso 12-15
pugixml 1.8.0 mandatory PUGIXML_DIRLight-weight, simple and fast XML parser for C++ with XPath
support.
parmetis 4.0.3 mandatory Parallel Graph Partitioning library. Should be built with 64-bit
PARMETIS_DIR
(with MPI) idx_t type.
suites- 5.8.1 ENABLE_SUITESPARSE A suite of sparse matrix software.
SUITESPARSE_DIR
parse
su- 0f6efc3 ENABLE_SUPERLU_DIST General purpose library for the direct solution of large, sparse,
SUPERLU_DIST_DIR
perlu_dist nonsymmetric systems of linear equations.
hypre 2186a8f ENABLE_HYPRE HYPRE_DIR Library of high performance preconditioners and solvers for large
sparse linear systems on massively parallel computers.
PETSc 3.13.0 ENABLE_PETSC PETSC_DIR Suite of data structures and routines for the scalable (parallel) so-
lution of scientific applications.
Trili- 12.18.1 ENABLE_TRILINOS Collection of reusable scientific software libraries, known in par-
TRILINOS_DIR
nos ticular for linear solvers.
silo 4.10.3 mandatory SILO_DIR A Mesh and Field I/O Library and Scientific Database.
VTK 9.0.0- ENABLE_VTK VTK_DIR Open source software for manipulating and displaying scientific
rc3 data.

Tools

The following tools are used as part of the build process to support GEOS development:

Name Ver- Enable option Path variable Description

sion
doxy- 1.8.20 De facto standard tool for generating documentation
ENABLE_DOXYGENDOXYGEN_EXECUTABLE
gen from annotated C++ sources.
sphinx 1.8.5 ENABLE_SPHINX SPHINX_EXECUTABLEA tool that makes it easy to create intelligent and beau-
tiful documentation.
un- 401a409 ENABLE_UNCRUSTIFY A source code beautifier for C, C++, C#, ObjectiveC, D,
UNCRUSTIFY_EXECUTABLE
crus- Java, Pawn and VALA.
tify

Some other dependencies (GoogleTest, GoogleBenchmark) are provided through BLT build system which is embedded
in GEOS source. No actions are needed to build them.
If you would like to create a Docker image with all dependencies, take a look at Dockerfiles that are used in our CI
process.

1.8. Build Guide 671

GEOS Documentation

Building bundled dependencies

To simplify the process of building TPLs, we provide a git repository thirdPartyLibs. It contains source copies of exact
TPL versions required and is updated periodically. It also contains a CMake script for building all TPLs in a single
command.
The recommended steps to build TPLs are:
• Create a host-config file that sets all system-specific CMake variables (compiler and library paths, configuration
flags, etc.) Take a look at host-config examples.
• Configure via config-build.py script:

cd thirdPartyLibs
python scripts/config-build.py --hostconfig=/path/to/host-config.cmake --
˓→buildtype=Release --installpath=/path/to/install/dir -DNUM_PROC=8

where
– --buildpath or -bp is the build directory (by default, created under current).
– --installpath or -ip is the installation directory(wraps CMAKE_INSTALL_PREFIX).
– --buildtype or -bt is a wrapper to the CMAKE_BUILD_TYPE option.
– --hostconfig or -hc is a path to host-config file.
– all other command-line options are passed to CMake.
• Run the build:

cd <buildpath>
make

. Warning

Do not provide -j argument to make here, since the top-level make only launches sub-project builds. Instead
use -DNUM_PROC option above, which is passed to each sub-project’s make command.

You may also run the CMake configure step manually instead of relying on config-build.py. The full TPL build
may take anywhere between 15 minutes and 2 hours, depending on your machine, number of threads and libraries
enabled.

ò Note

An exception from the above pattern, sphinx is currently not a part of the TPL bundle and must be installed with
your Python or package manager.

ò Note

PETSc build currently downloads pt-scotch from the internet. If you do not have access to internet, modify the
./configure step of petsc in CMakeLists.txt and change the --download-ptscotch option accordingly. pt-scotch
also relies on bison and flex.

672 Chapter 1. Table of Contents

GEOS Documentation

Installing dependencies individually

You may also install each individual TPL separately, either manually or through a package manager. This is a more
difficult route, since you are responsible for configuring dependencies in a compatible manner. Again, we strongly
recommend using the exact versions listed above, to avoid possible build problems.
You may look at our TPL CMake script to see how we configure TPL builds.

1.8.3 Building GEOS

Build steps
• Create a host-config file that sets all system-specific CMake variables. Take a look at host-config examples. We
recommend the same host-config is used for both TPL and GEOS builds. In particular, certain options (such as
ENABLE_MPI or ENABLE_CUDA) need to match between the two.
• Provide paths to all enabled TPLs. This can be done in one of two ways:
– Provide each path via a separate CMake variable (see Third-party dependencies for path variable names).
– If you built TPLs from the tplMirror repository, you can set GEOSX_TPL_DIR variable in your host-config
to point to the TPL installation path, and

include("/path/to/GEOS/host-configs/tpls.cmake")

which will set all the individual TPL paths for you.
• Configure via config-build.py script:

cd GEOS
python scripts/config-build.py --hostconfig=/path/to/host-config.cmake --
˓→buildtype=Release --installpath=/path/to/install/dir

where
– --buildpath or -bp is the build directory (by default, created under current working dir).
– --installpath or -ip is the installation directory(wraps CMAKE_INSTALL_PREFIX).
– --buildtype or -bt is a wrapper to the CMAKE_BUILD_TYPE option.
– --hostconfig or -hc is a path to host-config file.
– all unrecognized options are passed to CMake.
If --buildpath is not used, build directory is automatically named
build-<config-filename-without-extension>-<buildtype>. It is possible to keep automatic
naming and change the build root directory with --buildrootdir. In that case, build path will be set to
<buildrootdir>/<config-filename-without-extension>-<buildtype>. Both --buildpath and
--buildrootdir are incompatible and cannot be used in the same time. Same pattern is applicable to install
path, with --installpath and --installrootdir options.
• Run the build:

cd <buildpath>
make -j $(nproc)

You may also run the CMake configure step manually instead of relying on config-build.py. A full build typically
takes between 10 and 30 minutes, depending on chosen compilers, options and number of cores.

1.8. Build Guide 673

GEOS Documentation

Configuration options
Below is a list of CMake configuration options, in addition to TPL options above. Some options, when enabled, require
additional settings (e.g. ENABLE_CUDA). Please see host-config examples.

Option De- Explanation

fault
ENABLE_MPI ON Build with MPI (also applies to TPLs)
ENABLE_OPENMP OFF Build with OpenMP (also applies to TPLs)
ENABLE_CUDA OFF Build with CUDA (also applies to TPLs)
ENABLE_CUDA_NVTOOLSEXT
OFF Enable CUDA NVTX user instrumentation (via GEOS_MARK_SCOPE or
GEOS_MARK_FUNCTION macros)
ENABLE_HIP OFF Build with HIP/ROCM (also applies to TPLs)
ENABLE_DOCS ON Build documentation (Sphinx and Doxygen)
ENABLE_WARNINGS_AS_ERRORS
ON Treat all warnings as errors
ENABLE_PVTPackage ON Enable PVTPackage library (required for compositional flow runs)
ENABLE_TOTALVIEW_OUTPUT
OFF Enables TotalView debugger custom view of GEOS data structures
ENABLE_COV OFF Enables code coverage
GEOS_ENABLE_TESTS ON Enables unit testing targets
GEOS_LA_INTERFACE Hypre Choie of Linear Algebra backend (Hypre/Petsc/Trilinos)
GEOS_BUILD_OBJ_LIBS ON Use CMake Object Libraries build
GEOS_BUILD_SHARED_LIBS
OFF Build geosx_core as a shared library instead of static
GEOS_PARALLEL_COMPILE_JOBS Max. number of compile jobs (when using Ninja), in addition to -j flag
GEOS_PARALLEL_LINK_JOBS Max. number of link jobs (when using Ninja), in addition to -j flag
GEOS_INSTALL_SCHEMA ON Enables schema generation and installation

1.8.4 Spack and Uberenv

GEOS is transitioning to a new Spack and Uberenv system for building our dependencies. We refer the reader to the
Spack documentation and Uberenv documentation, in particular the Spack documentation for specs and dependencies,
manual compiler configuration and external packages are worth reading.
Building the dependencies can be as simple as running

./scripts/uberenv/uberenv.py

This will create a directory uberenv_libs (or a directory name you specify by adding --prefix directory-name)
in the current working directory, clone Spack into uberenv_libs/spack and install the dependencies into
uberenv_libs/system_dependent_path. It will then spit out a host-config file in the current directory which you
can use to build GEOS. While the above command should work on every system, it should never be used. Invoked as
such, Spack will ignore any system libraries you have installed and will go down a rabbit hole building dependencies.
Furthermore this does not allow you to choose the compiler to build. Both of these are easily solved by creating a
directory with a spack.yaml.
To prevent this from happening you’ll need to create a directory with a spack.yaml file. You can find working examples
for commonly used systems in scripts/spack_configs.
Once you have these files setup you can run Uberenv again and instruct it to use them with. If for instance you added
Clang 10.0.1 to the spack.yaml file the your command would look something like this:

./scripts/uberenv/uberenv.py --spack-config-dir=/path/to/your/config/directory/ --spec="

˓→%[email protected]"

It is worth noting that GEOS has two project json files (.uberenv_config.json and scripts/pygeosx_configs/
pygeosx.json) and two configuration directories for LC systems (scripts/spack_configs and scripts/

674 Chapter 1. Table of Contents

GEOS Documentation

pygeosx_configs). The .uberenv_config.json project json file and scripts/spack_configs direc-

tory is for building GEOS. The scripts/pygeosx_configs/pygeosx.json project json file and scripts/
pygeosx_configs directory is for building pygeosx. This is because pygeosx has a separate list of required compil-
ers and packages to build from GEOS (e.g. pygeosx’s numpy dependency recommends building with gcc and using
openblas for BLAS/LAPACK). However, when not building pygeosx other dependencies depend on python, but an
existing system version works just fine, so it can be put in GEOS’s spack.yaml to prevent Spack from building it. By
default, Uberenv will find and use .uberenv_config.json to build GEOS, but you can use the --project-json
command line option to target scripts/pygeosx_configs/pygeosx.json to build pygeosx:

./scripts/uberenv/uberenv.py --spack-config-dir=/path/to/your/config/directory/ --spec="

˓→%[email protected]" --project-json="scripts/pygeosx_configs/pygeosx.json"

ò Note

When building pygeosx, Spack will build various python packages, however by default they are not installed in
python. There are various ways of accomplishing this, but the recommended approach is to use spack environments.
Once you build pygeosx using Uberenv, Spack will create a view that ensures the Spack-built python can find the
built python packages. For example, with a default uberenv_libs directory of dependencies, the path to the view
of python will be uberenv_libs/._view/*/bin/python3. If you want to use your pygeosx python3 executable
in GEOS, you will need to update your host-config’s Python3_ROOT_DIR and Python3_EXECUTABLE to the path
to Spack’s view of python.

Build Configuration

. Warning

The spack build system is undergoing updates. The petsc variant and others are still a work in progress.

The GEOS Spack package has a lot of options for controlling which dependencies you would like to build and how you’d
like them built. The GEOS Spack package file is at `scripts/spack_packages/packages/geosx/package.py
<https://github.com/GEOS-DEV/GEOS/tree/develop/scripts/spack_packages/packages/geosx/
package.py>`_. The variants for the package are as follows

variant('shared', default=True, description='Build Shared Libs.')

variant('caliper', default=True, description='Build Caliper support.')
variant('vtk', default=True, description='Build VTK support.')
variant('fesapi', default=False, description='Build fesapi support.')
variant('trilinos', default=True, description='Build Trilinos support.')
variant('hypre', default=True, description='Build HYPRE support.')
variant('petsc', default=False, description='Build PETSc support.')
variant('scotch', default=True, description='Build Scotch support.')
variant('uncrustify', default=True, description='Build Uncrustify support.')
variant('lai',
default='hypre',
description='Linear algebra interface.',
values=('trilinos', 'hypre', 'petsc'),
multi=False)
variant('pygeosx', default=True, description='Enable pygeosx.')

1.8. Build Guide 675

GEOS Documentation

For example if you wanted to build with GCC 8.3.1, without Caliper and with Hypre as the Linear Algebra Interface,
your spec would be %[email protected] ~caliper lai=hypre.
The GEOS Spack package lists out the libraries that GEOS depends ons. Currently these dependencies are

depends_on('[email protected]:', type='build')

depends_on('blt')

#
# Virtual packages
#
depends_on('mpi')
depends_on('blas')
depends_on('lapack')

#
# Performance portability
#
depends_on('raja +openmp~examples~exercises~shared')

depends_on('umpire +c+openmp~examples+fortran~device_alloc~shared')

depends_on('[email protected] +raja+openmp~examples~shared')

depends_on('camp')

with when('+cuda'):
for sm_ in CudaPackage.cuda_arch_values:
depends_on('raja+cuda cuda_arch={0}'.format(sm_), when='cuda_arch={0}'.
˓→format(sm_))

depends_on('umpire+cuda cuda_arch={0}'.format(sm_), when='cuda_arch={0}'.

Using the Spack spec syntax you can inturn specify variants for each of the dependencies of GEOS. So for example
if you could modify the spec above to build RAJA in debug by using %[email protected] ~caliper lai=hypre ^raja
build_type=Debug. When building with Uberenv Spack should print out a table containing the full spec for every

1.8. Build Guide 677

GEOS Documentation

dependency it will build. If you would like to look at the variants for say RAJA in more detail you can find the package
file at uberenv_libs/spack/var/spack/repos/builtin/packages/raja/package.py.

Adding a Dependency (Advanced)

Adding a dependency to GEOS is straight forward if the dependency already builds with Spack. If that is the case
then all you need to do is add a depends_on('cool-new-library') to the GEOS package.py file. If however the
dependency doesn’t have a Spack package, you will have to add one by creating a cool-new-library/package.yaml
file in the scripts/spack_packages/packages directory and adding the logic to build it there.
Oftentimes (unfortunately), even when a package already exists, it might not work out of the box for your system. In this
case copy over the existing package.py file from the Spack repository into scripts/spack_packages/packages/
cool-new-library/package.py, as if you were adding a new package, and perform your modifications there. Once
you have the package working, copy the package back into the Spack repository (running Uberenv should do this for
you) and commit+push your changes to Spack.

1.8.5 Continuous Integration process

To save building time, the third party libraries (that do not change so often) and GEOS are build separately.
Everytime a pull is requested in the TPL repository, docker images are generated and deployed on
dockerhub. The repository names (ubuntu18.04-gcc8, centos7.7.1908-clang9.0.0, centos7.6.1810-gcc8.3.1-
cuda10.1.243 etc.) obviously reflect the OS and the compiler flavour used. For each image, the unique
tag ${PULL_REQUEST_NUMBER}-${BUILD_NUMBER} (defined as ${{ github.event.number }}-${{ github.
run_number }} in github actions) is used so we can connect the related code source in a rather convenient way. Each
docker contains the org.opencontainers.image.created and org.opencontainers.image.revision labels
to provide additional information.
It is necessary to set build.args.GEOS_TPL_TAG (e.g. something like 235-52) in the .devcontainer/devcontainer.json
file, to build against one selected version of the TPL.
It must be mentioned that one and only one version of the compiled TPL tarball is stored per pull request (older ones
are removed automatically). Therefore, a client building against a work in progress PR may experience a 404 error
sooner or later.

Building docker images

Our continuous integration process builds the TPL and GEOS against two operating systems (ubuntu and centos) and
two compilers (clang and gcc). The docker files use multi-stage builds in order to minimise the sizes of the images.
• First stage installs and defines all the elements that are commons to both TPL and GEOS (for example, MPI and
c++ compiler, BLAS, LAPACK, path to the installation directory. . . ).
• As a second stage, we install everything needed to build (not run) the TPLs. We keep nothing from this second
step for GEOS, except the compiled TPL themselves. For example, a fortran compiler is needed by the TPL but
not by GEOS: it shall be installed during this step, so GEOS won’t access a fortran compiler (it does not have
to).
• Last stage copies the compiled TPL from second stage and installs the elements only required by GEOS (there
are few).

Docker images contract

GEOS will find a compiled version of the third party libraries.
As part of the contract provided by the TPL, the docker images also defines several environment variables. The

GEOS_TPL_DIR

678 Chapter 1. Table of Contents

GEOS Documentation

variable contains the absolute path of the installation root directory of the third party libraries. GEOS must use it when
building.
Other variables are classical absolute path compiler variables.

CC
CXX
MPICC
MPICXX

And the absolute path the mpirun (or equivalent) command.

MPIEXEC

The following openmpi environment variables allow it to work properly in the docker container. But there should be
no reason to access or use them explicitly.

OMPI_CC=$CC
OMPI_CXX=$CXX

1.8.6 Building Apple MacOS

Install homebrew
Taken from the [homebrew website](https://brew.sh) .. code-block:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/

˓→install.sh)"

(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile

note: this is the command for `zsh`. Other shells will require different commands.␣
˓→Homebrew should provide the correct command after install is complete.

eval "$(/opt/homebrew/bin/brew shellenv)"

Install packages using homebrew

brew install bison cmake gfortran git-lfs open-mpi lapack python3 ninja m4
echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/opt/m4/bin:$PATH"' >> ~/.zshrc
git lfs install

Clone GEOS

git clone [email protected]:GEOS-DEV/GEOS.git

cd GEOS
git submodule init
git submodule update
cd ..

Clone thirdPartyLibs

git clone [email protected]:GEOS-DEV/thirdPartyLibs.git

cd thirdPartyLibs
(continues on next page)

1.8. Build Guide 679

GEOS Documentation

(continued from previous page)

git submodule init
git submodule update
git lfs pull

Configure and build thirdPartyLibs

python3 scripts/config-build.py -hc ../GEOS/host-configs/apple/macOS_arm.cmake -bt␣

˓→Release

You will get a warning you can ignore

CMake Warning at /Users/settgast1/Codes/geos/GEOS/host-configs/tpls.cmake:10 (message):

'GEOS_TPL_DIR' does not exist.

Continue with the build

cd build-macOS_arm-release
make

You will get an error at the end. . . you can ignore it.

[100%] Linking CXX executable ../../../tests/blt_mpi_smoke

ld: warning: -commons use_dylibs is no longer supported, using error treatment instead
ld: file not found: @rpath/libquadmath.0.dylib for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make[2]: *** [tests/blt_mpi_smoke] Error 1
make[1]: *** [blt/tests/smoke/CMakeFiles/blt_mpi_smoke.dir/all] Error 2
make: *** [all] Error 2

Build GEOS

cd ../../GEOS
python3 scripts/config-build.py -hc host-configs/apple/macOS_arm.cmake -bt Release --
˓→ninja

cd build-macOS_arm-release
ninja geosx

1.9 Datastructure Index

1.9.1 Input Schema Definitions
XML Schema

680 Chapter 1. Table of Contents

GEOS Documentation

XML Element: AcousticElasticSEM

Name Type Default Description

acousticSolverName groupNameRef required Name of the acoustic
solver used by the coupled
solver
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
elasticSolverName groupNameRef required Name of the elastic solver
used by the coupled solver
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
1.9. Datastructure Index - Nonlinear solver681
information
- Solver timers
information
GEOS Documentation

XML Element: AcousticFirstOrderSEM

Name Type Default Description

attenuationType geos_WaveSolverUtils_AttenuationType
none Flag to indicate which at-
tenuation model to use:
“none” for no attenuation,
“slsfor the standard-linear-
solid (SLS) model (Ficht-
ner, 2014).
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
dtSeismoTrace real64 0 Time step for output pres-
sure at receivers
enableLifo integer 0 Set to 1 to enable LIFO
storage feature
forward integer 1 Set to 1 to compute for-
ward propagation
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
lifoOnDevice integer -80 Set the capacity of the lifo
device storage (if negative,
opposite of percentage of
remaining memory)
lifoOnHost integer -80 Set the capacity of the lifo
host storage (if negative,
opposite of percentage of
remaining memory)
lifoSize integer 2147483647 Set the capacity of the lifo
storage (should be the total
number of buffers to store
in the LIFO)
linearDASGeometry real64_array2d {{0}} Geometry parameters for a
linear DAS fiber (dip, az-
imuth, gauge length)
continues on next page

682 Chapter 1. Table of Contents

GEOS Documentation

Table 1.3 – continued from previous page

Name Type Default Description
linearDASSamples integer 5 Number of sample points
to be used for strain in-
tegration when integrating
the strain for the DAS sig-
nal
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

Table 1.4 – continued from previous page

name groupName required A name is required for any

non-unique nodes
outputSeismoTrace integer 0 Flag that indicates if we
write the seismo trace in a
file .txt, 0 no output, 1 oth-
erwise
receiverCoordinates real64_array2d {{0}} Coordinates (x,y,z) of the
receivers
rickerOrder integer 2 Flag that indicates the or-
der of the Ricker to be used
o, 1 or 2. Order 2 by de-
fault
saveFields integer 0 Set to 1 to save fields dur-
ing forward and restore
them during backward
shotIndex integer 0 Set the current shot for
temporary files
continues on next page

1.9. Datastructure Index 687

GEOS Documentation

Table 1.4 – continued from previous page

Name Type Default Description
slsAnelasticityCoeffi- real32_array {0} Anelasticity coefficients
cients for the standard-linear-
solid (SLS) anelastic-
ity.The default value is
{ }, corresponding to no
attenuation. An array
with the corresponding
reference frequencies
must be provided.
slsReferenceAngularFre- real32_array {0} Reference angular fre-
quencies quencies (omega) for
the standard-linear-solid
(SLS) anelasticity.The
default value is { },
corresponding to no
attenuation. An array
with the corresponding
anelasticity coefficients
must be provided.
sourceCoordinates real64_array2d {{0}} Coordinates (x,y,z) of the
sources
sourceWaveletTable- string_array {} Names of the table func-
Names tions, one for each source,
that are used to define
the source wavelets. If
a list is given, it over-
rides the Ricker wavelet
definitions.The default
value is an empty list,
which means that a
Ricker wavelet is used
everywhere.
targetRegions groupNameRef_array required Allowable regions that the
solver may be applied to.
Note that this does not in-
dicate that the solver will
be applied to these re-
gions, only that allocation
will occur such that the
solver may be applied to
these regions. The de-
cision about what regions
this solver will beapplied
to rests in the EventMan-
ager.
timeSourceDelay real32 -1 Source time delay (1 / f0
by default)
timeSourceFrequency real32 0 Central frequency for the
time source
continues on next page

688 Chapter 1. Table of Contents

GEOS Documentation

Table 1.4 – continued from previous page

Name Type Default Description
timestepStabilityLimit integer 0 Set to 1 to apply a stabil-
ity limit to the simulation
timestep. The timestep
used is that given by the
CFL condition times the
cflFactor parameter.
useDAS geos_WaveSolverUtils_DASType
none Flag to indicate if DAS
data will be modeled,
and which DAS type to
use: “none” to deactivate
DAS, “strainIntegration”
for strain integration,
“dipole” for displacement
difference
writeLinearSystem integer 0 Write matrix, rhs, solution
to screen ( = 1) or file ( =
2).
LinearSolverParameters node unique XML Element: Linear-
SolverParameters
NonlinearSolverParame- node unique XML Element: Nonlinear-
ters SolverParameters

XML Element: AcousticVTISEM

Name Type Default Description

1.9. Datastructure Index 689

GEOS Documentation

Table 1.5 – continued from previous page

690 Chapter 1. Table of Contents

GEOS Documentation

Table 1.5 – continued from previous page

name groupName required A name is required for any

1.9. Datastructure Index 691

GEOS Documentation

Table 1.5 – continued from previous page

692 Chapter 1. Table of Contents

GEOS Documentation

Table 1.5 – continued from previous page

1.9. Datastructure Index 693

GEOS Documentation

XML Element: Aquifer

Name Type Default Description

aquiferAngle real64 required Angle subtended by the

XML Element: Blueprint

Name Type Default Description

childDirectory string Child directory path
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Output timing
information

name groupName required A name is required for any

non-unique nodes
outputFullQuadrature- integer 0 If true writes out data asso-
Data ciated with every quadra-
ture point.
parallelThreads integer 1 Number of plot files.
plotLevel geos_dataRepository_PlotLevel
1 Determines which fields to
write.

XML Element: Box

Name Type Default Description

name groupName required A name is required for any non-unique nodes
strike real64 -90 The strike angle of the box
xMax R1Tensor required Maximum (x,y,z) coordinates of the box
xMin R1Tensor required Minimum (x,y,z) coordinates of the box

1.9. Datastructure Index 697

GEOS Documentation

XML Element: BrooksCoreyBakerRelativePermeability

Name Type Default Description

gasOilRelPermExponent real64_array {1}
Rel perm power law
exponent for the pair (gas
phase, oil phase) at
residual water saturation
The expected format is “{
gasExp, oilExp }”, in that
order

gasOilRelPermMaxValue real64_array {0}

Maximum rel perm value
for the pair (gas phase, oil
phase) at residual water
saturation
The expected format is “{
gasMax, oilMax }”, in
that order

name groupName required A name is required for any

waterOilRelPermMax- real64_array {0}

Value
Maximum rel perm value
for the pair (water phase,
oil phase) at residual gas
saturation
The expected format is “{
waterMax, oilMax }”, in
that order

698 Chapter 1. Table of Contents

GEOS Documentation

XML Element: BrooksCoreyCapillaryPressure

Name Type De- Description

XML Element: BrooksCoreyRelativePermeability

Name Type De- Description

1.9. Datastructure Index 699

GEOS Documentation

XML Element: BrooksCoreyStone2RelativePermeability

Name Type Default Description

gasOilRelPermExponent real64_array {1}
Rel perm power law
exponent for the pair (gas
phase, oil phase) at
residual water saturation
The expected format is “{
gasExp, oilExp }”, in that
order

gasOilRelPermMaxValue real64_array {0}

Maximum rel perm value
for the pair (gas phase, oil
phase) at residual water
saturation
The expected format is “{
gasMax, oilMax }”, in
that order

Name Type Default Description

XML Element: CellElementRegion

Name Type Default Description

cellBlocks groupNameRef_array required
List of the desired
cell-blocks qualifiers to
contain in this
CellElementRegion.
Qualifiers can be either
cell-block names, region
attribute values, or
fnmatch pattern.The form
of loaded cell-block
names is of “regionAt-
tribute_elementType”, so
“1_tetrahedra” contains
the tetrahedric elements
for which the
regionAttribute is 1.
The element types are:
tetrahedra, pyramids,
wedges, hexahedra,
pentagonalPrisms,
hexagonalPrisms,
heptagonalPrisms,
octagonalPrisms,
nonagonalPrisms,
decagonalPrisms,
hendecagonalPrisms,
polyhedra.

coarseningRatio real64 0 (no description available)

materialList groupNameRef_array required List of materials present in
this region
meshBody groupNameRef Mesh body that contains
this region
name groupName required A name is required for any
non-unique nodes

1.9. Datastructure Index 703

GEOS Documentation

XML Element: CellToCellDataCollection

Name Type Default Description

flowSolverName groupNameRef required Name of the flow solver, to get the permeabilities.
logLevel integer 0 When higher than 1: Display store events details.
meshBody groupNameRef required Name of the target
name groupName required A name is required for any non-unique nodes

XML Element: CeramicDamage

Name Type De- Description

fault
compressiveStrength real64 re- Compressive strength
quired
crackSpeed real64 re- Crack speed
quired
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYoungModulus real64 -1 Default Young’s Modulus
maximumStrength real64 re- Maximum theoretical strength
quired
name group- re- A name is required for any non-unique nodes
Name quired
tensileStrength real64 re- Tensile strength
quired

704 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ChomboIO

Name Type Default Description

beginCycle real64 required Cycle at which the cou-
pling will commence.
childDirectory string Child directory path
inputPath string /IN- Path at which the chombo
VALID_INPUT_PATH to geos file will be written.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Output timing
information

name groupName required A name is required for any

non-unique nodes
outputPath string required Path at which the geos to
chombo file will be writ-
ten.
parallelThreads integer 1 Number of plot files.
useChomboPressures integer 0 True iff geos should use
the pressures chombo
writes out.
waitForInput integer required True iff geos should wait
for chombo to write out a
file. When true the input-
Path must be set.

XML Element: CompositeFunction

Name Type De- Description

1.9. Datastructure Index 705

GEOS Documentation

XML Element: CompositionalMultiphaseFVM

Name Type Default Description

706 Chapter 1. Table of Contents

GEOS Documentation

Table 1.6 – continued from previous page

maxAbsolutePres- real64 -1 Maximum (absolute) pres-

1.9. Datastructure Index 707

GEOS Documentation

Table 1.6 – continued from previous page

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
flowSolverName groupNameRef required Name of the flow solver
used by the coupled solver
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
- Crossflow
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

non-unique nodes
targetRegions
1.9. Datastructure Index groupNameRef_array required Allowable regions that the
715
solver may be applied to.
Note that this does not in-
dicate that the solver will
GEOS Documentation

716 Chapter 1. Table of Contents

GEOS Documentation

XML Element: CompositionalMultiphaseReservoirPoromechanics

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not. Set isThermal=”1”
to enable the thermal cou-
pling
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

non-unique nodes
1.9. Datastructure Index 717
reservoirAndWellsSolver- groupNameRef required Name of the reser-
Name voirAndWells solver used
by the coupled solver
solidSolverName groupNameRef required Name of the solid solver
GEOS Documentation

XML Element: CompositionalMultiphaseReservoirPoromechanicsInitialization

Name Type Default Description

logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Initialization
information

name groupName required A name is required for any

non-unique nodes
poromechanicsSolver- groupNameRef required Name of the poromechan-
Name ics solver
solidMechanicsStatistic- groupNameRef Name of the solid mechan-
sName ics statistics

718 Chapter 1. Table of Contents

GEOS Documentation

XML Element: CompositionalMultiphaseStatistics

XML Element: CompositionalThreePhaseFluidLohrenzBrayClark

Name Type Default Description

checkPVTTablesRanges integer 1 Enable (1) or disable (0)
an error when the input
pressure or temperature of
the PVT tables is out of
range.
componentAcentricFactor real64_array required Component acentric fac-
tors
componentBinaryCoeff real64_array2d {{0}} Table of binary interaction
coefficients
componentCriticalPres- real64_array required Component critical pres-
sure sures
componentCriticalTem- real64_array required Component critical tem-
perature peratures
componentCriticalVol- real64_array {0} Component critical vol-
ume umes
componentMolarWeight real64_array required Component molar weights
componentNames string_array required List of component names
componentVolumeShift real64_array {0} Component volume shifts
equationsOfState string_array required
List of equation of state
types for each phase.
Valid options:
* pr
* srk

name groupName required A name is required for any

non-unique nodes
phaseNames groupNameRef_array required List of fluid phases
viscosityMixingRule string HerningZipperer
Viscosity mixing rule to
be used for
Lohrenz-Bray-Clark
computation. Valid
options:
* HerningZipperer
* Wilke
* Brokaw

waterCompressibility real64 required The compressibility of wa-

ter
waterDensity real64 required The water density at the
reference pressure and
temperature
waterExpansionCoeffi- real64 0 The volumetric coefficient
cient of thermal expansion of
water
waterReferencePressure real64 required The reference pressure for
water density and viscos-
ity
waterReferenceTempera- real64 293.15 The reference temperature
ture
722 for 1.
Chapter water density
Table and vis-
of Contents
cosity
waterViscosity real64 required The water viscosity at the
reference pressure and
GEOS Documentation

XML Element: CompositionalTwoPhaseFluid

Name Type Default Description

checkPVTTablesRanges integer 1 Enable (1) or disable (0)
an error when the input
pressure or temperature of
the PVT tables is out of
range.
componentAcentricFactor real64_array required Component acentric fac-
tors
componentBinaryCoeff real64_array2d {{0}} Table of binary interaction
coefficients
componentCriticalPres- real64_array required Component critical pres-
sure sures
componentCriticalTem- real64_array required Component critical tem-
perature peratures
componentCriticalVol- real64_array {0} Component critical vol-
ume umes
componentMolarWeight real64_array required Component molar weights
componentNames string_array required List of component names
componentVolumeShift real64_array {0} Component volume shifts
constantPhaseViscosity real64_array {0} Constant phase viscosity
equationsOfState string_array required
List of equation of state
types for each phase.
Valid options:
* pr
* srk

name groupName required A name is required for any

non-unique nodes
phaseNames groupNameRef_array required List of fluid phases

1.9. Datastructure Index 723

GEOS Documentation

XML Element: CompositionalTwoPhaseFluidLohrenzBrayClark

Name Type Default Description

name groupName required A name is required for any

724 Chapter 1. Table of Contents

GEOS Documentation

XML Element: CompressibleSinglePhaseFluid

Name Type Default Description

name groupName required A name is required for any

XML Element: CompressibleSolidCarmanKozenyPermeability

Name Type Default Description

name groupName required A name is required for any non-unique nodes
permeabilityModelName groupNameRef required Name of the permeability model.
porosityModelName groupNameRef required Name of the porosity model.
solidInternalEnergyModelName groupNameRef Name of the solid internal energy model.
solidModelName groupNameRef required Name of the solid model.

XML Element: CompressibleSolidConstantPermeability

Name Type Default Description

1.9. Datastructure Index 725

GEOS Documentation

XML Element: CompressibleSolidExponentialDecayPermeability

Name Type Default Description

XML Element: CompressibleSolidParallelPlatesPermeability

Name Type Default Description

XML Element: CompressibleSolidPressurePermeability

Name Type Default Description

XML Element: CompressibleSolidSlipDependentPermeability

Name Type Default Description

XML Element: CompressibleSolidWillisRichardsPermeability

Name Type Default Description

726 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ConstantDiffusion

Name Type De- Description

fault
defaultPhaseDiffusivityMulti- real64_array {1} List of phase diffusivity multipliers
pliers
diffusivityComponents real64_array re- xx, yy, and zz components of a diffusivity tensor
quired [m^2/s]
name groupName re- A name is required for any non-unique nodes
quired
phaseNames string_array re- List of fluid phases
quired

XML Element: ConstantPermeability

Name Type Default Description

name group- re- A name is required for any non-unique nodes
Name quired
permeabilityCompo- R1Tensor re- xx, yy and zz components of a diagonal permeability tensor.
nents quired

XML Element: Constitutive

Name Type Default Description

BiotPorosity node XML Element: BiotPorosity
BlackOilFluid node XML Element: BlackOilFluid
BrooksCoreyBakerRelativePermeability node XML Element: BrooksCoreyBakerRelativePermeability
BrooksCoreyCapillaryPressure node XML Element: BrooksCoreyCapillaryPressure
BrooksCoreyRelativePermeability node XML Element: BrooksCoreyRelativePermeability
BrooksCoreyStone2RelativePermeability node XML Element: BrooksCoreyStone2RelativePermeability
CO2BrineEzrokhiFluid node XML Element: CO2BrineEzrokhiFluid
CO2BrineEzrokhiThermalFluid node XML Element: CO2BrineEzrokhiThermalFluid
CO2BrinePhillipsFluid node XML Element: CO2BrinePhillipsFluid
CO2BrinePhillipsThermalFluid node XML Element: CO2BrinePhillipsThermalFluid
CarmanKozenyPermeability node XML Element: CarmanKozenyPermeability
CeramicDamage node XML Element: CeramicDamage
CompositionalMultiphaseFluid node XML Element: CompositionalMultiphaseFluid
CompositionalThreePhaseFluidLohrenzBrayClark node XML Element: CompositionalThreePhaseFluidLohrenzBrayC
CompositionalTwoPhaseFluid node XML Element: CompositionalTwoPhaseFluid
CompositionalTwoPhaseFluidLohrenzBrayClark node XML Element: CompositionalTwoPhaseFluidLohrenzBrayCla
CompressibleSinglePhaseFluid node XML Element: CompressibleSinglePhaseFluid
CompressibleSolidCarmanKozenyPermeability node XML Element: CompressibleSolidCarmanKozenyPermeability
CompressibleSolidConstantPermeability node XML Element: CompressibleSolidConstantPermeability
CompressibleSolidExponentialDecayPermeability node XML Element: CompressibleSolidExponentialDecayPermeab
CompressibleSolidParallelPlatesPermeability node XML Element: CompressibleSolidParallelPlatesPermeability
CompressibleSolidPressurePermeability node XML Element: CompressibleSolidPressurePermeability
CompressibleSolidSlipDependentPermeability node XML Element: CompressibleSolidSlipDependentPermeability
CompressibleSolidWillisRichardsPermeability node XML Element: CompressibleSolidWillisRichardsPermeability
ConstantDiffusion node XML Element: ConstantDiffusion
continues on next p

1.9. Datastructure Index 727

GEOS Documentation

Table 1.8 – continued from previous page

Name Type Default Description
ConstantPermeability node XML Element: ConstantPermeability
Coulomb node XML Element: Coulomb
DamageElasticIsotropic node XML Element: DamageElasticIsotropic
DamageSpectralElasticIsotropic node XML Element: DamageSpectralElasticIsotropic
DamageVolDevElasticIsotropic node XML Element: DamageVolDevElasticIsotropic
DeadOilFluid node XML Element: DeadOilFluid
DelftEgg node XML Element: DelftEgg
DruckerPrager node XML Element: DruckerPrager
ElasticIsotropic node XML Element: ElasticIsotropic
ElasticIsotropicPressureDependent node XML Element: ElasticIsotropicPressureDependent
ElasticOrthotropic node XML Element: ElasticOrthotropic
ElasticTransverseIsotropic node XML Element: ElasticTransverseIsotropic
ExponentialDecayPermeability node XML Element: ExponentialDecayPermeability
ExtendedDruckerPrager node XML Element: ExtendedDruckerPrager
FrictionlessContact node XML Element: FrictionlessContact
HydraulicApertureTable node XML Element: HydraulicApertureTable
JFunctionCapillaryPressure node XML Element: JFunctionCapillaryPressure
LinearIsotropicDispersion node XML Element: LinearIsotropicDispersion
ModifiedCamClay node XML Element: ModifiedCamClay
MultiPhaseConstantThermalConductivity node XML Element: MultiPhaseConstantThermalConductivity
MultiPhaseVolumeWeightedThermalConductivity node XML Element: MultiPhaseVolumeWeightedThermalConductiv
NullModel node XML Element: NullModel
ParallelPlatesPermeability node XML Element: ParallelPlatesPermeability
ParticleFluid node XML Element: ParticleFluid
PerfectlyPlastic node XML Element: PerfectlyPlastic
PorousDamageElasticIsotropic node XML Element: PorousDamageElasticIsotropic
PorousDamageSpectralElasticIsotropic node XML Element: PorousDamageSpectralElasticIsotropic
PorousDamageVolDevElasticIsotropic node XML Element: PorousDamageVolDevElasticIsotropic
PorousDelftEgg node XML Element: PorousDelftEgg
PorousDruckerPrager node XML Element: PorousDruckerPrager
PorousElasticIsotropic node XML Element: PorousElasticIsotropic
PorousElasticOrthotropic node XML Element: PorousElasticOrthotropic
PorousElasticTransverseIsotropic node XML Element: PorousElasticTransverseIsotropic
PorousExtendedDruckerPrager node XML Element: PorousExtendedDruckerPrager
PorousModifiedCamClay node XML Element: PorousModifiedCamClay
PorousViscoDruckerPrager node XML Element: PorousViscoDruckerPrager
PorousViscoExtendedDruckerPrager node XML Element: PorousViscoExtendedDruckerPrager
PorousViscoModifiedCamClay node XML Element: PorousViscoModifiedCamClay
PressurePermeability node XML Element: PressurePermeability
PressurePorosity node XML Element: PressurePorosity
ProppantPermeability node XML Element: ProppantPermeability
ProppantPorosity node XML Element: ProppantPorosity
ProppantSlurryFluid node XML Element: ProppantSlurryFluid
ProppantSolidProppantPermeability node XML Element: ProppantSolidProppantPermeability
RateAndStateFriction node XML Element: RateAndStateFriction
ReactiveBrine node XML Element: ReactiveBrine
ReactiveBrineThermal node XML Element: ReactiveBrineThermal
SinglePhaseThermalConductivity node XML Element: SinglePhaseThermalConductivity
SlipDependentPermeability node XML Element: SlipDependentPermeability
SolidInternalEnergy node XML Element: SolidInternalEnergy
continues on next p

728 Chapter 1. Table of Contents

GEOS Documentation

Table 1.8 – continued from previous page

Name Type Default Description
TableCapillaryPressure node XML Element: TableCapillaryPressure
TableRelativePermeability node XML Element: TableRelativePermeability
TableRelativePermeabilityHysteresis node XML Element: TableRelativePermeabilityHysteresis
ThermalCompressibleSinglePhaseFluid node XML Element: ThermalCompressibleSinglePhaseFluid
VanGenuchtenBakerRelativePermeability node XML Element: VanGenuchtenBakerRelativePermeability
VanGenuchtenCapillaryPressure node XML Element: VanGenuchtenCapillaryPressure
VanGenuchtenStone2RelativePermeability node XML Element: VanGenuchtenStone2RelativePermeability
ViscoDruckerPrager node XML Element: ViscoDruckerPrager
ViscoExtendedDruckerPrager node XML Element: ViscoExtendedDruckerPrager
ViscoModifiedCamClay node XML Element: ViscoModifiedCamClay
WillisRichardsPermeability node XML Element: WillisRichardsPermeability

XML Element: Coulomb

Name Type Default Description

cohesion real64 required Cohesion
displacemen- real64 2.22045e- A threshold valued to determine whether a fracture is open
tJumpThreshold 16 or not.
frictionCoefficient real64 required Friction coefficient
name group- required A name is required for any non-unique nodes
Name
shearStiffness real64 0 Value of the shear elastic stiffness. Units of Pressure/length

XML Element: CustomPolarObject

Name Type De- Description

fault
center R1Tensor re- (x,y,z) coordinates of the center of the CustomPolarObject
quired
coeffi- real64_array
re- Coefficients of the CustomPolarObject function relating the localradius to the angle
cients quired theta.
length- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
Vector quired
name group- re- A name is required for any non-unique nodes
Name quired
normal R1Tensor re- Normal (n_x,n_y,n_z) to the plane (will be normalized automatically)
quired
toler- real64 1e- Tolerance to determine if a point sits on the CustomPolarObject or not. It is relative
ance 05 to the maximum dimension of the CustomPolarObject.
widthVec- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
tor quired

1.9. Datastructure Index 729

GEOS Documentation

XML Element: Cylinder

Name Type Default Description

firstFaceCenter R1Tensor required Center point of the first face of the cylinder
innerRadius real64 -1 Inner radius of the annulus
name groupName required A name is required for any non-unique nodes
outerRadius real64 required Outer radius of the cylinder
secondFaceCenter R1Tensor required Center point of the second face of the cylinder

XML Element: DamageElasticIsotropic

Name Type De- Description

fault
compressiveStrength real64 0 Compressive strength from the uniaxial compression test
criticalFractureEnergy real64 re- Critical fracture energy
quired
criticalStrainEnergy real64 re- Critical stress in a 1d tension test
quired
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYoungModulus real64 -1 Default Young’s Modulus
degradationLower- real64 0 The lower limit of the degradation function
Limit
deltaCoefficient real64 -1 Coefficient in the calculation of the external driving force
extDrivingForceFlag integer 0 Whether to have external driving force. Can be 0 or 1
lengthScale real64 re- Length scale l in the phase-field equation
quired
name group- re- A name is required for any non-unique nodes
Name quired
tensileStrength real64 0 Tensile strength from the uniaxial tension test

730 Chapter 1. Table of Contents

GEOS Documentation

XML Element: DamageSpectralElasticIsotropic

Name Type De- Description

1.9. Datastructure Index 731

GEOS Documentation

XML Element: DamageVolDevElasticIsotropic

Name Type De- Description

732 Chapter 1. Table of Contents

GEOS Documentation

XML Element: DeadOilFluid

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
phaseNames groupNameRef_array required List of fluid phases
surfaceDensities real64_array required List of surface mass densi-
ties for each phase
tableFiles path_array {} List of filenames with in-
put PVT tables (one per
phase)
waterCompressibility real64 0 Water compressibility
waterFormationVolume- real64 0 Water formation volume
Factor
1.9. Datastructure Index factor 733
waterReferencePressure real64 0 Water reference pressure
waterViscosity real64 0 Water viscosity
GEOS Documentation

XML Element: DelftEgg

Name Type De- Description

fault
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultCslSlope real64 1 Slope of the critical state line
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLinearTEC real64 0 Default Linear Thermal Expansion Coefficient of the Solid
Rock Frame
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultPreConsolidation- real64 -1.5 Initial preconsolidation pressure
Pressure
defaultRecompressionIn- real64 0.002 Recompresion Index
dex
defaultShapeParameter real64 1 Shape parameter for the yield surface
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultVirginCompres- real64 0.005 Virgin compression index
sionIndex
defaultYoungModulus real64 -1 Default Young’s Modulus
name group- re- A name is required for any non-unique nodes
Name quired

XML Element: Dirichlet

Name Type De- Description

fault
bcApplica- groupNameRef Name of table that specifies the on/off application of the
tionTableName boundary condition.
beginTime real64 - Time at which the boundary condition will start being applied.
1e+99
component integer -1 Component of field (if tensor) to apply boundary condition to.
direction R1Tensor {0,0,0} Direction to apply boundary condition to.
endTime real64 1e+99 Time at which the boundary condition will stop being applied.
fieldName groupNameRef Name of field that boundary condition is applied to.
functionName groupNameRef Name of function that specifies variation of the boundary con-
dition.
initialCondition integer 0 Boundary condition is applied as an initial condition.
logLevel integer 0 Log level
name groupName re- A name is required for any non-unique nodes
quired
objectPath groupNameRef Path to the target field
scale real64 0 Scale factor for value of the boundary condition.
setNames group- re- Name of sets that boundary condition is applied to.
NameRef_array quired

734 Chapter 1. Table of Contents

GEOS Documentation

XML Element: Disc

Name Type De- Description

fault
center R1Tensor re- (x,y,z) coordinates of the center of the disc
quired
length- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
Vector quired
name group- re- A name is required for any non-unique nodes
Name quired
normal R1Tensor re- Normal (n_x,n_y,n_z) to the plane (will be normalized automatically)
quired
radius real64 re- Radius of the disc.
quired
tolerance real64 1e-05 Tolerance to determine if a point sits on the disc or not. It is relative to the maxi-
mum dimension of the disc.
widthVec- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
tor quired

XML Element: DruckerPrager

Name Type De- Description

XML Element: ElasticFirstOrderSEM

Name Type Default Description

GEOS Documentation

Table 1.9 – continued from previous page

XML Element: ElasticIsotropic

Name Type De- Description

1.9. Datastructure Index 739

GEOS Documentation

XML Element: ElasticIsotropicPressureDependent

Name Type De- Description

fault
defaultDensity real64 re- Default Material Density
quired
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid Rock
earTEC Frame
defaultRecompres- real64 0.002 Recompresion Index
sionIndex
defaultRefPressure real64 -1 Reference Pressure
defaultRefStrainVol real64 0 Reference Volumetric Strain
defaultShearModulus real64 -1 Elastic Shear Modulus Parameter
name group- re- A name is required for any non-unique nodes
Name quired

XML Element: ElasticOrthotropic

Name Type De- Description

XML Element: ElasticSEM

740 Chapter 1. Table of Contents

GEOS Documentation

Name Type Default Description

1.9. Datastructure Index 741

GEOS Documentation

Table 1.10 – continued from previous page

name groupName required A name is required for any

1.9. Datastructure Index 747

GEOS Documentation

XML Element: ExternalDataSource

Name Type Default Description

VTKHierarchicalDataSource node XML Element: VTKHierarchicalDataSource

XML Element: FieldSpecification

Name Type De- Description

XML Element: FieldSpecifications

Name Type Default Description

Aquifer node XML Element: Aquifer
Dirichlet node XML Element: Dirichlet
FieldSpecification node XML Element: FieldSpecification
HydrostaticEquilibrium node XML Element: HydrostaticEquilibrium
PML node XML Element: PML
SourceFlux node XML Element: SourceFlux
Traction node XML Element: Traction

XML Element: File

Name Type Default Description

name path required The relative file path.

748 Chapter 1. Table of Contents

Box node XML Element: Box
CustomPolarObject node XML Element: CustomPolarObject
Cylinder node XML Element: Cylinder
Disc node XML Element: Disc
Rectangle node XML Element: Rectangle
ThickPlane node XML Element: ThickPlane

1.9. Datastructure Index 751

GEOS Documentation

XML Element: HaltEvent

Name Type De- Description

fault
beginTime real64 0 Start time of this event.
endTime real64 1e+100 End time of this event.
finalDt- real64 0.001 Allow the final dt request for this event to grow by this percentage to match
Stretch the endTime exactly.
forceDt real64 -1 While active, this event will request this timestep value (ignoring any chil-
dren/targets requests).
logLevel integer 0 Log level
maxEventDt real64 -1 While active, this event will request a timestep <= this value (depending upon
any child/target requests).
maxRuntime real64 re- The maximum allowable runtime for the job.
quired
name group- re- A name is required for any non-unique nodes
Name quired
target group- Name of the object to be executed when the event criteria are met.
NameRef
targetExact- integer 1 If this option is set, the event will reduce its timestep requests to match any
StartStop specified beginTime/endTimes exactly.
HaltEvent node XML Element: HaltEvent
Peri- node XML Element: PeriodicEvent
odicEvent
SoloEvent node XML Element: SoloEvent

XML Element: HybridMimeticDiscretization

Name Type Default Description

innerProductType string required Type of inner product used in the hybrid FVM solver
name groupName required A name is required for any non-unique nodes

XML Element: HydraulicApertureTable

Name Type De- Description

fault
aper- group-re- Name of the aperture table
tureTable-
NameRef
quired
Name
aper- real64 1e- Value to be used to avoid floating point errors in expressions involving aperture. For example
ture- 09 in the case of dividing by the actual aperture (not the effective aperture that results from the
Tol- aperture function) this value may be used to avoid the 1/0 error. Note that this value may
er- have some physical significance in its usage, as it may be used to smooth out highly nonlinear
ance behavior associated with 1/0 in addition to avoiding the 1/0 error.
name group-re- A name is required for any non-unique nodes
Name quired
ref- real64 1e- Reference hydraulic aperture. It is the aperture at zero normal stress.
er- 06
enceAper-
ture

752 Chapter 1. Table of Contents

GEOS Documentation

1.9. Datastructure Index 753

GEOS Documentation

XML Element: Hydrofracture

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
flowSolverName groupNameRef required Name of the flow solver
used by the coupled solver
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isLaggingFractureStencil- integer 0 Flag to determine whether
WeightsUpdate or not to apply lagging up-
date for the fracture stencil
weights.
isMatrixPoroelastic integer 0 (no description available)
isThermal integer 0 Flag indicating whether
the problem is thermal or
not. Set isThermal=”1”
to enable the thermal cou-
pling
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
754 Chapter 1. -Table of Contents
Fracture
generation
information
2
GEOS Documentation

XML Element: HydrofractureInitialization

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
poromechanicsSolver- groupNameRef required Name of the poromechan-
Name ics solver
solidMechanicsStatistic- groupNameRef Name of the solid mechan-
sName ics statistics

1.9. Datastructure Index 755

GEOS Documentation

XML Element: HydrostaticEquilibrium

Name Type De- Description

XML Element: Included

Name Type Default Description

File node XML Element: File

756 Chapter 1. Table of Contents

GEOS Documentation

XML Element: InternalMesh

Name Type De- Description

nonWettingIntermedi- real64 0
ateSurfaceTension
Surface tension [N/m] for
the pair (non-wetting
phase, intermediate
phase)
If you have a value in
[dyne/cm], divide it by
1000 to obtain the value
in [N/m]
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettingSur-
faceTension to specify the
surface tensions.

permeabilityDirection geos_constitutive_JFunctionCapillaryPressure_PermeabilityDirection
required
Permeability direction.
Options are:
XY - use the average of
the permeabilities in the x
and y directions,
X - only use the
permeability in the x
direction,
Y - only use the
permeability in the y
direction,
Z - only use the
permeability in the z
direction.
1.9. Datastructure Index 761
permeabilityExponent real64 0.5 Permeability exponent
phaseNames groupNameRef_array required List of fluid phases
porosityExponent real64 0.5 Porosity exponent
GEOS Documentation

762 Chapter 1. Table of Contents

GEOS Documentation

XML Element: LaplaceFEM

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
fieldName groupNameRef required Name of field variable
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
1.9. Datastructure Index 2 763
- The summary of
declared fields and
coupling
GEOS Documentation

XML Element: LinearIsotropicDispersion

Name Type Default Description

longitudinalDispersivity real64 required Longitudinal dispersivity [m]
name groupName required A name is required for any non-unique nodes

XML Element: LinearSolverParameters

Name Type Default Description

adaptiveExponent real64 1 Exponent parameter for
adaptive method
adaptiveGamma real64 0.1 Gamma parameter for
adaptive method
amgAggressiveCoarsen- integer 0 AMG number of levels for
ingLevels aggressive coarsening
amgAggressiveCoarsen- integer 1 AMG number of paths for
ingPaths aggressive coarsening
amgAggressiveInterp- geos_LinearSolverParameters_AMG_AggInterpType
multipass AMG aggressive in-
Type terpolation algo-
rithm. Available op-
tions are: default\
|extendedIStage2\
|standardStage2\
|extendedStage2\
|multipass\
|modifiedExtended\
|modifiedExtendedI\
|modifiedExtendedE\
|modifiedMultipass
amgCoarseSolver geos_LinearSolverParameters_AMG_CoarseType
direct AMG coarsest level
solver/smoother type.
Available options are:
default\|jacobi\
|l1jacobi\|fgs\|sgs\
|l1sgs\|chebyshev\
|direct\|bgs\
|gsElimWPivoting\
|gsElimWInverse
amgCoarseningType geos_LinearSolverParameters_AMG_CoarseningType
HMIS AMG coarsening al-
gorithm. Available
options are: default\
|CLJP\|RugeStueben\
|Falgout\|PMIS\|HMIS
amgInterpolation- integer 4 AMG interpolation maxi-
MaxNonZeros mum number of nonzeros
per row
continues on next page

764 Chapter 1. Table of Contents

GEOS Documentation

Table 1.11 – continued from previous page

Name Type Default Description
amgInterpolationType geos_LinearSolverParameters_AMG_InterpType
extendedI AMG interpolation
algorithm. Available
options are: default\
|modifiedClassical\
|direct\|multipass\
|extendedI\
|standard\|extended\
|directBAMG\
|modifiedExtended\
|modifiedExtendedI\
|modifiedExtendedE
amgNullSpaceType geos_LinearSolverParameters_AMG_NullSpaceType
constantModes AMG near null
space approximation.
Available options
are:constantModes\
|rigidBodyModes
amgNumFunctions integer 1 AMG number of functions
amgNumSweeps integer 1 AMG smoother sweeps
amgRelaxWeight real64 1 AMG relaxation factor for
the smoother
amgSeparateComponents integer 0 AMG apply separate com-
ponent filter for multi-
variable problems
amgSmootherType geos_LinearSolverParameters_AMG_SmootherType
l1sgs AMG smoother type.
Available options are:
default\|jacobi\
|l1jacobi\|fgs\
|bgs\|sgs\|l1sgs\
|chebyshev\|ilu0\
|ilut\|ic0\|ict
amgThreshold real64 0 AMG strength-of-
connection threshold
directCheckResidual integer 0 Whether to check the lin-
ear system solution resid-
ual
directColPerm geos_LinearSolverParameters_Direct_ColPerm
metis How to permute the
columns. Available
options are: none\
|MMD_AtplusA\
|MMD_AtA\|colAMD\
|metis\|parmetis
directEquil integer 1 Whether to scale the rows
and columns of the matrix
directIterRef integer 1 Whether to perform itera-
tive refinement
directParallel integer 1 Whether to use a parallel
solver (instead of a serial
one)
continues on next page

1.9. Datastructure Index 765

GEOS Documentation

Table 1.11 – continued from previous page

Name Type Default Description
directReplTinyPivot integer 1 Whether to re-
place tiny pivots by
sqrt(epsilon)*norm(A)
directRowPerm geos_LinearSolverParameters_Direct_RowPerm
mc64 How to permute the rows.
Available options are:
none\|mc64
iluFill integer 0 ILU(K) fill factor
iluThreshold real64 0 ILU(T) threshold factor
krylovAdaptiveTol integer 0 Use Eisenstat-Walker
adaptive linear tolerance
krylovMaxIter integer 200 Maximum iterations
allowed for an iterative
solver
krylovMaxRestart integer 200 Maximum iterations be-
fore restart (GMRES only)
krylovStrongestTol real64 1e-08 Strongest-allowed toler-
ance for adaptive method
krylovTol real64 1e-06
Relative convergence
tolerance of the iterative
method
If the method converges,
the iterative solution x𝑘 is
such that
the relative residual norm
satisfies:
‖b − Ax𝑘 ‖2 <
krylovTol * ‖b‖2

krylovWeakestTol real64 0.001 Weakest-allowed toler-

766 Chapter 1. Table of Contents

GEOS Documentation

XML Element: Mesh

Name Type Default Description

InternalMesh node XML Element: InternalMesh
InternalWellbore node XML Element: InternalWellbore
ParticleMesh node XML Element: ParticleMesh
VTKMesh node XML Element: VTKMesh

XML Element: ModifiedCamClay

Name Type De- Description

XML Element: MultiPhaseConstantThermalConductivity

Name Type De- Description

fault
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- re- List of fluid phases
NameRef_array quired
thermalConductivity- R1Tensor re- xx, yy, and zz components of a diagonal thermal conductiv-
Components quired ity tensor [J/(s.m.K)]

1.9. Datastructure Index 767

GEOS Documentation

XML Element: MultiPhaseVolumeWeightedThermalConductivity

Name Type De- Description

fault
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- re- List of fluid phases
NameRef_array quired
phaseThermalConductiv- real64_array re- Phase thermal conductivity [W/(m.K)]
ity quired
rockThermalConductivi- R1Tensor re- xx, yy, and zz components of a diagonal rock thermal con-
tyComponents quired ductivity tensor [W/(m.K)]

768 Chapter 1. Table of Contents

GEOS Documentation

XML Element: MultiphasePoromechanics

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
flowSolverName groupNameRef required Name of the flow solver
used by the coupled solver
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not. Set isThermal=”1”
to enable the thermal cou-
pling
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
2
- The summary of
declared fields and
coupling
1.9. Datastructure Index 769
name groupName required A name is required for any
non-unique nodes
solidSolverName groupNameRef required Name of the solid solver
used by the coupled solver
GEOS Documentation

XML Element: MultiphasePoromechanicsInitialization

FiniteElements node unique XML Element: FiniteElements
FiniteVolume node unique XML Element: FiniteVolume

XML Element: Outputs

Name Type Default Description

Blueprint node XML Element: Blueprint
ChomboIO node XML Element: ChomboIO
Python node XML Element: Python
Restart node XML Element: Restart
Silo node XML Element: Silo
TimeHistory node XML Element: TimeHistory
VTK node XML Element: VTK

774 Chapter 1. Table of Contents

GEOS Documentation

XML Element: PML

Name Type Default Description

bcApplica- group- Name of table that specifies the on/off application of the
tionTable- NameRef boundary condition.
Name
beginTime real64 -1e+99 Time at which the boundary condition will start being
applied.
component integer -1 Component of field (if tensor) to apply boundary con-
dition to.
direction R1Tensor {0,0,0} Direction to apply boundary condition to.
endTime real64 1e+99 Time at which the boundary condition will stop being
applied.
function- group- Name of function that specifies variation of the bound-
Name NameRef ary condition.
logLevel integer 0 Log level
name groupName required A name is required for any non-unique nodes
objectPath group- Path to the target field
NameRef
reflectivity real32 0.001 Desired reflectivity of the PML region, used to compute
the damping profile
scale real64 0 Scale factor for value of the boundary condition.
setNames group- required Name of sets that boundary condition is applied to.
NameRef_array
thickness- R1Tensor32 {-1,-1,-1} Thickness of the PML region, at right, back, and bottom
MaxXYZ sides, used to compute the damping profile
thickness- R1Tensor32 {-1,-1,-1} Thickness of the PML region, at left, front, and top
MinXYZ sides, used to compute the damping profile
waveSpeed- R1Tensor32 {-1,-1,-1} Wave speed in the PML, at right, back, and bottom
MaxXYZ sides, used to compute the damping profile
waveSpeed- R1Tensor32 {-1,-1,-1} Wave speed in the PML, at left, front, and top sides,
MinXYZ used to compute the damping profile
xMax R1Tensor32 {3.40282e+38,3.40282e+38,3.40282e+38}
Maximum (x,y,z) coordinates of the inner PML bound-
aries
xMin R1Tensor32 {-3.40282e+38,- Minimum (x,y,z) coordinates of the inner PML bound-
3.40282e+38,- aries
3.40282e+38}

1.9. Datastructure Index 775

GEOS Documentation

XML Element: PVTDriver

Name Type De- Description

XML Element: PackCollection

Name Type De- Description

XML Element: ParallelPlatesPermeability

Name Type De- Description

776 Chapter 1. Table of Contents

GEOS Documentation

XML Element: Parameter

Name Type Default Description

name groupName required A name is required for any non-unique nodes
value string required Input parameter definition for the preprocessor

XML Element: Parameters

XML Element: ParticleRegions

Name Type Default Description

ParticleRegion node XML Element: ParticleRegion

XML Element: PerfectlyPlastic

Name Type Default Description

defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultDensity real64 required Default Material Density
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid
earTEC Rock Frame
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYieldStress real64 1.79769e+308 Default yield stress
defaultYoungModu- real64 -1 Default Young’s Modulus
lus
name group- required A name is required for any non-unique nodes
Name

XML Element: Perforation

Name Type Default Description

distanceFromHead real64 required Linear distance from well head to the perforation
name groupName required A name is required for any non-unique nodes
skinFactor real64 0 Perforation skin factor
transmissibility real64 -1 Perforation transmissibility

778 Chapter 1. Table of Contents

GEOS Documentation

XML Element: PeriodicEvent

Name Type De- Description

Name Type Default Description

XML Element: PorousDamageVolDevElasticIsotropic

Name Type Default Description

XML Element: PorousDelftEgg

Name Type Default Description

XML Element: PorousDruckerPrager

Name Type Default Description

1.9. Datastructure Index 783

GEOS Documentation

XML Element: PorousElasticIsotropic

Name Type Default Description

XML Element: PorousElasticOrthotropic

Name Type Default Description

XML Element: PorousElasticTransverseIsotropic

Name Type Default Description

XML Element: PorousExtendedDruckerPrager

Name Type Default Description

XML Element: PorousModifiedCamClay

Name Type Default Description

784 Chapter 1. Table of Contents

GEOS Documentation

XML Element: PorousViscoDruckerPrager

Name Type Default Description

XML Element: PorousViscoExtendedDruckerPrager

Name Type Default Description

XML Element: PorousViscoModifiedCamClay

Name Type Default Description

defaultReferencePorosity real64 required Default value of the reference porosity
maxProppantConcentration real64 required Maximum proppant concentration
name groupName required A name is required for any non-unique nodes

786 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ProppantSlurryFluid

Name Type Default Description

componentNames string_array {} List of fluid component names
compressibility real64 0 Fluid compressibility
defaultComponentDensity real64_array {0} Default value for the component density.
defaultComponentViscosity real64_array {0} Default value for the component viscosity.
defaultCompressibility real64_array {0} Default value for the component compressibility.
flowBehaviorIndex real64_array {0} Flow behavior index
flowConsistencyIndex real64_array {0} Flow consistency index
maxProppantConcentration real64 0.6 Maximum proppant concentration
name groupName required A name is required for any non-unique nodes
referenceDensity real64 1000 Reference fluid density
referencePressure real64 100000 Reference pressure
referenceProppantDensity real64 1400 Reference proppant density
referenceViscosity real64 0.001 Reference fluid viscosity

XML Element: ProppantSolidProppantPermeability

Name Type Default Description

1.9. Datastructure Index 787

GEOS Documentation

XML Element: ProppantTransport

Name Type Default Description

allowNegativePressure integer 1 Flag indicating if negative
pressure is allowed
bridgingFactor real64 0 Bridging factor used for
bridging/screen-out calcu-
lation
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
criticalShieldsNumber real64 0 Critical Shields number
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
frictionCoefficient real64 0.03 Friction coefficient
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
788 Chapter 1. Table of Contents
- Time step
information
- Linear solver
GEOS Documentation

XML Element: Python

defaultA real64 required Default value of the Rate- and State-dependent friction coeffi-
cient a.
defaultB real64 required Default value of the Rate- and State-dependent friction coeffi-
cient b.
defaultDc real64 required Default value of the Rate- and State-dependent friction char-
acteristic length.
defaultReferenceFriction- real64 required Default value of the Rate- and State-dependent friction refer-
Coefficient ence friction coefficient.
defaultReferenceVelocity real64 required Default value of the Rate- and State-dependent friction refer-
ence slip rate.
displacemen- real64 2.22045e- A threshold valued to determine whether a fracture is open or
tJumpThreshold 16 not.
name group- required A name is required for any non-unique nodes
Name

XML Element: ReactiveBrine

Name Type De- Description

fault
checkPVTTa- integer 1 Enable (1) or disable (0) an error when the input pressure or tempera-
blesRanges ture of the PVT tables is out of range.
componentMo- real64_array {0} Component molar weights
larWeight
component- string_array {} List of component names
Names
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- {} List of fluid phases
NameRef_array
phasePVT- path_array re- Names of the files defining the parameters of the viscosity and density
ParaFiles quired models
writeCSV integer 0 Write PVT tables into a CSV file

1.9. Datastructure Index 793

GEOS Documentation

XML Element: ReactiveBrineThermal

Name Type De- Description

fault
checkPVTTa- integer 1 Enable (1) or disable (0) an error when the input pressure or tempera-
blesRanges ture of the PVT tables is out of range.
componentMo- real64_array {0} Component molar weights
larWeight
component- string_array {} List of component names
Names
name groupName re- A name is required for any non-unique nodes
quired
phaseNames group- {} List of fluid phases
NameRef_array
phasePVT- path_array re- Names of the files defining the parameters of the viscosity and density
ParaFiles quired models
writeCSV integer 0 Write PVT tables into a CSV file

794 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ReactiveCompositionalMultiphaseOBL

Name Type Default Description

OBLOperatorsTableFile path required File containing OBL oper-
ator values
allowLocalOBLChopping integer 1 Allow keeping solution
within OBL limits
allowNegativePressure integer 1 Flag indicating if negative
pressure is allowed
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
componentNames string_array {} List of component names
discretization groupNameRef required Name of discretization ob-
ject (defined in the Numer-
ical Methods) to use for
this solver. For instance,
if this is a Finite Ele-
ment Solver, the name of a
Finite Element Discretiza-
tion should be specified.
If this is a Finite Volume
Method, the name of a
Finite Volume Discretiza-
tion discretization should
be specified.
enableEnergyBalance integer required Enable energy balance cal-
culation and temperature
degree of freedom
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
1.9. Datastructure Index check) 795
- Convergence
information
GEOS Documentation

XML Element: ReactiveFluidDriver

Name Type Default Description

baseline path none Baseline file
feedComposition real64_array re- Feed composition array: total concentration of the primary
quired species
fluid group- re- Fluid to test
NameRef quired
logLevel integer 0 Log level
name groupName re- A name is required for any non-unique nodes
quired
output string none Output file
pressureControl group- re- Function controlling pressure time history
NameRef quired
steps integer re- Number of load steps to take
quired
temperatureCon- group- re- Function controlling temperature time history
trol NameRef quired

XML Element: Rectangle

Name Type De- Description

fault
dimen- real64_arrayre- Length and width of the bounded plane
sions quired
length- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
Vector quired
name group- re- A name is required for any non-unique nodes
Name quired
normal R1Tensor re- Normal (n_x,n_y,n_z) to the plane (will be normalized automatically)
quired
origin R1Tensor re- Origin point (x,y,z) of the plane (basically, any point on the plane)
quired
tolerance real64 1e-05 Tolerance to determine if a point sits on the plane or not. It is relative to the
maximum dimension of the plane.
widthVec- R1Tensor re- Tangent vector defining the orthonormal basis along with the normal.
tor quired

XML Element: Region

Name Type Default Description

id integer required Interval region identifier
name groupName required A name is required for any non-unique nodes
pathInRepository string required Path of the dataset in the repository

796 Chapter 1. Table of Contents

GEOS Documentation

XML Element: RelpermDriver

Name Type Default Description

baseline path none Baseline file
logLevel integer 0 Log level
name groupName required A name is required for any non-unique nodes
output string none Output file
relperm groupNameRef required Relperm model to test
steps integer required Number of saturation steps to take

XML Element: Restart

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
parallelThreads integer 1 Number of plot files.

1.9. Datastructure Index 797

GEOS Documentation

XML Element: Run

Name Type De- Description

fault
args string Any extra command line arguments to pass to GEOSX.
autoPar- string May be ‘Off’ or ‘On’, if ‘On’ partitioning arguments are created automatically. Default
tition is Off.
mesh- inte- {0} The target number of elements in the internal mesh (per-process for weak scaling,
Sizes ger_array globally for strong scaling) default doesn’t modify the internalMesh.
name string re- The name of this benchmark.
quired
nodes integer 0 The number of nodes needed to run the base benchmark, default is 1.
scaleList inte- {0} The scales at which to run the problem ( scale * nodes * tasksPerNode ).
ger_array
scaling string Whether to run a scaling, and which type of scaling to run.
tasksPerN- integer re- The number of tasks per node to run the benchmark with.
ode quired
threadsPer- integer 0 The number of threads per task to run the benchmark with.
Task
time- integer 0 The time limit of the benchmark.
Limit

798 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SeismicityRate

Name Type Default Description

backgroundStressingRate real64 required Background stressing rate
(Pa/s).
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
directEffect real64 required Rate-and-state friction di-
rect effect parameter.
faultNormalDirection R1Tensor {0,0,0} Fault normal direction
faultShearDirection R1Tensor {0,0,0} Fault shear direction
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

non-unique nodes
stressSolverName string Name of solver for com-
1.9. Datastructure Index puting stress 799
targetRegions groupNameRef_array required Allowable regions that the
solver may be applied to.
Note that this does not in-
GEOS Documentation

XML Element: Silo

Name Type Default Description

name groupName required A name is required for any

800 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SinglePhaseFVM

Name Type Default Description

logLevel integer 0

1.9. Datastructure Index Sets the level of 801

information to write in the
standard output (the
console typically).
GEOS Documentation

802 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SinglePhaseHybridFVM

Name Type Default Description

logLevel integer 0

non-unique nodes
poromechanicsSolver- groupNameRef required Name of the poromechan-
Name ics solver
solidMechanicsStatistic- groupNameRef Name of the solid mechan-
sName ics statistics

808 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SinglePhasePoromechanicsConformingFracturesReservoir

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

non-unique nodes
poromechanicsConform- groupNameRef required Name of the poromechan-
ingFracturesSolverName icsConformingFractures
solver used by the coupled
solver
targetRegions groupNameRef_array required Allowable regions that the
1.9. Datastructure Index 809
solver may be applied to.
Note that this does not in-
dicate that the solver will
be applied to these re-
GEOS Documentation

810 Chapter 1. Table of Contents

812 Chapter 1. Table of Contents

GEOS Documentation

1.9. Datastructure Index 813

GEOS Documentation

XML Element: SinglePhasePoromechanicsReservoir

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Coupling
information
2
- The summary of
declared fields and
coupling

name groupName required A name is required for any

non-unique nodes
822 Chapter 1. Table of Contents
reservoirAndWellsSolver- groupNameRef required Name of the reser-
Name voirAndWells solver used
by the coupled solver
solidSolverName groupNameRef required Name of the solid solver
GEOS Documentation

XML Element: SinglePhaseReservoirPoromechanicsConformingFracturesInitialization

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
poromechanicsSolver- groupNameRef required Name of the poromechan-
Name ics solver
solidMechanicsStatistic- groupNameRef Name of the solid mechan-
sName ics statistics

XML Element: SinglePhaseReservoirPoromechanicsInitialization

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
poromechanicsSolver- groupNameRef required Name of the poromechan-
Name ics solver
solidMechanicsStatistic- groupNameRef Name of the solid mechan-
sName ics statistics

1.9. Datastructure Index 823

GEOS Documentation

XML Element: SinglePhaseStatistics

Name Type Default Description

flowSolverName groupNameRef required Name of the flow solver
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Print statistics

name groupName required A name is required for any

non-unique nodes
writeCSV integer 0 Write statistics into a CSV
file

XML Element: SinglePhaseThermalConductivity

Name Type De- Description

824 Chapter 1. Table of Contents

GEOS Documentation

XML Element: SinglePhaseWell

Name Type Default Description

allowNegativePressure integer 1 Flag indicating if negative
pressure is allowed
cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isThermal integer 0 Flag indicating whether
the problem is thermal or
not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Well control
information
- Crossflow
information
2
- The summary of
declared fields and
coupling
1.9. Datastructure Index 825
name groupName required A name is required for any
non-unique nodes
targetRegions groupNameRef_array required Allowable regions that the
GEOS Documentation

XML Element: SlipDependentPermeability

Name Type Default Description

XML Element: SolidInternalEnergy

Name Type De- Description

XML Element: SolidMechanicsStateReset

Name Type Default Description

disableInelasticity integer 0 Flag to enable/disable in-
elastic behavior
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Initialization
information

name groupName required A name is required for any

non-unique nodes
resetDisplacements integer 1 Flag to reset displace-
ments (and velocities)
solidSolverName groupNameRef required Name of the solid mechan-
ics solver

XML Element: SolidMechanicsStatistics

Name Type Default Description

name groupName required A name is required for any

XML Element: SoloEvent

Name Type De- Description

XML Element: Solvers

Name Type Default Description

gravityVector R1Tensor {0,0,-9.81} Gravity vector used in the physics solvers
AcousticElasticSEM node XML Element: AcousticElasticSEM
AcousticFirstOrderSEM node XML Element: AcousticFirstOrderSEM
AcousticSEM node XML Element: AcousticSEM
AcousticVTISEM node XML Element: AcousticVTISEM
CompositionalMultiphaseFVM node XML Element: CompositionalMultiphaseFVM
CompositionalMultiphaseHybridFVM node XML Element: CompositionalMultiphaseHyb
CompositionalMultiphaseReservoir node XML Element: CompositionalMultiphaseRese
CompositionalMultiphaseReservoirPoromechanics node XML Element: CompositionalMultiphaseRese
CompositionalMultiphaseWell node XML Element: CompositionalMultiphaseWell
ElasticFirstOrderSEM node XML Element: ElasticFirstOrderSEM
ElasticSEM node XML Element: ElasticSEM
EmbeddedSurfaceGenerator node XML Element: EmbeddedSurfaceGenerator
FlowProppantTransport node XML Element: FlowProppantTransport
Hydrofracture node XML Element: Hydrofracture
LaplaceFEM node XML Element: LaplaceFEM

1.9. Datastructure Index 841

XML Element: SurfaceGenerator

Name Type Default Description

cflFactor real64 0.5 Factor to apply to the CFL
condition when calculat-
ing the maximum allow-
able time step. Values
should be in the interval
(0,1]
fractureRegion groupNameRef Fracture (no description available)
initialDt real64 1e+99 Initial time-step value re-
quired by the solver to the
event manager.
isPoroelastic integer 0 Flag that defines whether
the material is poroelastic
or not.
logLevel integer 0
Sets the level of
information to write in the
standard output (the
console typically).
Level 0 outputs no
specific information for
this solver. Higher levels
require more outputs.
1
- Line search
information
- Solution
information
(scaling, maximum
changes, quality
check)
- Convergence
information
- Time step
information
- Linear solver
information
- Nonlinear solver
information
- Solver timers
information
- Fracture
generation
information
2
- The summary of
declared fields and
coupling
- Mapping
information
1.9. Datastructure Index 3 845
- Rupture rate
information
GEOS Documentation

XML Element: SymbolicFunction

Name Type De- Description

846 Chapter 1. Table of Contents

GEOS Documentation

XML Element: TableCapillaryPressure

Name Type Default Description

phaseNames groupNameRef_array required List of fluid phases

1.9. Datastructure Index 847

GEOS Documentation

XML Element: TableFunction

Name Type Default Description

name groupName required A name is required for any

non-unique nodes
values real64_array {0} Values for 1D tables
voxelFile path Voxel file name for ND Ta-
ble

848 Chapter 1. Table of Contents

GEOS Documentation

XML Element: TableRelativePermeability

Name Type Default Description

phaseNames groupNameRef_array required List of fluid phases

threePhaseInterpolator geos_constitutive_ThreePhaseInterpolator
BAKER
Type of Three phase
interpolator.Valid options
* BAKER
* STONEII

wettingIntermedi- groupNameRef_array {}
ateRelPermTableNames
List of relative
permeability tables for the
pair (wetting phase,
intermediate phase)
The expected format is “{
wetting-
PhaseRelPermTable-
Name,
intermedi-
atePhaseRelPermTable-
Name }”, in that order
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
wettingNonWettin-
gRelPermTableNames to
1.9. Datastructure Index specify the table names 849

wettingNonWettin- groupNameRef_array {}
gRelPermTableNames
GEOS Documentation

850 Chapter 1. Table of Contents

GEOS Documentation

XML Element: TableRelativePermeabilityHysteresis

Name Type Default Description

drainageNonWettingIn- groupNameRef_array {}
termediateRelPermTable-
List of drainage relative
Names
permeability tables for the
pair (non-wetting phase,
intermediate phase)
The expected format is “{
nonWetting-
PhaseRelPermTable-
Name,
intermedi-
atePhaseRelPermTable-
Name }”, in that order
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
drainageWettingNonWet-
tingRelPermTableNames
to specify the table names

drainageWettingInterme- groupNameRef_array {}
diateRelPermTableNames
List of drainage relative
permeability tables for the
pair (wetting phase,
intermediate phase)
The expected format is “{
wetting-
PhaseRelPermTable-
Name,
intermedi-
atePhaseRelPermTable-
Name }”, in that order
Note that this input is only
used for three-phase flow.
If you want to do a
two-phase simulation,
please use instead
drainageWettingNonWet-
tingRelPermTableNames
to specify the table names

bcApplicationTableName groupNameRef Name of table that speci-
fies the on/off application
of the boundary condition.
beginTime real64 -1e+99 Time at which the bound-
ary condition will start be-
ing applied.
direction R1Tensor {0,0,0} Direction to apply bound-
ary condition to.
endTime real64 1e+99 Time at which the bound-
ary condition will stop be-
ing applied.
functionName groupNameRef Name of function that
specifies variation of the
boundary condition.
initialCondition integer 0 Boundary condition is ap-
plied as an initial condi-
tion.
inputStress R2SymTensor {0,0,0,0,0,0} Input stress for traction-
Type = stress
logLevel integer 0 Log level
name groupName required A name is required for any
non-unique nodes
objectPath groupNameRef Path to the target field
scale real64 0 Scale factor for value of
the boundary condition.
setNames groupNameRef_array required Name of sets that bound-
ary condition is applied to.
tractionType geos_TractionBoundaryCondition_TractionType
vector
Type of traction boundary
condition. Options are:
vector - traction is applied
to the faces as specified
from the scale and
direction,
normal - traction is
applied to the faces as a
pressure specified from
the product of scale and
the outward face normal,
stress - traction is applied
to the faces as specified by
the inner product of input
stress and face normal.

1.9. Datastructure Index 855

GEOS Documentation

XML Element: TriaxialDriver

Name Type De- Description

XML Element: TwoPointFluxApproximation

Name Type Default Description

areaRelTol real64 1e-08 Relative tolerance for area
calculations.
meanPermCoefficient real64 1 (no description available)
name groupName required A name is required for any
non-unique nodes
upwindingScheme geos_UpwindingScheme PPU
Type of upwinding
scheme. Valid options:
* PPU
* C1PPU
* IHU

usePEDFM integer 0 (no description available)

856 Chapter 1. Table of Contents

GEOS Documentation

XML Element: VTK

Name Type De- Description

XML Element: VTKHierarchicalDataSource

Name Type Default Description

file groupNameRef required Path to the mesh file
name groupName required A name is required for any non-unique nodes
VTKHierarchicalDataSource node XML Element: VTKHierarchicalDataSource

1.9. Datastructure Index 857

GEOS Documentation

XML Element: VTKMesh

Name Type De- Description

fault
data- string Name of the VTK data source
Source-
Name
face- group- {} For multi-block files, names of the face mesh block.
Blocks NameRef_array
field- group- {} Names of the volumic fields in GEOS to import into
NamesIn-NameRef_array
GEOS
field- group- {} Volumic fields to be imported from the external mesh file
sToIm- NameRef_array
port
file path Path to the mesh file
logLevelinte- 0 Log level
ger
main- group- main For multi-block files, name of the 3d mesh block.
Block- NameRef
Name
name group- re- A name is required for any non-unique nodes
Name quired
node- group- {} Names of the VTK nodesets to import
set- NameRef_array
Names
par- geos_vtk_PartitionMethod
parmetis
Method (library) used to partition the mesh
ti-
tion-
Method
par- inte- 1 Number of partitioning refinement iterations (defaults to 1, recommended value).A value of
ti- ger 0 disables graph partitioning and keeps simple kd-tree partitions (not recommended). Values
tion- higher than 1 may lead to slightly improved partitioning, but yield diminishing returns.
Re-
fine-
ment
re- group- at- Name of the VTK cell attribute to use as region marker
gion- NameReftribute
At-
tribute
scale R1Tensor{1,1,1}Scale the coordinates of the vertices by given scale factors (after translation)
sur- group- {} Names of the surfacic fields in GEOS to import into
faci- NameRef_array
c-
Field-
sIn-
GEOS
sur- group- {} Surfacic fields to be imported from the external mesh file
faci- NameRef_array
c-
Field-
sToIm-
port
trans- R1Tensor{0,0,0}Translate the coordinates of the vertices by a given vector (prior to scaling)
late
use- inte-
858 0 Controls the use of global IDs in the input file for cells andChapter
points. If 1.
set to 0 (default
Table value),
of Contents
Glob- ger the GlobalId arrays in the input mesh are used if available, and generated otherwise. If set to
alIds a negative value, the GlobalId arrays in the input mesh are not used, and generated global Ids
are automatically generated. If set to a positive value, the GlobalId arrays in the input mesh
GEOS Documentation

XML Element: VTKWell

Name Type De- Description

fault
file path re- Path to the well file
quired
minEle- real64 0.001 Minimum length of a well element, computed as (segment length / number
mentLength of elements per segment ) [m]
minSeg- real64 0.01 Minimum length of a well segment [m]
mentLength
name group- re- A name is required for any non-unique nodes
Name quired
numEle- integer re- Number of well elements per polyline segment
mentsPerSeg- quired
ment
radius real64 re- Radius of the well [m]
quired
wellControl- string re- Name of the set of constraints associated with this well
sName quired
wellRegionName string re- Name of the well element region
quired
Perforation node XML Element: Perforation

1.9. Datastructure Index 859

GEOS Documentation

XML Element: VanGenuchtenBakerRelativePermeability

Name Type Default Description

gasOilRelPermExpo- real64_array {0.5}
nentInv
Rel perm power law
exponent inverse for the
pair (gas phase, oil phase)
at residual water
saturation
The expected format is “{
gasExp, oilExp }”, in that
order

gasOilRelPermMaxValue real64_array {0}

Maximum rel perm value
for the pair (gas phase, oil
phase) at residual water
saturation
The expected format is “{
gasMax, oilMax }”, in
that order

name groupName required A name is required for any

non-unique nodes
phaseMinVolumeFraction real64_array {0} Minimum volume fraction
value for each phase
phaseNames groupNameRef_array required List of fluid phases
waterOilRelPermExpo- real64_array {0.5}
nentInv
Rel perm power law
exponent inverse for the
pair (water phase, oil
phase) at residual gas
saturation
The expected format is “{
waterExp, oilExp }”, in
that order

waterOilRelPermMax- real64_array {0}

Value
Maximum rel perm value
for the pair (water phase,
oil phase) at residual gas
saturation
The expected format is “{
waterMax, oilMax }”, in
that order

860 Chapter 1. Table of Contents

GEOS Documentation

XML Element: VanGenuchtenCapillaryPressure

Name Type De- Description

1.9. Datastructure Index 861

GEOS Documentation

XML Element: VanGenuchtenStone2RelativePermeability

Name Type Default Description

gasOilRelPermMaxValue real64_array {0}

Maximum rel perm value
for the pair (gas phase, oil
phase) at residual water
saturation
The expected format is “{
gasMax, oilMax }”, in
that order

name groupName required A name is required for any

non-unique nodes
phaseMinVolumeFraction real64_array {0} Minimum volume fraction
value for each phase
phaseNames groupNameRef_array required List of fluid phases
waterOilRelPermExpo- real64_array {0.5}
nentInv
Rel perm power law
exponent inverse for the
pair (water phase, oil
phase) at residual gas
saturation
The expected format is “{
waterExp, oilExp }”, in
that order

waterOilRelPermMax- real64_array {0}

Value
Maximum rel perm value
for the pair (water phase,
oil phase) at residual gas
saturation
The expected format is “{
waterMax, oilMax }”, in
that order

862 Chapter 1. Table of Contents

GEOS Documentation

XML Element: ViscoDruckerPrager

Name Type De- Description

XML Element: ViscoExtendedDruckerPrager

Name Type De- Description

fault
defaultBulkModulus real64 -1 Default Bulk Modulus Parameter
defaultCohesion real64 0 Initial cohesion
defaultDensity real64 re- Default Material Density
quired
defaultDilationRatio real64 1 Dilation ratio [0,1] (ratio = tan dilationAngle / tan frictionAn-
gle)
defaultDrainedLin- real64 0 Default Linear Thermal Expansion Coefficient of the Solid
earTEC Rock Frame
defaultHardening real64 0 Hardening parameter (hardening rate is faster for smaller val-
ues)
defaultInitialFrictionAn- real64 30 Initial friction angle (degrees)
gle
defaultPoissonRatio real64 -1 Default Poisson’s Ratio
defaultResidualFrictio- real64 30 Residual friction angle (degrees)
nAngle
defaultShearModulus real64 -1 Default Shear Modulus Parameter
defaultYoungModulus real64 -1 Default Young’s Modulus
name group- re- A name is required for any non-unique nodes
Name quired
relaxationTime real64 re- Relaxation time
quired

1.9. Datastructure Index 863

XML Element: quartz

Name Type Default Description

Run node unique XML Element: Run

Name Type Description

876 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: CO2BrineEzrokhiFluid

Name Type Description

dPhaseC- LvArray_Array<double, 5, Derivative of phase component fraction with respect
ompFrac- camp_int_seq<long, 0l, 1l, 2l, 3l, 4l>, to pressure, temperature, and global component frac-
tion int, LvArray_ChaiBuffer> tions
dPhaseDen- real64_array4d Derivative of phase density with respect to pressure,
sity temperature, and global component fractions
dPhaseEn- real64_array4d Derivative of phase enthalpy with respect to pressure,
thalpy temperature, and global component fractions
dPhase- real64_array4d Derivative of phase fraction with respect to pressure,
Fraction temperature, and global component fractions
dPhaseIn- real64_array4d Derivative of phase internal energy with respect to
ternalEn- pressure, temperature, and global component frac-
ergy tions
dPhase- real64_array4d Derivative of phase mass density with respect to pres-
MassDen- sure, temperature, and global component fractions
sity
dPhaseVis- real64_array4d Derivative of phase viscosity with respect to pressure,
cosity temperature, and global component fractions
dTo- real64_array3d Derivative of total density with respect to pressure,
talDensity temperature, and global component fractions
phaseC- real64_array4d Phase component fraction
ompFrac-
tion
phaseC- real64_array4d Phase component fraction at the previous converged
ompFrac- time step
tion_n
phaseDen- real64_array3d Phase density
sity
phaseDen- real64_array3d Phase density at the previous converged time step
sity_n
phaseEn- real64_array3d Phase enthalpy
thalpy
phaseEn- real64_array3d Phase enthalpy at the previous converged time step
thalpy_n
phaseFrac- real64_array3d Phase fraction
tion
phaseInter- real64_array3d Phase internal energy
nalEnergy
phaseIn- real64_array3d Phase internal energy at the previous converged time
ternalEn- step
ergy_n
phase- real64_array3d Phase mass density
MassDen-
sity
phaseVis- real64_array3d Phase viscosity
cosity
totalDen- real64_array2d Total density
sity
totalDen- real64_array2d Total density at the previous converged time step
sity_n
useMass integer (no description available)

Datastructure: CompositionalMultiphaseFVM

Name Type Description

882 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: CompositionalMultiphaseFluid

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
per- integer Flag to indicate that the solver is going to per-
form- form stress initialization
StressIni-
tial-
iza-
tion
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

Datastructure: CompositionalMultiphaseReservoirPoromechanicsInitialization

Name Type Description

886 Chapter 1. Table of Contents

GEOS Documentation

dPhaseC- LvArray_Array<double, 5, Derivative of phase component fraction with respect
ompFrac- camp_int_seq<long, 0l, 1l, 2l, 3l, 4l>, to pressure, temperature, and global component frac-
tion int, LvArray_ChaiBuffer> tions
dPhaseDen- real64_array4d Derivative of phase density with respect to pressure,
sity temperature, and global component fractions
dPhaseEn- real64_array4d Derivative of phase enthalpy with respect to pressure,
thalpy temperature, and global component fractions
dPhase- real64_array4d Derivative of phase fraction with respect to pressure,
Fraction temperature, and global component fractions
dPhaseIn- real64_array4d Derivative of phase internal energy with respect to
ternalEn- pressure, temperature, and global component frac-
ergy tions
dPhase- real64_array4d Derivative of phase mass density with respect to pres-
MassDen- sure, temperature, and global component fractions
sity
dPhaseVis- real64_array4d Derivative of phase viscosity with respect to pressure,
cosity temperature, and global component fractions
dTo- real64_array3d Derivative of total density with respect to pressure,
talDensity temperature, and global component fractions
kValues real64_array4d Phase equilibrium ratios
phaseC- real64_array4d Phase component fraction
ompFrac-
tion
phaseC- real64_array4d Phase component fraction at the previous converged
ompFrac- time step
tion_n
phaseDen- real64_array3d Phase density
sity
phaseDen- real64_array3d Phase density at the previous converged time step
sity_n
phaseEn- real64_array3d Phase enthalpy
thalpy
phaseEn- real64_array3d Phase enthalpy at the previous converged time step
thalpy_n
phaseFrac- real64_array3d Phase fraction
tion
phaseInter- real64_array3d Phase internal energy
nalEnergy
phaseIn- real64_array3d Phase internal energy at the previous converged time
ternalEn- step
ergy_n
phase- real64_array3d Phase mass density
MassDen-
sity
phase- integer_array (no description available)
Order
phaseVis- real64_array3d Phase viscosity
cosity
totalDen- real64_array2d Total density
sity
totalDen- real64_array2d Total density at the previous converged time step
sity_n
useMass
1.9. integer Index
Datastructure (no description available) 893
GEOS Documentation

Datastructure: CompressibleSinglePhaseFluid

Name Type Description

dDensity_dPressure real64_array2d Derivative of density with respect to pressure
dDensity_dTemperature real64_array2d Derivative of density with respect to temperature
dEnthalpy_dPressure real64_array2d Derivative of enthalpy with respect to pressure
dEnthalpy_dTemperature real64_array2d Derivative of enthalpy with respect to temperature
dInternalEnergy_dPressure real64_array2d Derivative of internal energy with respect to pressure
dInternalEnergy_dTemperature real64_array2d Derivative of internal energy with respect to temperature
dViscosity_dPressure real64_array2d Derivative of viscosity with respect to pressure
dViscosity_dTemperature real64_array2d Derivative of viscosity with respect to temperature
density real64_array2d Density
density_n real64_array2d Density at the previous converged time step
enthalpy real64_array2d Enthalpy
internalEnergy real64_array2d Internal energy
internalEnergy_n real64_array2d Fluid internal energy at the previous converged step
viscosity real64_array2d Viscosity

Datastructure: CompressibleSolidCarmanKozenyPermeability

Name Type Description

Datastructure: CompressibleSolidConstantPermeability

Datastructure: ConstantPermeability

Name Type Description

dPerm_dPressure real64_array3d Derivative of rock permeability with respect to pressure
permeability real64_array3d Rock permeability

Datastructure: Constitutive

Name Type Description

BiotPorosity node Datastructure: BiotPorosity
BlackOilFluid node Datastructure: BlackOilFluid
BrooksCoreyBakerRelativePermeability node Datastructure: BrooksCoreyBakerRelativePermeability
BrooksCoreyCapillaryPressure node Datastructure: BrooksCoreyCapillaryPressure
BrooksCoreyRelativePermeability node Datastructure: BrooksCoreyRelativePermeability
BrooksCoreyStone2RelativePermeability node Datastructure: BrooksCoreyStone2RelativePermeability
CO2BrineEzrokhiFluid node Datastructure: CO2BrineEzrokhiFluid
CO2BrineEzrokhiThermalFluid node Datastructure: CO2BrineEzrokhiThermalFluid
CO2BrinePhillipsFluid node Datastructure: CO2BrinePhillipsFluid
CO2BrinePhillipsThermalFluid node Datastructure: CO2BrinePhillipsThermalFluid
CarmanKozenyPermeability node Datastructure: CarmanKozenyPermeability
CeramicDamage node Datastructure: CeramicDamage
CompositionalMultiphaseFluid node Datastructure: CompositionalMultiphaseFluid
CompositionalThreePhaseFluidLohrenzBrayClark node Datastructure: CompositionalThreePhaseFluidLohrenzBrayClark
CompositionalTwoPhaseFluid node Datastructure: CompositionalTwoPhaseFluid
CompositionalTwoPhaseFluidLohrenzBrayClark node Datastructure: CompositionalTwoPhaseFluidLohrenzBrayClark
CompressibleSinglePhaseFluid node Datastructure: CompressibleSinglePhaseFluid
CompressibleSolidCarmanKozenyPermeability node Datastructure: CompressibleSolidCarmanKozenyPermeability
CompressibleSolidConstantPermeability node Datastructure: CompressibleSolidConstantPermeability
continues on next page

1.9. Datastructure Index 895

GEOS Documentation

GEOS Documentation

Datastructure: ElasticIsotropicPressureDependent

Name Type Description

density real64_array2d Material Density
oldStress real64_array3d Previous Material Stress
recompressionIndex real64_array Recompression Index Field
refPressure real64 Reference Pressure Field
refStrainVol real64 Reference Volumetric Strain
shearModulus real64_array Elastic Shear Modulus
stress real64_array3d Current Material Stress
thermalExpansionCoefficient real64_array Linear Thermal Expansion Coefficient Field

Datastructure: ElasticOrthotropic

Name Type Description

c11 real64_array Elastic Stiffness Field C11
c12 real64_array Elastic Stiffness Field C12
c13 real64_array Elastic Stiffness Field C13
c22 real64_array Elastic Stiffness Field C22
c23 real64_array Elastic Stiffness Field C23
c33 real64_array Elastic Stiffness Field C33
c44 real64_array Elastic Stiffness Field C44
c55 real64_array Elastic Stiffness Field C55
c66 real64_array Elastic Stiffness Field C66
density real64_array2d Material Density
oldStress real64_array3d Previous Material Stress
stress real64_array3d Current Material Stress
thermalExpansionCoefficient real64_array Linear Thermal Expansion Coefficient Field

902 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: ElasticSEM

Name Type Description

dasSig- real32_array2d DAS signal value at
nalNp1AtReceivers each receiver for each
timestep
dis- real32_array2d Displacement value at
place- each receiver for each
men- timestep (x-component)
tXNp1AtReceivers
dis- real32_array2d Displacement value at
place- each receiver for each
men- timestep (y-component)
tYNp1AtReceivers
dis- real32_array2d Displacement value at
place- each receiver for each
mentZNp1AtReceivers timestep (z-component)
in- integer Count for output pres-
dex- sure at receivers
Seis-
mo-
Trace
lin- real32_array X component of the lin-
ear- ear DAS direction vec-
DASVec- tor
torX
lin- real32_array Y component of the lin-
ear- ear DAS direction vec-
DASVec- tor
torY
lin- real32_array Z component of the lin-
ear- ear DAS direction vec-
DASVec- tor
torZ
maxStableDt
real64 Value of the Maximum
Stable Timestep for this
solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region
gets std___1_char_traits<char>, std___1_allocator<char>>, combinations that the
std___1_basic_string<char, std___1_char_traits<char>, solver will be applied
std___1_allocator<char>>>, LvArray_Array<std___1_basic_string<char, to.
std___1_char_traits<char>, std___1_allocator<char>>, 1, camp_int_seq<long,
0l>, int, LvArray_ChaiBuffer>, std___1_integral_constant<bool, true>>
re- real64_array2d Constant part of
ceiver- the receiver for
Con- the nodes listed in
stants m_receiverNodeIds
re- integer_array Element containing the
ceiverElem receivers
re- integer_array Flag that indicates
ceiverIs- whether the receiver is
Local local to this MPI rank
re- integer_array2d Indices of the nodes (in
ceiverN- the right order) for each
odeIds receiver point
re- Datastructure
1.9. integer_arrayIndex Region containing the 903
ceiver- receivers
Re-
gion
GEOS Documentation

Datastructure: ElasticTransverseIsotropic

Name Type Description

c11 real64_array Elastic Stiffness Field C11
c13 real64_array Elastic Stiffness Field C13
c33 real64_array Elastic Stiffness Field C33
c44 real64_array Elastic Stiffness Field C44
c66 real64_array Elastic Stiffness Field C66
density real64_array2d Material Density
oldStress real64_array3d Previous Material Stress
stress real64_array3d Current Material Stress
thermalExpansionCoefficient real64_array Linear Thermal Expansion Coefficient Field

Datastructure: ElementRegions

Name Type Description

904 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: EmbeddedSurfaceGenerator

Name Type Regis- Description

tered On
maxStableDt
real64 Value of
the Maxi-
mum Stable
Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, Mesh-
gets std___1_char_traits<char>, std___1_allocator<char>>, Body/Region
std___1_basic_string<char, std___1_char_traits<char>, combina-
std___1_allocator<char>>>, LvArray_Array<std___1_basic_string<char, tions that the
std___1_char_traits<char>, std___1_allocator<char>>, solver will
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>, be applied
std___1_integral_constant<bool, true>> to.
par- integer_array Datas- Index of
ent- tructure: parent edge
EdgeIn- embed- within the
dex dedSur- mesh object
facesNode- it is regis-
Manager tered on.
Lin- node Datas-
ear- tructure:
Solver- Linear-
Pa- SolverPa-
ram- rameters
eters
Non- node Datas-
lin- tructure:
ear- Nonlinear-
Solver- SolverPa-
Pa- rameters
ram-
eters
Solver- node Datas-
Statis- tructure:
tics SolverStatis-
tics

Datastructure: Events

Name Type Description

currentSubEvent integer Index of the current subevent.
cycle integer Current simulation cycle number.
dt real64 Current simulation timestep.
time real64 Current simulation time.
HaltEvent node Datastructure: HaltEvent
PeriodicEvent node Datastructure: PeriodicEvent
SoloEvent node Datastructure: SoloEvent

1.9. Datastructure Index 905

GEOS Documentation

Datastructure: ExponentialDecayPermeability

Name Type Description

dPerm_dDispJump real64_array4d Derivative of rock permeability with respect to displacement jump
dPerm_dPressure real64_array3d Derivative of rock permeability with respect to pressure
dPerm_dTraction real64_array4d Derivative of rock permeability with respect to the traction vector
permeability real64_array3d Rock permeability

Datastructure: ExtendedDruckerPrager

Name Type Description

bulkModulus real64_array Elastic Bulk Modulus Field
density real64_array2d Material Density
dilationRatio real64_array Plastic potential slope ratio
hardening real64_array Hardening parameter
initialFriction real64_array Initial yield surface slope
oldStateVariable real64_array2d Old equivalent plastic shear strain
oldStress real64_array3d Previous Material Stress
pressureIntercept real64_array Pressure point at cone vertex
residualFriction real64_array Residual yield surface slope
shearModulus real64_array Elastic Shear Modulus Field
stateVariable real64_array2d New equivalent plastic shear strain
stress real64_array3d Current Material Stress
thermalExpansionCoefficient real64_array Linear Thermal Expansion Coefficient Field

Datastructure: ExternalDataSource

Name Type Description

VTKHierarchicalDataSource node Datastructure: VTKHierarchicalDataSource

Datastructure: FieldSpecification

Name Type Description

Datastructure: FieldSpecifications

Name Type Description

Aquifer node Datastructure: Aquifer
Dirichlet node Datastructure: Dirichlet
FieldSpecification node Datastructure: FieldSpecification
HydrostaticEquilibrium node Datastructure: HydrostaticEquilibrium
PML node Datastructure: PML
SourceFlux node Datastructure: SourceFlux
Traction node Datastructure: Traction

906 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: File

Datastructure: HydrostaticEquilibrium

Name Type Description

component integer Component of field (if tensor) to apply boundary condition to.
fieldName groupNameRef Name of field that boundary condition is applied to.
initialCondition integer Boundary condition is applied as an initial condition.
setNames groupNameRef_array Name of sets that boundary condition is applied to.

Datastructure: Included

Name Type Description

File node Datastructure: File

Datastructure: InternalMesh

Name Type Description

InternalWell node Datastructure: InternalWell
Region node Datastructure: Region
VTKWell node Datastructure: VTKWell
meshLevels node Datastructure: meshLevels

Datastructure: InternalWell

Name Type Description

Perforation node Datastructure: Perforation

Datastructure: InternalWellbore

Name Type Description

nx integer_array Number of elements in the x-direction within each mesh block
ny integer_array Number of elements in the y-direction within each mesh block
xCoords real64_array x-coordinates of each mesh block vertex
yCoords real64_array y-coordinates of each mesh block vertex
InternalWell node Datastructure: InternalWell
Region node Datastructure: Region
VTKWell node Datastructure: VTKWell
meshLevels node Datastructure: meshLevels

1.9. Datastructure Index 911

GEOS Documentation

Datastructure: JFunctionCapillaryPressure

Name Type Description

dPhaseCapPres- real64_array4d Derivative of phase capillary pres-
sure_dPhaseVolFraction sure with respect to phase volume
fraction
jFuncMultiplier real64_array2d Multiplier for the Leverett J-function
jFunctionWrap- LvArray_Array<geos_TableFunction_KernelWrapper, (no description available)
pers 1, camp_int_seq<long, 0l>, int, LvAr-
ray_ChaiBuffer>
phaseCapPressure real64_array3d Phase capillary pressure
phaseOrder integer_array (no description available)
phaseTypes integer_array (no description available)

Datastructure: LaplaceFEM

Name Type Description

912 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: Level0

Name Type Description

meshLevel integer (no description available)
ElementRegions node Datastructure: ElementRegions
ParticleRegions node Datastructure: ParticleRegions
edgeManager node Datastructure: edgeManager
embeddedSurfacesEdgeManager node Datastructure: embeddedSurfacesEdgeManager
embeddedSurfacesNodeManager node Datastructure: embeddedSurfacesNodeManager
faceManager node Datastructure: faceManager
nodeManager node Datastructure: nodeManager

cslSlope real64_array Slope of the critical state line
density real64_array2d Material Density
oldPreConsolidationPressure real64_array2d Old preconsolidation pressure
oldStress real64_array3d Previous Material Stress
preConsolidationPressure real64_array2d New preconsolidation pressure
recompressionIndex real64_array Recompression Index Field
refPressure real64 Reference Pressure Field
refStrainVol real64 Reference Volumetric Strain
shearModulus real64_array Elastic Shear Modulus
stress real64_array3d Current Material Stress
thermalExpansionCoefficient real64_array Linear Thermal Expansion Coefficient Field
virginCompressionIndex real64_array Virgin compression index

Datastructure: MultiPhaseConstantThermalConductivity

Name Type Description

dEffectiveConductiv- real64_array4d Derivative of effective conductivity with respect to phase vol-
ity_dPhaseVolFraction ume fraction
effectiveConductivity real64_array3d Effective conductivity

Datastructure: MultiPhaseVolumeWeightedThermalConductivity

Name Type Description

dEffectiveConductiv- real64_array4d Derivative of effective conductivity with respect to phase vol-
ity_dPhaseVolFraction ume fraction
effectiveConductivity real64_array3d Effective conductivity
rockThermalConductivity real64_array3d Rock thermal conductivity

914 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: MultiphasePoromechanics

Name Type Description

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
per- integer Flag to indicate that the solver is going to per-
form- form stress initialization
StressIni-
tial-
iza-
tion
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

Datastructure: MultiphasePoromechanicsInitialization

Name Type Description

1.9. Datastructure Index 915

GEOS Documentation

Datastructure: MultiphasePoromechanicsReservoir

Name Type Description

Datastructure: MultivariableTableFunction

Name Type Description

916 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: NonlinearSolverParameters

Name Type Description

newtonNumberOfIterations integer Number of Newton’s iterations.
normType geos_physicsSolverBaseKernels_NormType
Norm used by the flow solver to
check nonlinear convergence. Valid
options:
* Linfinity
* L2

Datastructure: NullModel

Name Type Description

Datastructure: NumericalMethods

Name Type Description

FiniteElements node Datastructure: FiniteElements
FiniteVolume node Datastructure: FiniteVolume

Datastructure: Outputs

Name Type Description

Blueprint node Datastructure: Blueprint
ChomboIO node Datastructure: ChomboIO
Python node Datastructure: Python
Restart node Datastructure: Restart
Silo node Datastructure: Silo
TimeHistory node Datastructure: TimeHistory
VTK node Datastructure: VTK

Datastructure: PML

Name Type Description

fieldName groupNameRef Name of field that boundary condition is applied to.
initialCondition integer Boundary condition is applied as an initial condition.

Datastructure: PVTDriver

Name Type Description

1.9. Datastructure Index 917

GEOS Documentation

Datastructure: PackCollection

Name Type Description

Datastructure: ParallelPlatesPermeability

Name Type Description

Datastructure: Parameter

Name Type Description

Datastructure: Parameters

Name Type Description

Parameter node Datastructure: Parameter

922 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: PorousViscoDruckerPrager

Name Type Description

Datastructure: PorousViscoExtendedDruckerPrager

Name Type Description

Datastructure: PorousViscoModifiedCamClay

Name Type Description

Datastructure: PressurePermeability

Name Type Description

dPerm_dPressure real64_array3d Derivative of rock permeability with respect to pressure
permeability real64_array3d Rock permeability
referencePermeability real64_array3d Reference permeability field

Datastructure: PressurePorosity

Name Type Description

dPorosity_dPressure real64_array2d Derivative of rock porosity with respect to pressure
dPorosity_dTemperature real64_array2d Derivative of rock porosity with respect to temperature
initialPorosity real64_array2d Initial porosity
porosity real64_array2d Rock porosity
porosity_n real64_array2d Rock porosity at the previous converged time step
referencePorosity real64_array Reference porosity

1.9. Datastructure Index 923

Name Type Description

926 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: QuasiDynamicEQ

Name Type Description

1.9. Datastructure Index 927

GEOS Documentation

Datastructure: QuasiDynamicEQRK32

Name Type Description

Datastructure: RateAndStateFriction

Name Type Description

Dc real64_array Rate- and State-dependent friction characteristic length.
a real64_array Rate- and State-dependent friction coefficient a.
b real64_array Rate- and State-dependent friction coefficient b.
frictionCoefficient real64_array Friction coefficient
referenceFrictionCoefficient real64_array Rate- and State-dependent friction reference friction coefficient.
referenceVelocity real64_array Rate- and State-dependent friction reference slip rate.

928 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: ReactiveBrine

Name Type Description

dPhaseC- LvArray_Array<double, 5, Derivative of phase component fraction with re-
ompFraction camp_int_seq<long, 0l, 1l, 2l, 3l, 4l>, int, spect to pressure, temperature, and global compo-
LvArray_ChaiBuffer> nent fractions
dPhaseDensity real64_array4d Derivative of phase density with respect to pres-
sure, temperature, and global component fractions
dPhaseEn- real64_array4d Derivative of phase enthalpy with respect to pres-
thalpy sure, temperature, and global component fractions
dPhaseFraction real64_array4d Derivative of phase fraction with respect to pres-
sure, temperature, and global component fractions
dPhaseInter- real64_array4d Derivative of phase internal energy with respect to
nalEnergy pressure, temperature, and global component frac-
tions
dPhaseMass- real64_array4d Derivative of phase mass density with respect to
Density pressure, temperature, and global component frac-
tions
dPhaseViscos- real64_array4d Derivative of phase viscosity with respect to pres-
ity sure, temperature, and global component fractions
dTotalDensity real64_array3d Derivative of total density with respect to pressure,
temperature, and global component fractions
kineticReac- real64_array2d kineticReactionRates
tionRates
phaseC- real64_array4d Phase component fraction
ompFraction
phaseC- real64_array4d Phase component fraction at the previous con-
ompFraction_n verged time step
phaseDensity real64_array3d Phase density
phaseDen- real64_array3d Phase density at the previous converged time step
sity_n
phaseEnthalpy real64_array3d Phase enthalpy
phaseEn- real64_array3d Phase enthalpy at the previous converged time step
thalpy_n
phaseFraction real64_array3d Phase fraction
phaseInter- real64_array3d Phase internal energy
nalEnergy
phaseInter- real64_array3d Phase internal energy at the previous converged
nalEnergy_n time step
phaseMass- real64_array3d Phase mass density
Density
phaseViscosity real64_array3d Phase viscosity
primarySpeci- real64_array2d primarySpeciesConcentration
esConcentra-
tion
prima- real64_array2d primarySpeciesTotalConcentration
rySpeciesTotal-
Concentration
sec- real64_array2d secondarySpeciesConcentration
ondarySpeci-
esConcentra-
tion
totalDensity real64_array2d Total density
totalDensity_n real64_array2d Total density at the previous converged time step
useMass integer (no description available)
1.9. Datastructure Index 929
GEOS Documentation

930 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: ReactiveBrineThermal

Name Type Description

dPhaseC- LvArray_Array<double, 5, Derivative of phase component fraction with re-
ompFraction camp_int_seq<long, 0l, 1l, 2l, 3l, 4l>, int, spect to pressure, temperature, and global compo-
LvArray_ChaiBuffer> nent fractions
dPhaseDensity real64_array4d Derivative of phase density with respect to pres-
sure, temperature, and global component fractions
dPhaseEn- real64_array4d Derivative of phase enthalpy with respect to pres-
thalpy sure, temperature, and global component fractions
dPhaseFraction real64_array4d Derivative of phase fraction with respect to pres-
sure, temperature, and global component fractions
dPhaseInter- real64_array4d Derivative of phase internal energy with respect to
nalEnergy pressure, temperature, and global component frac-
tions
dPhaseMass- real64_array4d Derivative of phase mass density with respect to
Density pressure, temperature, and global component frac-
tions
dPhaseViscos- real64_array4d Derivative of phase viscosity with respect to pres-
ity sure, temperature, and global component fractions
dTotalDensity real64_array3d Derivative of total density with respect to pressure,
temperature, and global component fractions
kineticReac- real64_array2d kineticReactionRates
tionRates
phaseC- real64_array4d Phase component fraction
ompFraction
phaseC- real64_array4d Phase component fraction at the previous con-
ompFraction_n verged time step
phaseDensity real64_array3d Phase density
phaseDen- real64_array3d Phase density at the previous converged time step
sity_n
phaseEnthalpy real64_array3d Phase enthalpy
phaseEn- real64_array3d Phase enthalpy at the previous converged time step
thalpy_n
phaseFraction real64_array3d Phase fraction
phaseInter- real64_array3d Phase internal energy
nalEnergy
phaseInter- real64_array3d Phase internal energy at the previous converged
nalEnergy_n time step
phaseMass- real64_array3d Phase mass density
Density
phaseViscosity real64_array3d Phase viscosity
primarySpeci- real64_array2d primarySpeciesConcentration
esConcentra-
tion
prima- real64_array2d primarySpeciesTotalConcentration
rySpeciesTotal-
Concentration
sec- real64_array2d secondarySpeciesConcentration
ondarySpeci-
esConcentra-
tion
totalDensity real64_array2d Total density
totalDensity_n real64_array2d Total density at the previous converged time step
useMass integer (no description available)
1.9. Datastructure Index 931
GEOS Documentation

Datastructure: ReactiveCompositionalMultiphaseOBL

Name Type Description

934 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: SinglePhaseFVM

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
per- integer Flag to indicate that the solver is going to per-
form- form stress initialization
StressIni-
tial-
iza-
tion
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

Datastructure: SinglePhasePoromechanicsEmbeddedFracturesInitialization

Name Type Description

940 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: SinglePhasePoromechanicsInitialization

Name Type Description

Datastructure: SinglePhaseReservoirPoromechanics

Name Type Description

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
per- integer Flag to indicate that the solver is going to per-
form- form stress initialization
StressIni-
tial-
iza-
tion
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

944 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: SinglePhaseReservoirPoromechanicsConformingFractures

Name Type Description

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
per- integer Flag to indicate that the solver is going to per-
form- form stress initialization
StressIni-
tial-
iza-
tion
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

Datastructure: SinglePhaseReservoirPoromechanicsConformingFracturesInitialization

Name Type Description

1.9. Datastructure Index 945

GEOS Documentation

Datastructure: SinglePhaseReservoirPoromechanicsInitialization

Name Type Description

Datastructure: SinglePhaseStatistics

Name Type Description

Datastructure: SinglePhaseThermalConductivity

Name Type Description

dEffectiveConductivity_dT real64_array3d Derivative of effective conductivity w.r.t. temperature
effectiveConductivity real64_array3d Effective conductivity

946 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: SinglePhaseWell

Name Type Description

Datastructure: SlipDependentPermeability

Name Type Description

1.9. Datastructure Index 947

GEOS Documentation

Datastructure: SolidInternalEnergy

Name Type Description

dInternalEn- real64_array2d Derivative of the solid internal energy w.r.t. temperature [J/(m^3.K)]
ergy_dTemperature
internalEnergy real64_array2d Internal energy of the solid per unit volume [J/m^3]
internalEnergy_n real64_array2d Internal energy of the solid per unit volume at the previous time-step
[J/m^3]

948 Chapter 1. Table of Contents

Datastructure: SoloEvent

dis- groupNameRef Name of discretization object (defined in the
cretiza- Numerical Methods) to use for this solver. For
tion instance, if this is a Finite Element Solver, the
name of a Finite Element Discretization should
be specified. If this is a Finite Volume Method,
the name of a Finite Volume Discretization dis-
cretization should be specified.
fail- integer (no description available)
Cri-
te-
rion
maxStableDt
real64 Value of the Maximum Stable Timestep for
this solver.
meshTar-geos_mapBase<std___1_pair<std___1_basic_string<char, MeshBody/Region combinations that the
gets std___1_char_traits<char>, std___1_allocator<char>>, solver will be applied to.
std___1_basic_string<char, std___1_char_traits<char>,
std___1_allocator<char>>>, LvAr-
ray_Array<std___1_basic_string<char,
std___1_char_traits<char>, std___1_allocator<char>>,
1, camp_int_seq<long, 0l>, int, LvArray_ChaiBuffer>,
std___1_integral_constant<bool, true>>
tipEdgesLvArray_SortedArray<int, int, LvArray_ChaiBuffer> Set containing all the tip edges
tip- LvArray_SortedArray<int, int, LvArray_ChaiBuffer> Set containing all the tip faces
Faces
tipN- LvArray_SortedArray<int, int, LvArray_ChaiBuffer> Set containing all the nodes at the fracture tip
odes
trail- LvArray_SortedArray<int, int, LvArray_ChaiBuffer> Set containing all the trailing faces
ing-
Faces
Lin- node Datastructure: LinearSolverParameters
ear-
Solver-
Pa-
ram-
e-
ters
Non- node Datastructure: NonlinearSolverParameters
lin-
ear-
Solver-
Pa-
ram-
e-
ters
Solver-node Datastructure: SolverStatistics
Statis-
tics

1.9. Datastructure Index 959

GEOS Documentation

Datastructure: SymbolicFunction

Name Type Description

Datastructure: TableCapillaryPressure

Name Type Description

capPresWrappers LvArray_Array<geos_TableFunction_KernelWrapper, (no description available)
1, camp_int_seq<long, 0l>, int, LvAr-
ray_ChaiBuffer>
dPhaseCapPres- real64_array4d Derivative of phase capillary pres-
sure_dPhaseVolFraction sure with respect to phase volume
fraction
phaseCapPressure real64_array3d Phase capillary pressure
phaseOrder integer_array (no description available)
phaseTypes integer_array (no description available)

Datastructure: TableFunction

Name Type Description

Datastructure: TableRelativePermeability

Name Type Description

dPhaseRelPerm_dPhaseVolFraction
real64_array4d Derivative of phase relative permeabil-
ity with respect to phase volume frac-
tion
phaseMinVol- real64_array (no description available)
umeFraction
phaseOrder integer_array (no description available)
phaseRelPerm real64_array3d Phase relative permeability
phaseRelPerm_n real64_array3d Phase relative permeability at previous
time
phaseTrapped- real64_array3d Phase trapped volume fraction
VolFraction
phaseTypes integer_array (no description available)
relPermWrap- LvArray_Array<geos_TableFunction_KernelWrapper, (no description available)
pers 1, camp_int_seq<long, 0l>, int, LvAr-
ray_ChaiBuffer>
waterOil- real64 (no description available)
MaxRelPerm

960 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: TableRelativePermeabilityHysteresis

Name Type Description

dPhaseRelPerm_dPhaseVolFraction
real64_array4d Derivative of phase relative perme-
ability with respect to phase volume
fraction
drainagePhase- real64_array (no description available)
MaxVolumeFrac-
tion
drainagePhaseM- real64_array (no description available)
inVolumeFrac-
tion
drainagePhaseRelPer-real64_array (no description available)
mEndPoint
drainageRelPermWrap-
LvArray_Array<geos_TableFunction_KernelWrapper, (no description available)
pers 1, camp_int_seq<long, 0l>, int, LvAr-
ray_ChaiBuffer>
imbibitionPhase- real64_array (no description available)
MaxVolumeFrac-
tion
imbibition- real64_array (no description available)
PhaseMinVol-
umeFraction
imbibition- real64_array (no description available)
PhaseRelPermE-
ndPoint
imbibition- LvArray_Array<geos_TableFunction_KernelWrapper, (no description available)
RelPermWrap- 1, camp_int_seq<long, 0l>, int, LvAr-
pers ray_ChaiBuffer>
landParameter real64_array (no description available)
phaseHasHys- integer_array (no description available)
teresis
phaseMaxHistor- real64_array2d Phase max historical phase volume
icalVolFraction fraction
phaseMinHistori- real64_array2d Phase min historical phase volume
calVolFraction fraction
phaseOrder integer_array (no description available)
phaseRelPerm real64_array3d Phase relative permeability
phaseRelPerm_n real64_array3d Phase relative permeability at previous
time
phaseTrapped- real64_array3d Phase trapped volume fraction
VolFraction
phaseTypes integer_array (no description available)
waterOil- real64 (no description available)
MaxRelPerm

1.9. Datastructure Index 961

GEOS Documentation

Datastructure: Tasks

Name Type Description

CellToCellDataCollection node Datastructure: CellToCellDataCollection
CompositionalMultiphaseReservoirPorome- node Datastructure: CompositionalMultiphaseReservoir-
chanicsInitialization PoromechanicsInitialization
CompositionalMultiphaseStatistics node Datastructure: CompositionalMultiphaseStatistics
HydrofractureInitialization node Datastructure: HydrofractureInitialization
MultiphasePoromechanicsInitialization node Datastructure: MultiphasePoromechanicsInitialization
PVTDriver node Datastructure: PVTDriver
PackCollection node Datastructure: PackCollection
ReactiveFluidDriver node Datastructure: ReactiveFluidDriver
RelpermDriver node Datastructure: RelpermDriver
SinglePhasePoromechanicsConformingFrac- node Datastructure: SinglePhasePoromechanicsConform-
turesInitialization ingFracturesInitialization
SinglePhasePoromechanicsEmbeddedFrac- node Datastructure: SinglePhasePoromechanicsEmbedded-
turesInitialization FracturesInitialization
SinglePhasePoromechanicsInitialization node Datastructure: SinglePhasePoromechanicsInitialization
SinglePhaseReservoirPoromechanicsConform- node Datastructure: SinglePhaseReservoirPoromechanic-
ingFracturesInitialization sConformingFracturesInitialization
SinglePhaseReservoirPoromechanicsInitializa- node Datastructure: SinglePhaseReservoirPoromechanicsIni-
tion tialization
SinglePhaseStatistics node Datastructure: SinglePhaseStatistics
SolidMechanicsStateReset node Datastructure: SolidMechanicsStateReset
SolidMechanicsStatistics node Datastructure: SolidMechanicsStatistics
SourceFluxStatistics node Datastructure: SourceFluxStatistics
TriaxialDriver node Datastructure: TriaxialDriver

Datastructure: ThermalCompressibleSinglePhaseFluid

Name Type Description

962 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: ThickPlane

Name Type Description

Datastructure: TimeHistory

Name Type Description

restart inte- The current history record to be written, on restart from an earlier time allows use to remove invalid
ger future history.

Datastructure: Traction

Name Type Description

component integer Component of field (if tensor) to apply boundary condition to.
fieldName groupNameRef Name of field that boundary condition is applied to.

Datastructure: TriaxialDriver

Name Type Description

1.9. Datastructure Index 963

GEOS Documentation

Perforation node Datastructure: Perforation

Datastructure: VanGenuchtenBakerRelativePermeability

Name Type Description

Datastructure: VanGenuchtenCapillaryPressure

Name Type Description

1.9. Datastructure Index 965

GEOS Documentation

Datastructure: VanGenuchtenStone2RelativePermeability

Name Type Description

Datastructure: ViscoDruckerPrager

Name Type Description

Datastructure: ViscoExtendedDruckerPrager

Name Type Description

966 Chapter 1. Table of Contents

GEOS Documentation

Datastructure: ViscoModifiedCamClay

Name Type Description

GEOS Documentation

Datastructure: embeddedSurfacesEdgeManager

1.9. Datastructure Index 975

GEOS Documentation

Datastructure: wellElementSubRegion

Name Type Description

domainBound- integer_array (no description available)
aryIndicator
ghostRank integer_array (no description available)
globalToLo- geos_mapBase<long long, int, (no description available)
calMap std___1_integral_constant<bool, false>>
isExternal integer_array (no description available)
localMaxGlob- globalIndex (no description available)
alIndex
localToGlob- globalIndex_array Array that contains a map from localIndex to
alMap globalIndex.
location real64_array2d For each perforation, physical location (x,y,z
coordinates)
maxGlobalIndex globalIndex (no description available)
numPerforations- globalIndex (no description available)
Global
reservoirElement- globalIndex_array For each perforation, global element index of
GlobalIndex the perforated element
reservoirEle- integer_array For each perforation, element index of the per-
mentIndex forated element
reservoirElemen- integer_array For each perforation, elementRegion index of
tRegion the perforated element
reservoirEle- integer_array For each perforation, elementSubRegion in-
mentSubregion dex of the perforated element
wellElementIndex integer_array For each perforation, index of the well ele-
ment
wellSkinFactor real64_array For each perforation, well skin factor
wellTransmissi- real64_array For each perforation, well transmissibility
bility
neighborData node Datastructure: neighborData
sets node Datastructure: sets

1.10 Contributors
An up-to-date list of all GEOS contributors can be found on our Github page:
GEOS Contributors
The following is the list of GEOS contributors as of January 2019:

Managing reservoir dynamics when converting natural gas fields to underground hydrogen storage
JT Camargo, JA White, FP Hamon, V Fakeye, TA Buscheck, N Huerta
International Journal of Hydrogen Energy
doi.org/10.1016/j.ijhydene.2023.09.165

Constrained pressure-temperature residual (CPTR) preconditioner performance for large-scale thermal

CO2 injection simulation
MA Cremon, J Franc, FP Hamon
Computational Geosciences
doi.org/10.1007/s10596-024-10292-z

Surrogate model for geological CO2 storage and its use in hierarchical MCMC history matching
Y Han, FP Hamon, S Jiang, LJ Durlofsky
Advances in Water Resources
doi:10.1016/j.advwatres.2024.104678

Simulation of Multiphase Flow and Poromechanical Effects Around Injection Wells in CO2 Storage Sites
J Huang, F Hamon, M Cusini, T Gazzola, RR Settgast, JA White, H Gross
Rock Mechanics and Rock Engineering
doi:10.1007/s00603-024-04051-w

1.11. Publications 979

Multilevel well modeling in aggregation-based nonlinear multigrid for multiphase flow in porous media
CS Lee, FP Hamon, N Castelletto, PS Vassilevski, JA White
Journal of Computational Physics
GEOS Documentation

1.11.3 2023

A phase-field model for hydraulic fracture nucleation and propagation in porous media
F Fei, A Costa, JE Dolbow, R Settgast, M Cusini
International Journal for Numerical and Analytical Methods in Geomechanics
doi.org/10.1002/nag.3612

Validation and Application of a Three-Dimensional Model for Simulating Proppant Transport and
Fracture Conductivity
J Huang, Y Hao, RR Settgast, JA White, K Mateen, H Gross
Rock Mechanics and Rock Engineering
doi:10.1007/s00603-022-03092-3

980 Chapter 1. Table of Contents

GEOS Documentation

1.11. Publications 981

GEOS Documentation

1.11.4 2022

Smooth implicit hybrid upwinding for compositional multiphase flow in porous media
SBM Bosma, FP Hamon, BT Mallison, HA Tchelepi
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2021.114288

A Multi-resolution approach to hydraulic fracture simulation

A Costa, M Cusini, T Jin, R Settgast, JE Dolbow
International Journal of Fracture
doi:10.1007/s10704-022-00662-y

Phase-field modeling of rock fractures with roughness

F Fei, J Choo, C Liu, JA White
International Journal for Numerical and Analytical Methods in Geomechanics
doi:10.1002/nag.3317

Scalable preconditioning for the stabilized contact mechanics problem

A Franceschini, N Castelletto, JA White, HA Tchelepi
Journal of Computational Physics
doi:10.1016/j.jcp.2022.111150

A scalable preconditioning framework for stabilized contact mechanics with hydraulically active fractures
A Franceschini, L Gazzola, M Ferronato
Journal of Computational Physics
doi:10.1016/j.jcp.2022.111276

Enhanced Relaxed Physical Factorization preconditioner for coupled poromechanics

M Frigo, N Castelletto, M Ferronato
Computers & Mathematics with Applications
doi:10.1016/j.camwa.2021.11.015

An aggregation-based nonlinear multigrid solver for two-phase flow and transport in porous media
CS Lee, FP Hamon, N Castelletto, PS Vassilevski, JA White
Computers & Mathematics with Applications
doi:10.1016/j.camwa.2022.03.026

Deep learning-accelerated 3D carbon storage reservoir pressure forecasting based on data assimilation
using surface displacement from InSAR
H Tang, P Fu, H Jo, S Jiang, CS Sherman, F Hamon, NA Azzolina, JP Morris
982 Chapter 1. Table of Contents
International Journal of Greenhouse Gas Control
doi:10.1016/j.ijggc.2022.103765
GEOS Documentation

1.11. Publications 983

GEOS Documentation

1.11.5 2021

Hybrid mimetic finite-difference and virtual element formulation for coupled poromechanics
A Borio, FP Hamon, N Castelletto, JA White, RR Settgast
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2021.113917

Enhanced multiscale restriction-smoothed basis (MsRSB) preconditioning with applications to porous

media flow and geomechanics
SBM Bosma, S Klevtsov, O Møyner, N Castelletto
Journal of Computational Physics
doi:10.1016/j.jcp.2020.109934

Multigrid reduction preconditioning framework for coupled processes in porous and fractured media
QM Bui, FP Hamon, N Castelletto, D Osei-Kuffuor, RR Settgast, JA White
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2021.114111

A macroelement stabilization for mixed finite element/finite volume discretizations of multiphase

poromechanics
JT Camargo, JA White, RI Borja
Computational Geosciences
doi:10.1007/s10596-020-09964-3

Preconditioners for multiphase poromechanics with strong capillarity

JT Camargo, JA White, N Castelletto, RI Borja
International Journal for Numerical and Analytical Methods in Geomechanics
doi:10.1002/nag.3192

An anisotropic viscoplasticity model for shale based on layered microstructure homogenization

J Choo, SJ Semnani, JA White
International Journal for Numerical and Analytical Methods in Geomechanics
doi:10.1002/nag.3167

Simulation of coupled multiphase flow and geomechanics in porous media with embedded discrete fractures
M Cusini, JA White, N Castelletto, RR Settgast
International Journal for Numerical and Analytical Methods in Geomechanics
doi:10.1002/nag.3168

Approximate inverse-based block preconditioners in poroelasticity

984 Chapter 1. Table of Contents
A Franceschini, N Castelletto, M Ferronato
Computational Geosciences
doi:10.1007/s10596-020-09981-2
GEOS Documentation

1.11.6 2020

Scalable multigrid reduction framework for multiphase poromechanics of heterogeneous media

QM Bui, D Osei-Kuffuor, N Castelletto, JA White
SIAM Journal on Scientific Computing
doi:10.1137/19M1256117

Multi-stage preconditioners for thermal–compositional–reactive flow in porous media

MA Cremon, N Castelletto, JA White
Journal of Computational Physics
doi:10.1016/j.jcp.2020.109607

Algebraically stabilized Lagrange multiplier method for frictional contact mechanics with hydraulically
active fractures
A Franceschini, N Castelletto, JA White, HA Tchelepi
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2020.113161

Fully implicit multidimensional hybrid upwind scheme for coupled flow and transport
F Hamon, B Mallison
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2019.112606

Nonlinear multigrid based on local spectral coarsening for heterogeneous diffusion problems
CS Lee, F Hamon, N Castelletto, PS Vassilevski, JA White
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2020.113432

An inelastic homogenization framework for layered materials with planes of weakness

SJ Semnani, JA White
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2020.113221

1.11. Publications 985

GEOS Documentation

1.11.7 2019

Multiscale two-stage solver for Biot’s poroelasticity equations in subsurface media

N Castelletto, S Klevtsov, H Hajibeygi, HA Tchelepi
Computational Geosciences
doi:10.1007/s10596-018-9791-z

Block preconditioning for fault/fracture mechanics saddle-point problems

A Franceschini, N Castelletto, M Ferronato
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2018.09.039

A relaxed physical factorization preconditioner for mixed finite element coupled poromechanics
M Frigo, N Castelletto, M Ferronato
SIAM Journal on Scientific Computing
doi:10.1137/18M120645X

A two-stage preconditioner for multiphase poromechanics in reservoir simulation

JA White, N Castelletto, S Klevtsov, QM Bui, D Osei-Kuffuor, HA Tchelepi
Computer Methods in Applied Mechanics and Engineering
doi:10.1016/j.cma.2019.112575

1.12 Acknowledgements
GEOS was developed with supporting funds from a number of organizations, including
• Lawrence Livermore National Laboratory
• U.S. Department of Energy, Office of Science
• TotalEnergies.
This support is gratefully acknowledged.

986 Chapter 1. Table of Contents

CHAPTER

TWO

INDICES AND TABLES

• genindex
• modindex
• search

987
GEOS Documentation

988 Chapter 2. Indices and tables

INDEX

B
built-in function
pygeosx.apply_initial_conditions(), 556
pygeosx.finalize(), 556
pygeosx.initialize(), 555
pygeosx.reinit(), 555
pygeosx.run(), 556

G
get_group() (pygeosx.Group method), 556
get_wrapper() (pygeosx.Group method), 556
groups() (pygeosx.Group method), 556

P
pygeosx.apply_initial_conditions()
built-in function, 556
pygeosx.COMPLETED (built-in variable), 556
pygeosx.finalize()
built-in function, 556
pygeosx.Group (built-in class), 556
pygeosx.initialize()
built-in function, 555
pygeosx.INITIALIZED (built-in variable), 556
pygeosx.READY_TO_RUN (built-in variable), 556
pygeosx.reinit()
built-in function, 555
pygeosx.run()
built-in function, 556
pygeosx.UNINITIALIZED (built-in variable), 556
pygeosx.Wrapper (built-in class), 557

R
register() (pygeosx.Group method), 556

V
value() (pygeosx.Wrapper method), 557

W
wrappers() (pygeosx.Group method), 556

989

Víctor Olaya - ''A Gentle Introduction To SAGA GIS (Edition 1.1) ''
No ratings yet
Víctor Olaya - ''A Gentle Introduction To SAGA GIS (Edition 1.1) ''
217 pages
Market Guide For Endpoint Detection and Response Enero 2020
No ratings yet
Market Guide For Endpoint Detection and Response Enero 2020
13 pages
LB# 820-1372 - 051-6278 - A000.schematic
No ratings yet
LB# 820-1372 - 051-6278 - A000.schematic
44 pages
Geemap Readthedocs Io en Latest
No ratings yet
Geemap Readthedocs Io en Latest
94 pages
Gds Course
No ratings yet
Gds Course
190 pages
Get Start
No ratings yet
Get Start
79 pages
GEOEAS
No ratings yet
GEOEAS
186 pages
Nates Intro To Qgis
No ratings yet
Nates Intro To Qgis
103 pages
Raste Rio
No ratings yet
Raste Rio
269 pages
GRASS GIS For Geomorphologists: An Introductory Guide: Andrew Wickert April 16, 2012
No ratings yet
GRASS GIS For Geomorphologists: An Introductory Guide: Andrew Wickert April 16, 2012
67 pages
Qgis-1.4.0 Coding-Compilation Guide en
No ratings yet
Qgis-1.4.0 Coding-Compilation Guide en
135 pages
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman - Read the ebook online or download it for a complete experience
100% (2)
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman - Read the ebook online or download it for a complete experience
51 pages
Cosmos Users Guide
No ratings yet
Cosmos Users Guide
770 pages
Saga Manual
100% (1)
Saga Manual
216 pages
Qgis-1.6.0 User Guide en
No ratings yet
Qgis-1.6.0 User Guide en
217 pages
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman - The full ebook with all chapters is available for download
100% (1)
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman - The full ebook with all chapters is available for download
61 pages
GeoMOOSE PDF
No ratings yet
GeoMOOSE PDF
140 pages
Using The Geoquery Package: Sean Davis September 21, 2014
No ratings yet
Using The Geoquery Package: Sean Davis September 21, 2014
15 pages
Get PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman PDF ebook with Full Chapters Now
100% (2)
Get PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman PDF ebook with Full Chapters Now
79 pages
Postgis-3 1 1
No ratings yet
Postgis-3 1 1
874 pages
GMSH
100% (1)
GMSH
218 pages
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman pdf download
100% (1)
PyQGIS Programmer s Guide Extending Qgis 2 X with Python 1st Edition Gary Sherman pdf download
44 pages
Postgis-1 5 PDF
No ratings yet
Postgis-1 5 PDF
326 pages
Postgis-1 5 PDF
No ratings yet
Postgis-1 5 PDF
326 pages
Lab 1 - Introduction To The Fundamentals of Google Earth Engine API
No ratings yet
Lab 1 - Introduction To The Fundamentals of Google Earth Engine API
13 pages
Qgis-1.5.0 User Guide en
No ratings yet
Qgis-1.5.0 User Guide en
231 pages
Citcoms-3 3 0-Manual
No ratings yet
Citcoms-3 3 0-Manual
105 pages
Postgis-1 3 3
No ratings yet
Postgis-1 3 3
76 pages
Introduction To GEE Workshop - Gandhi
No ratings yet
Introduction To GEE Workshop - Gandhi
36 pages
Postgis-1 5 3 PDF
No ratings yet
Postgis-1 5 3 PDF
334 pages
Postgis-1 5 3
No ratings yet
Postgis-1 5 3
334 pages
QGIS - Open Source GIS
100% (1)
QGIS - Open Source GIS
223 pages
GPL Reference Guide For IBM SPSS Statistics
No ratings yet
GPL Reference Guide For IBM SPSS Statistics
363 pages
GNU Astronomy Utilities
No ratings yet
GNU Astronomy Utilities
145 pages
Postgis 1.5.1 Manual
No ratings yet
Postgis 1.5.1 Manual
3 pages
Geo Network User Manual
No ratings yet
Geo Network User Manual
248 pages
GMSH 2.0.0 MSH2
No ratings yet
GMSH 2.0.0 MSH2
212 pages
Qgis-1.6.0 Coding-Compilation Guide en
No ratings yet
Qgis-1.6.0 Coding-Compilation Guide en
129 pages
Geopandas Documentation: Release 0.2.0.dev
No ratings yet
Geopandas Documentation: Release 0.2.0.dev
45 pages
Postgis-3 0 PDF
100% (1)
Postgis-3 0 PDF
869 pages
Geotext Documentation
No ratings yet
Geotext Documentation
23 pages
Postgis 1.3.6 Manual
No ratings yet
Postgis 1.3.6 Manual
78 pages
Building Mapping Applications With QGIS Sample Chapter
No ratings yet
Building Mapping Applications With QGIS Sample Chapter
25 pages
Post Gis
No ratings yet
Post Gis
61 pages
Spatial R
No ratings yet
Spatial R
75 pages
Unlocking Statistics for the Social Sciences
From Everand
Unlocking Statistics for the Social Sciences
Norma Sinclair
No ratings yet
Mastering Python Advanced Concepts and Practical Applications
From Everand
Mastering Python Advanced Concepts and Practical Applications
Aissa Younes
No ratings yet
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
From Everand
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
Jay Nans
No ratings yet
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
From Everand
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
Vladimir Kiselev
No ratings yet
JAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)
From Everand
JAVA PROGRAMMING FOR BEGINNERS: Master Java Fundamentals and Build Your Own Applications (2023 Crash Course)
Theo Houle
No ratings yet
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
1/5 (1)
10K Blueprint
From Everand
10K Blueprint
Cian O Farrell
5/5 (2)
Exploring Bentley STAAD.Pro CONNECT Edition, V22 Update 12, 6th Edition
From Everand
Exploring Bentley STAAD.Pro CONNECT Edition, V22 Update 12, 6th Edition
Prof. Sham Tickoo
No ratings yet
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
Aquaponics Design Plans, Construction, Operation, and Income: Organic Food
From Everand
Aquaponics Design Plans, Construction, Operation, and Income: Organic Food
David H Dudley
No ratings yet
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Hardwiring New Leadership Habits
From Everand
Hardwiring New Leadership Habits
Dick Daniels
No ratings yet
Aquaponics How to do Everything from Backyard to Profitable Business: from BACKYARD to PROFITABLE BUSINESS
From Everand
Aquaponics How to do Everything from Backyard to Profitable Business: from BACKYARD to PROFITABLE BUSINESS
David H Dudley
No ratings yet
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
From Everand
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
Matthew C. Smith
No ratings yet
Aquaponics for Profit
From Everand
Aquaponics for Profit
David H Dudley
No ratings yet
Fractures and Fracturing-Hydraulic Fracturing in Jointed Rock
No ratings yet
Fractures and Fracturing-Hydraulic Fracturing in Jointed Rock
34 pages
Bubecketal2016acceptedpost-rev
No ratings yet
Bubecketal2016acceptedpost-rev
31 pages
A Semi-Analytical Solution for Estimating the Fracture Width in Wellbore+++++
No ratings yet
A Semi-Analytical Solution for Estimating the Fracture Width in Wellbore+++++
12 pages
a-comparative-study-of-biot-s-theory-and-the-linear-theory-3u7hkqx7j2
No ratings yet
a-comparative-study-of-biot-s-theory-and-the-linear-theory-3u7hkqx7j2
23 pages
Hydraulic Fracture Propagation Through Geological Discontinuities
No ratings yet
Hydraulic Fracture Propagation Through Geological Discontinuities
149 pages
Field Development Optimization Through Integrated Geosciences
No ratings yet
Field Development Optimization Through Integrated Geosciences
23 pages
Criterion for Crack Initiation in brittle rock under high pore pressure
No ratings yet
Criterion for Crack Initiation in brittle rock under high pore pressure
10 pages
Mathematical and Experimental Simulation of Hydraulic Fracturing in Shallow Coal Seams
No ratings yet
Mathematical and Experimental Simulation of Hydraulic Fracturing in Shallow Coal Seams
10 pages
The Relationship Between Net Pressure Development During Hydraulic Fracture Treatments and Productivity in Fruitland Coal Completions
No ratings yet
The Relationship Between Net Pressure Development During Hydraulic Fracture Treatments and Productivity in Fruitland Coal Completions
16 pages
Comparison of Griffith's Theory and Mohr Failure Criteria
No ratings yet
Comparison of Griffith's Theory and Mohr Failure Criteria
12 pages
Impacts of the Number of Perforation Clusters and Cluster Spacing on Production Performance of Horizontal Shale-Gas Wells
No ratings yet
Impacts of the Number of Perforation Clusters and Cluster Spacing on Production Performance of Horizontal Shale-Gas Wells
10 pages
Impact of cold fluid injection on hydraulic fracture propagation
No ratings yet
Impact of cold fluid injection on hydraulic fracture propagation
9 pages
Fracture Propagation in Rock_Laboratory Tests and Finite-Element Analysis
No ratings yet
Fracture Propagation in Rock_Laboratory Tests and Finite-Element Analysis
6 pages
Effect of thermal cycling-dependent cracks on physical and mechanical
No ratings yet
Effect of thermal cycling-dependent cracks on physical and mechanical
12 pages
Hydraulic-Fracture Design
No ratings yet
Hydraulic-Fracture Design
4 pages
Integrated 3D Numerical Modelling of Pressure Behavior and Casing
No ratings yet
Integrated 3D Numerical Modelling of Pressure Behavior and Casing
18 pages
minerals-12-01438-v3
No ratings yet
minerals-12-01438-v3
24 pages
OPENING OF A PRESSURIZED FRACTURE IN AN ELASTIC MEDIUM
No ratings yet
OPENING OF A PRESSURIZED FRACTURE IN AN ELASTIC MEDIUM
17 pages
Numerical modelling of hydraulic fracturing in underground rocks
No ratings yet
Numerical modelling of hydraulic fracturing in underground rocks
8 pages
Three-Dimensional Hydraulic Fracturing Simulation
No ratings yet
Three-Dimensional Hydraulic Fracturing Simulation
18 pages
Numerical Modeling of Multi-Stranded Hydraulic Fracture Propagation
No ratings yet
Numerical Modeling of Multi-Stranded Hydraulic Fracture Propagation
10 pages
Evaluation of stress changes due to multi-stage hydraulic Frac
No ratings yet
Evaluation of stress changes due to multi-stage hydraulic Frac
6 pages
Bongoleetal.20191
No ratings yet
Bongoleetal.20191
25 pages
Optimizing Horizontal Completion Techniques in the Barnett Shale Using Microseismic
No ratings yet
Optimizing Horizontal Completion Techniques in the Barnett Shale Using Microseismic
11 pages
Quantifying Variability in Hydraulic Fracture Geometry
No ratings yet
Quantifying Variability in Hydraulic Fracture Geometry
24 pages
Pressure Interpretations in Acid Fracturing Treatments
No ratings yet
Pressure Interpretations in Acid Fracturing Treatments
22 pages
978-3-319-11894-9
No ratings yet
978-3-319-11894-9
314 pages
The past revisited-The giants behind the elastic solutions for stresses around
No ratings yet
The past revisited-The giants behind the elastic solutions for stresses around
6 pages
A Numerical Analysis Method of Hydraulic Seals for (1)
No ratings yet
A Numerical Analysis Method of Hydraulic Seals for (1)
15 pages
A 3D thermo-hydro-mechanical coupling model for enhanced geothermal systems
No ratings yet
A 3D thermo-hydro-mechanical coupling model for enhanced geothermal systems
14 pages
Intersymbol Interference (ISI)
No ratings yet
Intersymbol Interference (ISI)
21 pages
Mad MP
No ratings yet
Mad MP
12 pages
LAS WEEK 7 - Grade 10 ICT
No ratings yet
LAS WEEK 7 - Grade 10 ICT
4 pages
BDCOM S2928P Hardware Installation Manual
No ratings yet
BDCOM S2928P Hardware Installation Manual
25 pages
CIS Microsoft SQL Server 2016 Benchmark v1.3.0
No ratings yet
CIS Microsoft SQL Server 2016 Benchmark v1.3.0
4 pages
Lecture Notes On: Department of Computer Science & Engineering Jaipur Engineering College & Research Centre, Jaipur
No ratings yet
Lecture Notes On: Department of Computer Science & Engineering Jaipur Engineering College & Research Centre, Jaipur
41 pages
Digital Forensics Exam Preparation
No ratings yet
Digital Forensics Exam Preparation
4 pages
Huwaei OLT
No ratings yet
Huwaei OLT
41 pages
Chapter 5, PT 1
No ratings yet
Chapter 5, PT 1
34 pages
AsteraApp Control
No ratings yet
AsteraApp Control
5 pages
Line Current Differential System: Grid Solutions
No ratings yet
Line Current Differential System: Grid Solutions
970 pages
Amiga Hardware Reference Manual-EnG
No ratings yet
Amiga Hardware Reference Manual-EnG
379 pages
NetSDK Programming Manual (Intelligent Analysis Server)
No ratings yet
NetSDK Programming Manual (Intelligent Analysis Server)
60 pages
Lecture 7 To 8 For Programming of Mobile Terminals
No ratings yet
Lecture 7 To 8 For Programming of Mobile Terminals
6 pages
Log
No ratings yet
Log
229 pages
FC24 - : Name Data Type Address Comment
No ratings yet
FC24 - : Name Data Type Address Comment
5 pages
Basic IT Tutorial 2 - No Answer, Candidates Are To Work Out The Answers Themselve
No ratings yet
Basic IT Tutorial 2 - No Answer, Candidates Are To Work Out The Answers Themselve
3 pages
nso_installation_guide-4.2
No ratings yet
nso_installation_guide-4.2
30 pages
What is an Operating System-Introduction,system components,functions,types
No ratings yet
What is an Operating System-Introduction,system components,functions,types
16 pages
Simulation of The Central Server Algorithm
No ratings yet
Simulation of The Central Server Algorithm
11 pages
SQL Notes
No ratings yet
SQL Notes
190 pages
How To - Quick Start Guide To Alibaba Cloud
No ratings yet
How To - Quick Start Guide To Alibaba Cloud
12 pages
Resume Garikipati Srujana
No ratings yet
Resume Garikipati Srujana
1 page
Unit - V
No ratings yet
Unit - V
138 pages
STEP 7 - Compatibility List
No ratings yet
STEP 7 - Compatibility List
30 pages
Univerge: Communications Platform
No ratings yet
Univerge: Communications Platform
2 pages
Ch8- firewall & IDS & IPS
No ratings yet
Ch8- firewall & IDS & IPS
13 pages
BTP100 EN Col07-50
No ratings yet
BTP100 EN Col07-50
1 page