diff --git a/doc/sphinx/source/quickstart.rst b/doc/sphinx/source/quickstart.rst
index e6baa65..30a6a40 100644
--- a/doc/sphinx/source/quickstart.rst
+++ b/doc/sphinx/source/quickstart.rst
@@ -1,215 +1,237 @@
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
^^^^^^^^^^^^
+Docker images are automatically built and pused to the Gitlab registry. To get
+the latest image simply run:
+
+.. code-block:: bash
+
+ docker pull registry.gitlab.com/tamaas/tamaas:master
+ # to rename for convenience
+ docker tag registry.gitlab.com/tamaas/tamaas:master 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
+
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:
+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.
-
+A `singularity `_ container can be created from the docker image with:
+
+.. code-block:: bash
+
+ singularity build tamaas.sif docker://registry.gitlab.com/tamaas/tamaas:master
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.