diff --git a/README.md b/README.md index 2228b0c..6a168a1 100644 --- a/README.md +++ b/README.md @@ -1,198 +1,198 @@ -Tamaas --- A blazingly fast rough contact library -================================================= +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 with Python 3.7+ installed, you can simply run `pip3 -install tamaas`. Note however that there may be incompatibilities between Linux -distributions (the PyPI package was built on Debian Buster), so if you encounter -an issue, please compile from source. +If you have a Linux system with Python 3.7+ and FFTW3 installed, you can simply +run `pip3 install tamaas`. Note however that there may be incompatibilities +between Linux distributions (the PyPI package was built on Debian Buster), so if +you encounter an issue, please compile from source. ## 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/) compiled with //OpenMP// support - [boost](https://www.boost.org/) (preprocessor) - [thrust](https://github.com/thrust/thrust) (1.9.2+) - [python 3+](https://www.python.org/) (probably works with python 2, but it is not tested) with [numpy](https://numpy.org/) - [pybind11](https://github.com/pybind/pybind11) (included as submodule) - [expolit](https://c4science.ch/source/expolit/) (included as submodule) Optional dependencies are: - [scipy](https://scipy.org) (for nonlinear solvers) - [uvw](https://pypi.org/project/uvw/) (for 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 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 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). ## 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 use_googletest=True`). ## Documentation The latest documentation is available on [ReadTheDocs](https://tamaas.readthedocs.io/en/latest/)! Note however that due to technical limitations, the Python API documentation is not available online. You'll need to compile the documentation locally. To build the documentation, activate the `build_doc` option and run `scons doc`. Make sure you have [sphinx-rtd-theme](https://pypi.org/project/sphinx-rtd-theme/) and [breath](https://pypi.org/project/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) ## Contributing Contributions to Tamaas are welcome! Please follow the guidelines below. ### Report an issue If you have an account on [c4science](https://c4science.ch), you can [submit an issue](https://c4science.ch/maniphest/task/edit/?owner=frerot&projectPHIDs=tamaas&view=public). All open issues are visible on the [workboard](https://c4science.ch/project/board/2036/), and the full list of issues is available [here](https://c4science.ch/maniphest/query/1jDBkIDDxCAP/). ### Submit a patch / pull-request C4Science runs [Phabricator](https://www.phacility.com/phabricator/) to host the code. The procedure to submit changes to repositories is described in this [guide](https://secure.phabricator.com/book/phabricator/article/arcanist_diff/). In a nutshell: ```lang=bash # Make changes git commit # Any number of times arc diff # Pushes all new commits for review # Wait for review... ``` ## 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) 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). ## 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/index.rst b/doc/sphinx/source/index.rst index 6fdbbd2..ead12ea 100644 --- a/doc/sphinx/source/index.rst +++ b/doc/sphinx/source/index.rst @@ -1,105 +1,105 @@ .. 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 blazingly fast rough contact library -================================================= +Tamaas --- A high-performance library for periodic rough surface contact +======================================================================== .. 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 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 :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. 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`). .. toctree:: :maxdepth: 2 :caption: Table of Contents: ./quickstart ./rough_surfaces ./model ./contact ./examples ./performance ./api_reference Seeking help ------------ You can ask your questions on `c4science `_ using this `form `_. If you do not have an account, you can create one `here `_. Contribution ------------ Code .... To contribute code to Tamaas, you can use `Arcanist `_ to send code differentials. In a nutshell, the process to contribute is: 1. Create a branch for the modifications you wish to submit 2. Work on your branch (commits + run tests) 3. ``arc diff`` to send your code for review 4. Commit any requested changes 5. ``arc diff`` to send your modifications For reviewers: 1. Checkout a code differential using ``arc patch D???`` 2. Accept the code differential on `c4science `_. 3. ``arc land`` to merge the differential 4. Profit with ``arc anoid`` Bug reports ........... You can also contribute to Tamaas by reporting any bugs you find `here `_ if you have an account on `c4science `_. Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` diff --git a/python/setup.py.in b/python/setup.py.in index 161bd11..814bc89 100644 --- a/python/setup.py.in +++ b/python/setup.py.in @@ -1,94 +1,93 @@ import setuptools import shutil import sysconfig import os long_description = """ -# Tamaas — A fast rough contact library +# Tamaas - A high-performance library for periodic rough surface contact [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3479236.svg)](https://doi.org/10.5281/zenodo.3479236) [![status](https://joss.theoj.org/papers/86903c51f3c66964eef7776d8aeaf17d/status.svg)](https://joss.theoj.org/papers/86903c51f3c66964eef7776d8aeaf17d) 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 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! Tamaas is aimed at researchers and practitioners wishing to compute realistic contact solutions for the study of interface phenomena. ## Disclaimer This package is intended for ease of installation for Linux platforms, but comes with NO WARRANTY of compatibility. If you experience any issue, please install Tamaas from [source](https://c4science.ch/source/tamaas/). We provide a Docker image for non-Linux systems. This package contains unsigned binary blobs: if you are concerned about security, please build Tamaas from source (the commits are signed). 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 the [JOSS paper](https://joss.theoj.org/papers/86903c51f3c66964eef7776d8aeaf17d) and the appropriate references therein. ## Dependencies Essentials: - FFTW with OpenMP support (needs to be installed separately, e.g. with your system's package manager) - Numpy Optional: - Scipy (for non-linear solvers) - UVW (for dumpers) - h5py (for dumpers) - netCDF4 (for dumpers) To install with all dependencies (except FFTW), run ``pip install tamaas[solvers,dumpers]``. ## Documentation Documentation can be found on [tamaas.readthedocs.io](https://tamaas.readthedocs.io/en/latest/). """ version = "@version@" major = version.split('.')[0] if @packaging_setup@: shutil.copyfile('../../README.md', 'README.md') shutil.copyfile('../src/libTamaas.so.{}'.format(version), 'tamaas/libTamaas.so.{}'.format(major)) setuptools.setup( name="tamaas", version="@version@", packages=setuptools.find_packages(), include_package_data=True, author=', '.join(@authors@), author_email="@email@", - description='A fast library for periodic elastic ' - 'and elasto-plastic rough contact', + description='A high-performance library for periodic rough surface contact', long_description=long_description, long_description_content_type="text/markdown", url="https://c4science.ch/project/view/2036/", install_requires=['numpy'], extras_require={ "dumpers": ['uvw', 'h5py', 'netCDF4'], "solvers": ['scipy'], }, classifiers=[ "Intended Audience :: Science/Research", "License :: OSI Approved :: GNU Affero General Public License v3", "Programming Language :: C++", "Programming Language :: Python :: 3", "Topic :: Scientific/Engineering", "Intended Audience :: Science/Research", "Operating System :: POSIX :: Linux", ] )