diff --git a/doc/sphinx/source/overview.rst b/doc/sphinx/source/overview.rst index 5bf0ce1..2c842c8 100644 --- a/doc/sphinx/source/overview.rst +++ b/doc/sphinx/source/overview.rst @@ -1,72 +1,69 @@ 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 `_) 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 `_. diff --git a/doc/sphinx/source/quickstart.rst b/doc/sphinx/source/quickstart.rst index 166c2ec..e6baa65 100644 --- a/doc/sphinx/source/quickstart.rst +++ b/doc/sphinx/source/quickstart.rst @@ -1,229 +1,215 @@ Quickstart ---------- Here is a quick introduction to get you started with Tamaas. Installation from PyPI ^^^^^^^^^^^^^^^^^^^^^^ If you have a Linux system, 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 compile from source with the instructions below. Docker image ^^^^^^^^^^^^ The ``Dockerfile`` at the root of the Tamaas repository can be used to build an image containing Tamaas with a full set of dependencies. 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. 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. diff --git a/doc/sphinx/source/rough_surfaces.rst b/doc/sphinx/source/rough_surfaces.rst index a5d42b3..cd49948 100644 --- a/doc/sphinx/source/rough_surfaces.rst +++ b/doc/sphinx/source/rough_surfaces.rst @@ -1,119 +1,117 @@ Random rough surfaces ===================== The generation of stochatsticly rough surfaces is controlled in Tamaas by two abstract classes: :cpp:class:`tamaas::SurfaceGenerator` and :cpp:class:`tamaas::Filter`. The former provides access lets the user set the surface sizes and random seed, while the latter encodes the information of the spectrum of the surface. Two surface generation methods are provided: - :cpp:class:`tamaas::SurfaceGeneratorFilter` implements a Fourier filtering algorithm (see `Hu & Tonder `_), - - :cpp:class:`tamaas::SurfaceGeneratorRandomPhase` implements a random phase filter. Both of these rely on a :cpp:class:`tamaas::Filter` object to provided the filtering information (usually power spectrum density coefficients). Tamaas provides two such classes and allows for Python subclassing: - :cpp:class:`tamaas::Isopowerlaw` provides a roll-off powerlaw, - - :cpp:class:`tamaas::RegularizedPowerlaw` provides a powerlaw with a regularized rolloff. Tamaas also provided routines for surface statistics. Generating a surface -------------------- Let us now see how to generate a surface. Frist create a filter object and set the surface sizes:: import tamaas as tm # Create spectrum object spectrum = tm.Isopowerlaw2D() # Set spectrum parameters spectrum.q0 = 4 spectrum.q1 = 4 spectrum.q2 = 32 spectrum.hurst = 0.8 The ``spectrum`` object can be queried for information, such as the root-mean-square of heights, the various statistical moments, the spectrum bandwidth, etc. Then we create a generator object and build the random surface:: generator = tm.SurfaceGeneratorFilter2D([128, 128]) generator.spectrum = spectrum generator.random_seed = 0 surface = generator.buildSurface() .. important:: The ``surface`` object is a :py:class:`numpy.ndarray` wrapped around internal memory in the ``generator`` object, so a subsequent call to :py:func:`buildSurface ` may change its content. Note that if ``generator`` goes out of scope its memory will not be freed if there is still a live reference to the surface data. .. important:: If ran in an MPI context, the constructor of :py:class:`SurfaceGeneratorFilter2D ` (and others) expects the *global* shape of the surface. The shape can also be changed with ``generator.shape = [64, 64]``. Custom filter ------------- Tamaas provides several classes that can be derived directly with Python classes, and :cpp:class:`tamaas::Filter` is one of them. Since it provides a single pure virtual method :cpp:func:`computeFilter `, it is easy to write a sub-class. Here we implement a class that takes a user-defined auto-correlation function and implements the :cpp:func:`computeFilter ` virtual function:: import numpy class AutocorrelationFilter(tm.Filter2D): def __init__(self, autocorrelation): tm.Filter2D.__init__(self) self.autocorrelation = autocorrelation.copy() def computeFilter(self, filter_coefficients): shifted_ac = numpy.fft.ifftshift(self.autocorrelation) # Fill in the PSD coefficients filter_coefficients[...] = numpy.sqrt(np.fft.rfft2(shifted_ac)) # Normalize filter_coefficients[...] *= 1 / numpy.sqrt(self.autocorrelation.size) Here ``filter_coefficients`` is also a :py:class:`numpy.ndarray` and is therefore easily manipulated. The creation of the surface then follows the same pattern as previously:: # Create spectrum object autocorrelation = ... # set your desired autocorrelation spectrum = AutocorrelationFilter(autocorrelation) generator = tm.SurfaceGenerator2D() generator.shape = autocorrelation.shape generator.spectrum = spectrum surface = generator.buildSurface() The lifetime of the ``spectrum`` object is associated to the ``generator`` when :py:func:`setSpectrum ` is called. Surface Satistics ----------------- Tamaas provides the C++ class :cpp:class:`tamaas::Statistics` and its wrapper :py:class:`Statistics2D ` to compute statistics on surfaces, including: - power spectrum density - autocorrelation - spectrum moments - root-mean-square of heights :math:`\sqrt{\langle h^2 \rangle}` - root-mean-square of slopes (computed in Fourier domain) :math:`\sqrt{\langle |\nabla h|^2\rangle}` All these quantities are computed in a discretization-independent manner: increasing the number of points in the surface should not drastically change the computed values (for a given spectrum). This allows to refine the discretization as much as possible to approximate a continuum. Note that the autocorrelation and PSD are fft-shifted. Here is a sample code plotting the PSD and autocorrelation:: psd = tm.Statistics2D.computePowerSpectrum(surface) psd = numpy.fft.fftshift(psd, axes=0) # Shifting only once axis because of R2C transform import matplotlib.pyplot as plt from matplotlib.colors import LogNorm plt.imshow(psd.real, norm=LogNorm()) acf = tm.Statistics2D.computeAutocorrelation(surface) acf = numpy.fft.fftshift(acf) plt.figure() plt.imshow(acf) plt.show() See ``examples/statistics.py`` for more usage examples of statistics.