diff --git a/README.md b/README.md index d165b9f..f737e2a 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,70 @@ 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 farsi. +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 //Mercurial// (for documentation) +- //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 + +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)' + ## Tests To run tests, execute `pytest build-` if you have compiled Tamaas with tests activated (`scons build_tests=True use_googletest=True`). +## Documentation + +To build the documentation, activate the `build_doc` option. The compiled indexes for the doxygen C++ API and Sphinx documentation can be found in `doc/build/{doxygen,sphinx}/html/index.html`. + ## 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) diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 3aaa5ff..d7835bc 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -1,115 +1,115 @@ .. 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 --- 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 **Mercurial** (for documentation) +- **Doxygen** and **Sphinx** (for documentation) -.. note:: - If on an HPC environment, you can use the following variables to specify where the dependencies are located: +.. tip:: + On an 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 ``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 ` (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`