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

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 registry.gitlab.com/micromorph/ratel
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 https://gitlab.com/micromorph/ratel

Prerequisites

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

libCEED

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

$ git clone https://github.com/CEED/libCEED
$ 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.

PETSc

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

$ git clone https://gitlab.com/petsc/petsc

Follow the PETSc documentation to configure and build PETSc.

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

Automatic Differentiation

Ratel supports developing new constitutive models with Automatic Differentiation tools, including Enzyme-AD and ADOL-C.

Enzyme-AD

Enzyme-AD can be cloned from GitHub.

$ git clone https://github.com/EnzymeAD/Enzyme

Follow the Enzyme documentation to build Enzyme.

ADOL-C

ADOL-C can be cloned from GitHub.

$ git clone https://github.com/coin-or/ADOL-C

Follow the ADOL-C instructions to build ADOL-C.

Building

The environment variables CEED_DIR, PETSC_DIR, and PETSC_ARCH must be set to build Ratel. Assuming you have cloned the Ratel repository as above, export these environment variables:

$ export CEED_DIR=[path to libCEED] PETSC_DIR=[path to PETSc] PETSC_ARCH=[PETSc arch]

If you are using Enzyme-AD, set the ENZYME_LIB environment variable as well:

$ export ENZYME_LIB=[path to Enzyme]

For ADOL-C, you can either set ADOLC_LIB and ADOLC_INCLUDE directly, or set ADOLC_DIR (which should contain both include/ and lib/ subdirectories). Alternatively, if ADOL-C is installed globally, you can simply build Ratel with WITH_ADOLC=1.

$ export ADOLC_LIB=[path to ADOL-C lib directory] ADOLC_LIB=[path to ADOL-C include directory]

or

$ export ADOLC_DIR=[path to ADOL-C directory]

Note: Building Ratel with Enzyme-AD or ADOL-C is optional. Depending on your system setup, you might not be able to build both at the same time.

Build Ratel with:

$ make -j8

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

$ bin/ratel-quasistatic -options_file examples/ymls/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/ymls/ex02-quasistatic-elasticity-schwarz-pendulum.yml -options_file examples/ymls/ratel-monitor.yml

To test the installation, use

$ make test -j8

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

Install

To install Ratel, run:

$ make install prefix=/path/to/install/dir

or (e.g., if creating packages):

$ make install prefix=/usr DESTDIR=/packaging/path

To build and install in separate steps, run:

$ make for_install=1 prefix=/path/to/install/dir
$ make install prefix=/path/to/install/dir

The usual variables like CEED_DIRandPETSC_DIRare used. UseSTATIC=1 to build static libraries (ratel.a`).

pkg-config

In addition to library and header, Ratel provides a pkg-config file that can be used to easily compile and link. For example, if $prefix is a standard location or you set the environment variable PKG_CONFIG_PATH:

$ cc `pkg-config --cflags --libs ceed` -o myapp myapp.c

will build myapp with Ratel. This can be used with the source or installed directories. Most build systems have support for pkg-config.

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:

Default configurations

libCEED Backend

Default DM options

Notes

PETSc configure

-ceed /cpu/self

-coarse_dm_mat_type aij

assembles coarse matrix in CPU memory; GAMG uses CPU

None

-ceed /gpu/cuda

-coarse_dm_mat_type aijcusparse -dm_vec_type cuda

GAMG and Hypre use GPU

--with-cuda

-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 registry.gitlab.com/micromorph/ratel:petsc-int64 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:

$ SKIP_INT64_BUILD=1 ./build-containers.sh

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

$ docker login registry.gitlab.com
$ DEPLOY=1 ./build-containers.sh

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://registry.gitlab.com/micromorph/ratel

How to Cite

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

@misc{ratel-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     = nov,
  year      = 2023,
  publisher = {Zenodo},
  version   = {v0.3.0},
  doi       = {10.5281/zenodo.10063890},
  url       = {https://doi.org/10.5281/zenodo.10063890}
}

Contact

You can reach the Ratel team by leaving a comment in the issue tracker.