Getting Started#

Ratel provides static, quasistatic, and dynamic applications with a variety of elastic material models. Additionally, Ratel has an API for creation of solid mechanics applications with PETSc.


Docker images provide a ‘quick start’ option for users wanting to use the Ratel quasistatic and dynamic applications. These Docker images are automatically generated for the latest commit to main.

To run the Ratel quasistatic application in the published Docker container with a local work directory, use:

host$ docker run -it --rm -v $(pwd):/work
container$ ratel-quasistatic -options_file config.yaml

The published Ratel Docker image provides a generic CPU only build of Ratel. For GPU support or builds optimized to your specific hardware, use the download and build instructions below.

Download and Install#

A local build and installation provides greater control over build options and optimization. Ratel is open-source and can be downloaded from the Ratel repository on GitLab.

$ git clone


The Ratel solid mechanics library is based upon libCEED and PETSc.


Ratel requires libCEED’s main development branch, which can be cloned from Github.

$ git clone
$ make -C -j8 libCEED

The above will be enough for most simple CPU installations; see the libCEED documentation for details on using GPUs, tuning, and more complicated environments.

The current minimum required libCEED commit hash can be found in containers/docker/libceed/Dockerfile.


Ratel requires PETSc’s main development branch, which can be cloned from GitLab.

$ git clone

Follow the PETSc documentation to configure and build PETSc.

The current minimum required PETSc commit hash can be found in containers/docker/petsc/Dockerfile.


Ratel supports developing new constitutive models with Automatic Differentiation using Enzyme-AD, which can be cloned from GitHub.

$ git clone

Follow the Enzyme documentation to build Enzyme.


The environment variables CEED_DIR, PETSC_DIR, and PETSC_ARCH must be set to build Ratel. ENZYME_LIB could also be set if one opts to use Enzyme-AD.

Assuming you have cloned the Ratel repository as above, build using:

$ export CEED_DIR=[path to libCEED] PETSC_DIR=[path to PETSc] PETSC_ARCH=[PETSc arch] ENZYME_LIB=[path to Enzyme]
$ make -j8

To run a sample problem with the quasistatic example using multiple pseudotimesteps, run:

$ bin/ratel-quasistatic -options_file examples/ex02-quasistatic-elasticity-schwarz-pendulum.yml

To activate common solver monitor options such as solution values at each pseudotimestep (that can be visualized using software like Paraview or VisIt), run:

$ bin/ratel-quasistatic -options_file examples/ex02-quasistatic-elasticity-schwarz-pendulum.yml -options_file examples/ratel-monitor.yml

To test the installation, use

$ make test -j8

See the Example Applications for instructions on using the Ratel applications.

GPU Support#

Ratel supports CUDA and ROCm GPUs. To use these features, build PETSc and libCEED with GPU support and run with -ceed /gpu/cuda or -ceed /gpu/hip.

The multigrid coarse solver uses PETSc PCGAMG by default. Other coarse solvers such as PCHYPRE can be selected with -mg_coarse_pc_type hypre. Coarse solvers generally require an assembled matrix, and this be done on the GPU with suitable matrix types.

The default multigrid coarse solver options are set based upon the libCEED backend selected at runtime. These options are listed below:

Table 1 Default configurations#

libCEED Backend

Default DM options


PETSc configure

-ceed /cpu/self

-coarse_dm_mat_type aij

assembles coarse matrix in CPU memory; GAMG uses CPU


-ceed /gpu/cuda

-coarse_dm_mat_type aijcusparse -dm_vec_type cuda

GAMG and Hypre use GPU


-ceed /gpu/hip

-coarse_dm_mat_type aijkokkos -dm_vec_type kokkos

GAMG and Hypre use GPU

--with-hip --download-kokkos --download-kokkos-kernels

Build Containers Locally#

As an alterative to using the published Ratel Docker image or building Ratel locally, users can also build Docker images locally.

Building Docker Containers#

The Ratel Docker images have the following chain of dependencies:

  1. petsc

  2. libceed

  3. dev-env

  4. latest

The default is to build with PetscInt == int32 in the PETSc image, but this can be changed by use of the build arguments PETSC_DIR and ADDITIONAL_PETSC_OPTS,

To build a single container with optional arguments in the $RATEL_DIR/containers/docker directory:

$ docker build -t petsc --build-arg PETSC_DIR="/usr/local/petsc/mpich-int64-real-opt" --build-arg ADDITIONAL_PETSC_OPTS="--with-64-bit-indices"

To build only the PetscInt == int32 development environment containers locally in the $RATEL_DIR/containers/docker directory:


To build and deploy PetscInt == int32 and PetscInt == int64 development environment containers from the $RATEL_DIR/containers/docker directory:

$ docker login
$ DEPLOY=1 ./

Building Singularity Containers#

The Ratel Singularity def files use the Docker images generated in Ratel CI/CD to build a Singularity container.

Alternatively, users can directly use Docker images for a Singularity container from the command line.

$ singularity run docker://

How to Cite#

The archival copy of the Ratel user manual is maintained on Zenodo. To cite the user manual:

  author    = {Atkins, Zach and
               Brown, Jed and
               Ghaffari, Leila and
               Shakeri, Rezgar and
               Stengel, Ren and
               Thompson, Jeremy L},
  title     = {Ratel User Manual},
  month     = jan,
  year      = 2023,
  publisher = {Zenodo},
  version   = {v0.2.1},
  doi       = {10.5281/zenodo.7530158},
  url       = {}