diff --git a/doc/sphinx/source/quickstart.rst b/doc/sphinx/source/quickstart.rst
index 8ad42f2..2dd86d7 100644
--- a/doc/sphinx/source/quickstart.rst
+++ b/doc/sphinx/source/quickstart.rst
@@ -1,185 +1,185 @@
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 ``pip(3) install tamaas``. Note
however that there may be due to compatibility reasons, this version of Tamaas
is not built with parallel capabilities. So if you want parallelism, or
encounter an issue with the `PyPI package `_,
please compile from source.
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 (`expolit `_,
`pybind11 `_ and `googletest
`_)::
git clone --recursive https://c4science.ch/source/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)'
Using Docker
............
The Tamaas repository provides a `Dockerfile` that describes an appropriate
build environment. You can use it in the following way:
.. code-block:: bash
# Build the image, run it and mount the tamaas repository
docker build -t tamaas_build .
docker run -v $PWD:/app/tamaas -it tamaas_build bash
# Once in the image shell: compile and install
cd /app/tamaas
scons
scons dev
The image also has some of the dependencies required to run the examples below
(matplotlib, uvw).
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``.
``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.
``fftw_threads``
Controls the FFTW thread model. Defaults to ``omp`` for OpenMP.
``use_mpi``
Activates MPI-parallelism.
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
+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.