Here is a quick introduction to get you started with Tamaas.
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:
python3 -m pip install \
--extra-index-url https://gitlab.com/api/v4/projects/19913787/packages/pypi/simple \
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:
spack install tamaas
This will install an MPI-enabled version of tamaas with Scipy solvers. The
spack info tamaas shows the build variants. To disable MPI, you
should disable MPI in the FFTW variant:
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
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
- [py-mpi4py, py-netcdf4, tamaas@master+solvers]
- ["^openmpi@4 fabrics=ofi,psm2,ucx schedulers=none"]
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:
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:
docker run -v $PWD:/app -t tamaas python3 /app/your_script.py
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 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.
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:
docker build -t tamaas .
The following arguments can be passed to docker to customize the Tamaas
build (with the
--build-arg flag for
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:
singularity build tamaas.sif docker://registry.gitlab.com/tamaas/tamaas
To run the image with MPI:
mpirun singularity exec --home=$PWD tamaas.sif python3 <your_script>
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)
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)
On a HPC environment, use the following variables to specify where the dependencies are located:
You can use the provided Dockerfile to build an image with the external dependencies installed.
git clone --recursive https://gitlab.com/tamaas/tamaas.git
The build system uses SCons. In order to compile Tamaas with the default options:
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
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
-j n executes the build with
n threads and
-c cleans the
build). Note that the build is aware of the
Once compiled, you can install the python module with:
scons install prefix=/your/prefix
The above command automatically calls
pip if it is installed. If want to
install an editable package for development, the best practice is to run the
following in a virtual environment:
This is equivalent to running
pip install -e build-release/python[all]. You
can check that everything is working fine with:
python3 -c 'import tamaas; print(tamaas)'
Important build options
Here are a selected few important compilation options:
Controls the type of build, which essentially changes the optimisation level (
release) and the amount of debug information. Default type is
release. Accepted values are:
Compiler (uses the environment variable
Compiler flags (uses the environment variable
CXXFLAGSby default). Useful to add tuning flags (e.g.
-march=native -mtune=nativefor GCC or
-xHOSTfor Intel), or additional optimisation flags (e.g.
-fltofor link-time optimization).
Controls the Thrust parallelism backend. Defaults to
ompfor OpenMP. Accepted values are:
tbb(unsupported): Threading Building Blocks
Controls the FFTW thread model. Defaults to
ompfor OpenMP. Accepted values are:
Activates MPI-parallelism (boolean value).
More details on the above options can be found in 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:
surfacegenerates randomly rough surfaces (see Random rough surfaces)
contactsolves an elastic contact problem with a surface read from
stdin(see Solving contact)
plotplots the surface tractions and displacements read from
Here’s a sample command line for you to try out:
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:
Tests can then be run with the
scons test command. Make sure you have