diff --git a/README.md b/README.md index a14c947..446f0cd 100644 --- a/README.md +++ b/README.md @@ -1,269 +1,270 @@ Tamaas --- A high-performance library for periodic rough surface contact ======================================================================== [![JOSS](https://joss.theoj.org/papers/10.21105/joss.02121/status.svg)](https://doi.org/10.21105/joss.02121) [![Documentation Status](https://readthedocs.org/projects/tamaas/badge/?version=latest)](https://tamaas.readthedocs.io/en/latest/?badge=latest) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gl/tamaas%2Ftutorials/HEAD) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3479236.svg)](https://doi.org/10.5281/zenodo.3479236) 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 `pip3 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](https://pypi.org/project/tamaas/), please compile from source. This can be easily done with [Spack](https://spack.io/) using the command `spack install tamaas`. See `spack info tamaas` for build options. You can also use one of our [interactive tutorial notebooks](https://tamaas.readthedocs.io/en/latest/overview.html#tutorials) to get started. ## πŸ“š Dependencies Here is a list of dependencies to compile Tamaas: - a C++ compiler with full C++14 and OpenMP support - [SCons](https://scons.org/) (python build system) - [FFTW3](http://www.fftw.org/) - [boost](https://www.boost.org/) (preprocessor) - [thrust](https://github.com/NVIDIA/thrust) (1.9.2+) - [python 3+](https://www.python.org/) with [numpy](https://numpy.org/) - [pybind11](https://github.com/pybind/pybind11) Optional dependencies are: - an MPI implementation - [FFTW3](http://www.fftw.org/) with MPI/pthreads/OpenMP support - [scipy](https://scipy.org) (for nonlinear solvers) - [uvw](https://pypi.org/project/uvw/), [netCDF4](https://unidata.github.io/netcdf4-python/netCDF4/index.html#section1), [h5py](https://www.h5py.org/) (for various dumpers) - [googletest](https://github.com/google/googletest) and [pytest](https://docs.pytest.org/en/latest/) (for tests) - [Doxygen](http://doxygen.nl/) and [Sphinx](https://www.sphinx-doc.org/en/stable/) (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](https://pypi.org/project/tamaas/) 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): 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](https://docs.pytest.org/en/latest/) 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](https://tamaas.readthedocs.io/en/latest/)! 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](https://pypi.org/project/sphinx-rtd-theme/) and [breathe](https://pypi.org/project/breathe/) installed. The compiled indexes for the doxygen C++ API and Sphinx documentation can be found in `build-release/doc/{doxygen,sphinx}/html/index.html`. ## πŸ“‘ Examples Example simulations can be found in the `examples/` directory. These simulations can be run in MPI. - `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 ## πŸ’» 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 --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](https://gitlab.com), you can [submit an issue](https://gitlab.com/tamaas/tamaas/-/issues/new). The full list of issues -is available [here](https://gitlab.com/tamaas/tamaas/-/issues). +is available [here](https://gitlab.com/tamaas/tamaas/-/issues). Please read the +[FAQ](https://tamaas.readthedocs.io/en/latest/faq.html) before posting. ### Submit a patch / merge-request Follow [this guide](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) 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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://gitlab.com/tamaas/tamaas/-/blob/master/CHANGELOG.md). ## 🏦 Funding Tamaas' development was funded by the [Swiss National Science Foundation](https://www.snf.ch), grants [162569 ("Contact mechanics of rough surfaces")](https://data.snf.ch/grants/grant/162569) and [191720 ("Tribology of Polymers: from Atomistic to Continuum Scales")](https://data.snf.ch/grants/grant/191720). ## βš–οΈ License Tamaas is distributed under the terms of the [GNU Affero General Public License v3.0](https://www.gnu.org/licenses/agpl.html). diff --git a/doc/sphinx/source/faq.rst b/doc/sphinx/source/faq.rst new file mode 100644 index 0000000..4f9c9ae --- /dev/null +++ b/doc/sphinx/source/faq.rst @@ -0,0 +1,14 @@ +.. _faq: + +Frequently Asked Questions +========================== + +Importing ``tamaas`` module gives a circular import error on Windows +-------------------------------------------------------------------- + +`(Similar to this issue) `_ +Installing with ``pip install tamaas`` does not work on Windows, as binary +distributions are only built for Linux. To use Tamaas in Windows, use the +Windows subsystem for Linux, then use ``pip`` to :ref:`install Tamaas +`, or use the :ref:`provided Docker images `. + diff --git a/doc/sphinx/source/index.rst b/doc/sphinx/source/index.rst index 530a1e3..f5b190a 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -1,52 +1,53 @@ .. 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 --- A high-performance library for periodic rough surface contact ======================================================================== .. image:: https://img.shields.io/badge/code-gitlab.com%2Ftamaas-9cf.svg :target: https://gitlab.com/tamaas/tamaas .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3479236.svg :target: https://doi.org/10.5281/zenodo.3479236 .. image:: https://joss.theoj.org/papers/86903c51f3c66964eef7776d8aeaf17d/status.svg :target: https://joss.theoj.org/papers/86903c51f3c66964eef7776d8aeaf17d .. image:: https://mybinder.org/badge_logo.svg - :target: https://mybinder.org/v2/gl/tamaas%2Ftutorials/HEAD + :target: https://mybinder.org/v2/gl/tamaas%2Ftutorials/HEAD 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. :doi:`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 :doc:`two orders of magnitude faster ` (and lighter) than traditional FEM! Tamaas is aimed at researchers and practitioners wishing to compute realistic contact solutions for the study of interface phenomena. You can see Tamaas in action with our interactive :ref:`tutorials `. .. toctree:: :maxdepth: 2 :caption: Table of Contents: ./overview ./quickstart ./rough_surfaces ./model ./contact ./mpi ./examples ./performance + ./faq ./api_reference Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/doc/sphinx/source/overview.rst b/doc/sphinx/source/overview.rst index 2f82cc9..e2409c3 100644 --- a/doc/sphinx/source/overview.rst +++ b/doc/sphinx/source/overview.rst @@ -1,81 +1,81 @@ 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 :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`). .. _sect-tutorials: Tutorials --------- The following tutorial notebooks can also be used to learn about Tamaas: - Elastic Contact (`live notebook `_, `notebook viewer `_) - Rough Surfaces (`live notebook `__, `notebook viewer `__) Citations --------- Tamaas is the fruit of a research effort. To give proper credit to its creators and the scientists behind the methods it implements, you can use the :py:func:`tamaas.utils.publications` function at the end of your python scripts. This function scans global variables and prints the relevant citations for the different capabilities of Tamaas used. Note that it may miss citations if some objects are not explicitly stored in named variables, so please examine the relevant publications in :doi:`10.21105/joss.02121`. Changelog --------- The changelog can be consulted `here `__. Seeking help ------------ You can ask your questions on `gitlab `_ using this `form `_. If you do not have an account, you can create one `on this page `_. Contribution ------------ Contributions to Tamaas are welcome, whether they are code, bug, or documentation related. Code .... Please `fork `_ Tamaas and `submit your patch as a merge request `_. Bug reports ........... You can also contribute to Tamaas by reporting any bugs you find `here `__ if you have an account on -`gitlab `__. +`gitlab `__. Please read the :ref:`FAQ ` before posting. diff --git a/doc/sphinx/source/quickstart.rst b/doc/sphinx/source/quickstart.rst index e8dcd72..2b65307 100644 --- a/doc/sphinx/source/quickstart.rst +++ b/doc/sphinx/source/quickstart.rst @@ -1,303 +1,307 @@ Quickstart ---------- Here is a quick introduction to get you started with Tamaas. +.. _pip-install: + Installation from PyPI ^^^^^^^^^^^^^^^^^^^^^^ If you have a Linux system, or have installed the `Windows Subsystem for Linux `_, you can simply run ``python3 -m pip install tamaas``. This installs the latest stable version of Tamaas from `PyPI `_. You can get the latest cutting-edge build of Tamaas with: .. code-block:: bash python3 -m pip install \ --extra-index-url https://gitlab.com/api/v4/projects/19913787/packages/pypi/simple \ tamaas .. note:: To limit the number of statically linked dependencies in the wheel package, the builds that can be installed via PyPI or the GitLab package registery do not include parallelism or architecture specific optimizations. If you want to execute Tamaas in parallel, or want to improve performance, it is highly recommanded that you install with Spack or compile from source with the instructions below. Installation with Spack ^^^^^^^^^^^^^^^^^^^^^^^ If you have `Spack `_ installed (e.g. in an HPC environment), you can install Tamaas with the following: .. code-block:: bash spack install tamaas This will install an MPI-enabled version of tamaas with Scipy solvers. The command ``spack info tamaas`` shows the build variants. To disable MPI, you should disable MPI in the FFTW variant: .. code-block:: bash spack install tamaas ^fftw~mpi The Spack package for Tamaas allows installation from the repository with ``spack install tamaas@master``. You can also use Spack to create container recipes with ``spack containerize``. Here's an example ``spack.yaml`` for Tamaas which creates an image with OpenMPI and NetCDF so that Tamaas can be executed in parallel within the container with `Singularity `_: .. code-block:: yaml spack: config: build_jobs: 2 specs: - matrix: - [py-mpi4py, py-netcdf4, tamaas@master+solvers] - ["^openmpi@4 fabrics=ofi,psm2,ucx schedulers=none"] concretizer: unify: true container: format: singularity images: os: ubuntu:20.04 spack: develop os_packages: final: - gfortran +.. _docker-image: + Docker image ^^^^^^^^^^^^ We provide Docker images that are automatically built and pused to the Gitlab registry for compatibility reasons (mainly with macOS). To get the latest image simply run: .. code-block:: bash docker pull registry.gitlab.com/tamaas/tamaas # to rename for convenience docker tag registry.gitlab.com/tamaas/tamaas tamaas Then you can run scripts directly: .. code-block:: bash docker run -v $PWD:/app -t tamaas python3 /app/your_script.py # or docker run tamaas tamaas surface --sizes 16 16 --cutoffs 4 4 8 --hurst 0.8 | docker run -i tamaas tamaas contact 0.1 > results.npy .. warning:: The provided Docker image and Dockerfile offer limited customization options and are hard-wired to use OpenMPI. If the use case/goal is to run in HPC environements, containers generated with Spack should be preferred, as they allow greater flexibility in the dependency selection and installed packages. The ``Dockerfile`` at the root of the Tamaas repository can be used to build an image containing Tamaas with a full set of dependencies and customize the build options. Simply run: .. code-block:: bash docker build -t tamaas . .. tip:: The following arguments can be passed to docker to customize the Tamaas build (with the ``--build-arg`` flag for ``docker build``): - ``BACKEND``: parallelism model for loops - ``FFTW_THREADS``: parallelism model for FFTW3 - ``USE_MPI``: compile an MPI-parallel version of Tamaas See below for explanations. Singularity container ^^^^^^^^^^^^^^^^^^^^^ A `singularity`_ container can be created from the docker image with: .. code-block:: bash singularity build tamaas.sif docker://registry.gitlab.com/tamaas/tamaas To run the image with MPI: .. code-block:: bash mpirun singularity exec --home=$PWD tamaas.sif python3 Installation from source ^^^^^^^^^^^^^^^^^^^^^^^^ 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** - **thrust** (1.9.2+) - **boost** (pre-processor) - **python 3+** with **numpy** - **pybind11** (included as submodule) - **expolit** (included as submodule) Optional dependencies are: - an MPI implementation - **FFTW3** with MPI/threads/OpenMP (your pick) support - **scipy** (for nonlinear solvers) - **uvw**, **h5py**, **netCDF4** (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 repository with the submodules that are dependencies to tamaas (`pybind11 `_ and `googletest `_):: git clone --recursive https://gitlab.com/tamaas/tamaas.git 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: .. code-block:: bash 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: .. code-block:: bash 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//site-packages`` and is equivalent to ``pip(3) install -e`` or ``./setup.py develop``. You can check that everything is working fine with: .. code-block:: bash python3 -c 'import tamaas; print(tamaas)' Important build options ....................... Here are a selected few important compilation options: ``build_type`` Controls the type of build, which essentially changes the optimisation level (``-O0`` for ``debug``, ``-O2`` for ``profiling`` and ``-O3`` for ``release``) and the amount of debug information. Default type is ``release``. Accepted values are: - ``release`` - ``debug`` - ``profiling`` ``CXX`` Compiler (uses the environment variable ``CXX`` by default). ``CXXFLAGS`` Compiler flags (uses the environment variable ``CXXFLAGS`` by default). Useful to add tuning flags (e.g. ``-march=native -mtune=native`` for GCC or ``-xHOST`` for Intel), or additional optimisation flags (e.g. ``-flto`` for link-time optimization). ``backend`` Controls the Thrust parallelism backend. Defaults to ``omp`` for OpenMP. Accepted values are: - ``omp``: OpenMP - ``cpp``: Sequential - ``tbb`` (unsupported): Threading Building Blocks ``fftw_threads`` Controls the FFTW thread model. Defaults to ``omp`` for OpenMP. Accepted values are: - ``omp``: OpenMP - ``threads``: PThreads - ``none``: Sequential ``use_mpi`` Activates MPI-parallelism (boolean value). More details on the above options can be found in :doc:`performance`. Building the docs ^^^^^^^^^^^^^^^^^ Documentation is built using ``scons doc``. Make sure to have the correct dependencies installed (they are already provided in the Docker image). Running the contact pipe tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once installed, the python package provides a `tamaas` command, which defines three subcommands that can be used to explore the mechanics of elastic rough contact: - ``surface`` generates randomly rough surfaces (see :doc:`rough_surfaces`) - ``contact`` solves an elastic contact problem with a surface read from ``stdin`` (see :doc:`contact`) - ``plot`` plots the surface tractions and displacements read from ``stdin`` Here's a sample command line for you to try out: .. code-block:: bash tamaas surface --cutoffs 2 4 64 --size 512 512 --hurst 0.8 | tamaas contact 1 | tamaas plot Check out the help of each command (e.g. ``tamaas surface -h``) for a description of the arguments. Running the tests ^^^^^^^^^^^^^^^^^ You need to activate the ``build_tests`` option to compile the tests: .. code-block:: bash scons build_tests=True Tests can then be run with the ``scons test`` command. Make sure you have `pytest `_ installed.