Homec4science
Diffusion tamaas (maxwell_viscoelastic-branch) Browse

tamaas/doc/sphinx/source/index.rst
8a6e6130da0emaxwell_viscoelastic…

Last Change
Raw File

index.rst
View Options

.. Tamaas documentation master file, created by
sphinx-quickstart on Mon Apr 29 18:08:33 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Tamaas: high performance 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 <https://doi.org/10.1007/s00466-017-1392-5>`_ and `arXiv:1811.11558 <https://arxiv.org/abs/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 **Mercurial** (for documentation)
.. note::
If on an HPC environment, you can 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 <https://c4science.ch/source/expolit/>`_, `pybind11 <https://github.com/pybind/pybind11>`_ and `googletest <https://github.com/google/googletest>`_)::
git submodule update --init --recursive
The build system uses `SCons <https://scons.org/>`_. 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 ``pip`` (preferably in a virtual environment)::
pip install -e build-release/python
Check that everything is working fine with::
python3 -c 'import tamaas; print(tamaas)'
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 :doc:`rough_surfaces`)
- ``contact`` solves a contact problem with a surface read from ``stdin`` (see :doc:`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 meant to be independent as well as inter-operable. The first one provides an interface to several stochastic surface generation algorithms described in :doc:`rough_surfaces`. The second provides an interface to a state object :py:class:`Model <tamaas._tamaas.Model>` (and C++ class :cpp:class:`tamaas::Model`) as well as integral operators based on the state object (see :doc:`model`). Finally, the third part provides contact solving routines that make use of the integral operators for performance (see :doc:`contact`).
.. toctree::
:maxdepth: 2
:caption: Table of Contents:
./rough_surfaces
./model
./contact
./api_reference
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
c4science · Help