diff --git a/CHANGELOG.md b/CHANGELOG.md index b45d1d1..30c64c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,172 +1,173 @@ # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## Unreleased ### Added - Entry-point `tamaas` defines a grouped CLI for `examples/pipe_tools`. Try executing `tamaas surface -h` from the command-line! ### Changed - `CXXFLAGS` are now passed to the linker - Added this changelog - Using absolute paths for environmental variables when running `scons test` - Reorganized documentation layout - Gave the build system a facelift (docs are now generated directly with SCons instead of a Makefile) ### Deprecated - Python 2 support is discontinued. Version `v2.2.1` is the last PyPi build with a Python 2 wheel. +- The scripts in `examples/pipe_tools` have been replaced by the `tamaas` command ## Fixed - `UVWDumper` no longer imports `mpi4py` in sequential - Compiling with different Thrust/FFTW backends ## v2.2.1 -- 2021-03-02 ### Added - Output registered fields and dumpers in `print(model)` - Added `operator[]` to the C++ model class (for fields) - Added `traction` and `displacement` properties to Python model bindings - Added `operators` property to Python model bindings, which provides a dict-like access to registered operators - Added `shape` and `spectrum` to properties to Python surface generator bindings - Surface generator constructor accepts surface global shape as argument - Choice of FFTW thread model ### Changed - Tests use `/tmp` for temporary files - Updated dependency versions (Thrust, Pybind11) ### Deprecated - Most `get___()` and `set___()` in Python bindings have been deprecated. They will generate a `DeprecationWarning`. ### Removed - All legacy code ## v2.2.0 -- 2020-12-31 ### Added - More accurate function for computation of contact area - Function to compute deviatoric of tensor fields - MPI implementation - Convenience `hdf5toVTK` function - Readonly properties `shape`, `global_shape`, `boundary_shape` on model to give shape information ### Changed - Preprocessor defined macros are prefixed with `TAMAAS_` - Moved `tamaas.to_voigt` to `tamaas.compute.to_voigt` ### Fixed - Warning about deprecated constructors with recent GCC versions - Wrong computation of grid strides - Wrong computation of grid sizes in views ## v2.1.4 -- 2020-08-07 ### Added - Possibility to generate a static `libTamaas` - C++ implementation of DFSANE solver - Allowing compilation without OpenMP ### Changed - NetCDF dumper writes frames to a single file ### Fixed - Compatibility with SCons+Python 3 ## v2.1.3 -- 2020-07-27 ### Added - Version number to `TamaasInfo` ### Changed - Prepending root directory when generating archive ## v2.1.2 -- 2020-07-24 This release changes some core internals related to discrete Fourier transforms for future MPI support. ### Added - Caching `CXXFLAGS` in SCons build - SCons shortcut to create code archive - Test of the elastic-plastic contact solver - Paraview data dumper (`.pvd` files) - Compression for UVW dumper - `__contains__` and `__iter__` Python bindings of model - Warning message of possible overflow in Kelvin ### Changed - Simplified `tamaas_info.cpp`, particularly the diff part - Using a new class `FFTEngine` to manage discrete Fourier transforms. Plans are re-used as much as possible with different data with the same shape. This is in view of future MPI developments - Redirecting I/O streams in solve functions so they can be used from Python (e.g. in Jupyter notebooks) - Calling `initialize()` and `finalize()` is no longer necessary ### Fixed - Convergence issue with non-linear solvers - Memory error in volume potentials ## v2.1.1 -- 2020-04-22 ### Added - SCons shortcut to run tests ### Fixed - Correct `RPATH` for shared libraries - Issues with SCons commands introduced in v2.1.0 - Tests with Python 2.7 ## v2.1.0 -- 2020-04-17 ### Added - SCons shortcuts to build/install Tamaas and its components - Selection of integration method for Kelvin operator - Compilation option to remove the legacy part of Tamaas - NetCDF dumper ### Fixed - Link bug with clang - NaNs in Kato saturated solver ## v2.0.0 -- 2019-11-11 First public release. Contains relatively mature elastic-plastic contact code. diff --git a/doc/sphinx/source/examples.rst b/doc/sphinx/source/examples.rst index a631d12..a6e8de8 100644 --- a/doc/sphinx/source/examples.rst +++ b/doc/sphinx/source/examples.rst @@ -1,43 +1,43 @@ Examples ======== The directory ``examples/`` in Tamaas' root repository contains example scripts dedicated to various aspects of Tamaas: ``statistics.py`` This script generates a rough surface and computes its power spectrum density as well as its autocorrelation function. ``rough_contact.py`` This script generates a rough surface and solves an adhesion-less elastic contact problem. ``adhesion.py`` This script solves a rough contact problem with an exponential energy functional for adhesion. It also shows how to derive an energy functional in python. ``saturation.py`` This script solves a saturated contact problem (i.e. pseudo-plasticity) with a rough surface. ``stresses.py`` This script solves an equilibrium problem with an eigenstrain distribution and a surface traction distribution and writes the output to a VTK file. It demonstrates how the integral operators that Tamaas uses internally for elastic-plastic contact can be used directly in Python. ``plasticity.py`` This script solves an elastoplastic Hertz contact problem with three load steps and writes the result to VTK files. ``pipe_tools/`` - This directory contains scripts that provide a simple interface to elastic - contact: + **Deprecated**, use the `tamaas` command instead. This directory + contains scripts that provide a simple interface to elastic contact: - Rough surface generation (``surface``) - Elastic contact solve (``contact``) - Plotting contact solution (``plot``) These can be composed together via standard UNIX pipes. Running them with the ``-h`` option describes all the options and required arguments. diff --git a/doc/sphinx/source/quickstart.rst b/doc/sphinx/source/quickstart.rst index 13f1420..8ad42f2 100644 --- a/doc/sphinx/source/quickstart.rst +++ b/doc/sphinx/source/quickstart.rst @@ -1,183 +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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In the ``examples/pipe_tools`` folder, you will find three scripts that can be -used to explore the mechanics of elastic rough contact: +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 a contact problem with a surface read from ``stdin`` (see - :doc:`contact`) -- ``plot`` simply plots the surface tractions and displacements read from +- ``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 - ./surface --cutoffs 2 4 64 --size 512 512 --hurst 0.8 | ./contact 1 | ./plot + tamaas surface --cutoffs 2 4 64 --size 512 512 --hurst 0.8 | tamaas contact 1 | tamaas plot -Check out the help of each script for a description of the arguments. +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.