Tamaas — A blazingly fast rough contact library

Tamaas (from تماس meaning “contact” in Arabic and Farsi) is a high-performance rough-surface periodic contact code based on boundary and volume integral equations. The clever mathematical formulation of the underlying numerical methods (see e.g. 10.1007/s00466-017-1392-5 and arXiv:1811.11558) allows the use of the fast-Fourier Transform, a great help in achieving peak performance: Tamaas is consistently two orders of magnitude faster (and lighter) than traditional FEM!

Quickstart

Here is a quick introduction to get you started with Tamaas.

Installation

First make sure the following dependencies are installed for Tamaas:

  • a C++ compiler with full C++14 and OpenMP support

  • SCons (python build system)

  • FFTW3 compiled with OpenMP support

  • thrust (1.9.2+)

  • boost (pre-processor)

  • python 3+ (probably works with python 2, but it is not tested) with numpy

  • pybind11 (included as submodule)

  • expolit (included as submodule)

Optional dependencies are:

  • scipy (for nonlinear solvers)

  • uvw (for dumpers)

  • googletest and pytest (for tests)

  • Doxygen and Sphinx (for documentation)

Tip

On a HPC environment, use the following variables to specify where the dependencies are located:

  • FFTW_ROOT

  • THRUST_ROOT

  • BOOST_ROOT

  • PYBIND11_ROOT

  • GTEST_ROOT

Note

You can use the provided Dockerfile to build an image with the external dependencies installed.

You should first clone the git submodules that are dependencies to tamaas (expolit, pybind11 and googletest):

git submodule update --init --recursive

The build system uses SCons. In order to compile Tamaas with the default options:

scons

After compiling a first time, you can edit the compilation options in the file build-setup.conf, or alternatively supply the options directly in the command line:

scons option=value [...]

To get a list of all build options and their possible values, you can run scons -h. You can run scons -H to see the SCons-specific options (among them -j n executes the build with n threads and -c cleans the build). Note that the build is aware of the CXX and CXXFLAGS environment variables.

Once compiled, you can install the python module with:

scons install prefix=/your/prefix

The above command automatically calls pip(3) if it is installed, and falls back on setuptools otherwise. If you do not want to install Tamaas, you can use the following command:

scons dev

This creates a symlink in ~/.local/lib/<python version>/site-packages and is equivalent to pip(3) install -e or ./setup.py develop. You can check that everything is working fine with:

python3 -c 'import tamaas; print(tamaas)'

Using Docker

The Tamaas repository provides a Dockerfile that describes an appropriate build environment. You can use it in the following way:

# Build the image, run it and mount the tamaas repository
docker build -t tamaas_build .
docker run -v $PWD:/app/tamaas -it tamaas_build bash

# Once in the image shell: compile and install
cd /app/tamaas
scons
scons dev

The image also has some of the dependencies required to run the examples below (matplotlib, uvw).

Running the contact pipe tools

In the examples/pipe_tools folder, you will find three scripts that can be used to explore the mechanics of elastic rough contact:

  • surface generates randomly rough surfaces (see Random rough surfaces)

  • contact solves a contact problem with a surface read from stdin (see Solving contact)

  • plot simply plots the surface tractions and displacements read from stdin

Here’s a sample command line for you to try out:

./surface --cutoffs 2 4 64 --size 512 512 --hurst 0.8 | ./contact 1 | ./plot

Check out the help of each script for a description of the arguments.

Library overview

Tamaas is mainly composed of three components:

  • Random surface generation procedures

  • Model state objects and operators

  • Contact solving procedures

These parts are meant to be independent as well as inter-operable. The first one provides an interface to several stochastic surface generation algorithms described in Random rough surfaces. The second provides an interface to a state object Model (and C++ class tamaas::Model) as well as integral operators based on the state object (see Model and integral operators). Finally, the third part provides contact solving routines that make use of the integral operators for performance (see Solving contact).

Contribution

You can contribute to Tamaas by reporting any bugs you find here if you have an account on c4science.

To contribute code to Tamaas, you can use Arcanist to send code differentials. To know if you break anything, you can run the tests with:

scons test

Make sure you have pytest installed.

Indices and tables