Tamaas --- A high-performance library for periodic rough surface contact

Tamaas is a C++/Python library that implements a number of numerical methods based on integral equations to efficiently solve contact problems with rough surfaces. The word تماس (tamaas) means "contact" in Arabic and Farsi.

Quick Start

If you have a Linux system, you can simply run pip(3) install tamaas. Note however that there due to compatibility reasons, this version of Tamaas is not built with parallel/multi-threading capabilities. So if you want parallelism, or encounter an issue with the PyPI package, please compile from source.

You can also use one of our interactive tutorial notebooks to get started.

Dependencies

Here is a list of dependencies to compile Tamaas:

• a C++ compiler with full C++14 and OpenMP support
• SCons (python build system)
• FFTW3
• boost (preprocessor)
• thrust (1.9.2+)
• python 3+ with numpy
• pybind11

Optional dependencies are:

• an MPI implementation
• FFTW3 with MPI/pthreads/OpenMP support
• scipy (for nonlinear solvers)
• uvw, netCDF4, h5py (for various dumpers)
• googletest and pytest (for tests)
• Doxygen and Sphinx (for documentation)

Note that a Debian distribution should have the right packages for all these dependencies (they package the right version of thrust extracted from CUDA in stretch-backports non-free and buster non-free).

Compiling

Here are the instructions to compile Tamaas. Note that we provide a [Docker image](#using-docker-image) and a PyPI package that do not require compiling.

Installing Dependencies

On Debian-based systems, mandatory dependencies can be installed with the following command:

apt install \
    g++ \
    libboost-dev \
    libthrust-dev \
    libfftw3-dev \
    pybind11-dev \
    python3-dev \
    python3-numpy \
    scons

Additionally, to build and run tests, one needs to install:

apt install \
    libgtest-dev \
    python3-pytest

For documentation:

apt install \
    doxygen \
    python3-sphinx \
    python3-breathe \
    python3-sphinx-rtd-theme

Build System

The build system uses SCons. In order to compile Tamaas with the default options (i.e. optimized release build with python bindings + OpenMP):

scons

After compiling a first time (or running scons -h if you want to avoid compiling), 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.

Installing

Before you can import tamaas in python, you need to install the python package in some way.

Using pip

You have two choices to install tamaas:

• An out-of-repository installation to a given prefix (e.g. /usr/local, or a python virtual environment)
• A development installation to ~/.local which links to the build directory

The former is simply achieved with:

scons prefix=/your/prefix install

# Equivalent to (if you build in release)
install build-release/src/libTamaas.so* /your/prefix/lib
pip3 install --prefix /your/prefix build-release/python

The compiled parts of the python module should automatically know where to find the Tamaas shared library, so no need to tinker with LD_LIBRARY_PATH. The second installation choice is equally simple:

scons dev

# Equivalent to
pip3 install --user -e build-release/python

You can check that everything is working fine with:

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

Using environment variables (not recommended)

You can source (e.g. in your ~/.bashrc file) the file build-release/tamaas_environment.sh to modify the PYTHONPATH and LD_LIBRARY_PATH environment variables. This is however not recommended because these variables may conflict in a python virtual environment (i.e. if you use virtualenv with tamaas).

Using Docker image

Tamaas provides a Dockerfile you can use to compile and deploy Tamaas in a tested environment. Simply run docker build -t tamaas . in the root folder of the repository. Check the documentation to see which build options can be adjusted.

Tests

To run tests, make sure to have pytest installed and run scons test if you have compiled Tamaas with tests activated (scons build_tests=True).

Documentation

The latest documentation is available on ReadTheDocs! It contains detailed guides on the different components of Tamaas as well as a combined C++ and Python API documentation.

You can also build the documentation locally: activate the build_doc option and run scons doc. Make sure you have sphinx-rtd-theme and breathe installed. The compiled indexes for the doxygen C++ API and Sphinx documentation can be found in doc/build/{doxygen,sphinx}/html/index.html. Beware however that manually compiling documentation leads to a lot of warnings.

Examples

Example simulations can be found in the examples/ directory. There is no guarantee that the examples in examples/legacy/ all work however.

• rough_contact.py shows a typical normal rough contact simulation
• adhesion.py shows how you can derive some classes from Tamaas in python, here to implement a custom adhesion potential
• plasticity.py computes an elastoplastic Hertz simulation and dumps the result in examples/paraview/ in VTK format
• stresses.py shows how you can compute stresses from a boundary traction distribution
• the scripts in pipe_tools allow to execute elastic contact simulations without the need to code a custom script (see documentation for more details)

Command-line Interface

The Tamaas python module exposes a tamaas command with three subcommands:

• tamaas surface generates rough surfaces
• tamaas contact solves elastic contact
• tamaas plot plots contact pressure and displacement

See tamaas <cmd> --help for command line arguments.

Contributing

Contributions to Tamaas are welcome! Please follow the guidelines below.

Report an issue

If you have an account on gitlab, you can submit an issue. The full list of issues is available here.

Submit a patch / merge-request

Follow this guide to create a merge request on GitLab. Please target the repository's master branch.

Citing

Tamaas is the result of a science research project. To give proper credit to Tamaas and the researchers who have developed the numerical methods that it implements, please cite Tamaas as:

Frérot , L., Anciaux, G., Rey, V., Pham-Ba, S., & Molinari, J.-F. Tamaas: a library for elastic-plastic contact of periodic rough surfaces. Journal of Open Source Software, 5(51), 2121 (2020). doi:10.21105/joss.02121

The paper above details relevant references for the different features of Tamaas. In particular, if you use the elastic-plastic contact capabilities of Tamaas, please cite:

Frérot, L., Bonnet, M., Molinari, J.-F. & Anciaux, G. A Fourier-accelerated volume integral method for elastoplastic contact. Computer Methods in Applied Mechanics and Engineering 351, 951–976 (2019) doi:10.1016/j.cma.2019.04.006.

If you use the adhesive contact capabilities of Tamaas, please cite:

Rey, V., Anciaux, G. & Molinari, J.-F. Normal adhesive contact on rough surfaces: efficient algorithm for FFT-based BEM resolution. Comput Mech 1–13 (2017) doi:10.1007/s00466-017-1392-5.

For an (almost) exhaustive list of publications, insert the following code snippet at the end of your python scripts:

python
from tamaas.utils import publications
publications()

Changelog

The changelog can be consulted here.

Funding

Tamaas' development was funded by the Swiss National Science Foundation, grants 162569 ("Contact mechanics of rough surfaces") and 191720 ("Tribology of Polymers: from Atomistic to Continuum Scales").

License

Tamaas is distributed under the terms of the GNU Affero General Public License v3.0.