Tamaas --- A blazingly fast rough contact library

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.

Dependencies

Here is a list of dependencies for Tamaas:

• a C++ compiler with full C++14 and OpenMP support
• SCons (python build system)
• FFTW3 compiled with OpenMP support
• boost (preprocessor)
• thrust (1.9.2+)
• 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)

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

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.

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

Make sure however that /your/prefix/lib is in your LD_LIBRARY_PATH or is a standard location, otherwise you may get an ImportError. The second installation choice is equally simple:

scons dev

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

This time, you should not have to worry about the position of shared libraries. The python modules knows where to find them in the build directory. 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).

Tests

To run tests, execute pytest build-<build_type> if you have compiled Tamaas with tests activated (scons build_tests=True use_googletest=True).

Documentation

The latest documentation is available on ReadTheDocs!

To build the documentation, activate the build_doc option. Make sure you have sphinx-rtd-theme and breath 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)

Contributing

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

Report an issue

If you have an account on c4science, you can submit an issue. All open issues are visible on the workboard, and the full list of issues is available here.

Submit a patch / pull-request

C4Science runs Phabricator to host the code. The procedure to submit changes to repositories is described in this guide. In a nutshell:

# Make changes
git commit           # Any number of times
arc diff             # Pushes all new commits for review
# Wait for review...
arc land             # Once the changes are accepted

Citing

Please cite Tamaas as:

Frérot, L., Anciaux, G., Rey, V., Pham-Ba, S., J.-F., Molinari (2019). Tamaas, a high-performance library for periodic rough surface contact, doi:10.5281/zenodo.3479237.

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.

License

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