The TS-GitLab will have to shut down towards the end of the year — please think about migrating your projects to GitLab.com or GitHub.
(This is still a very early message, meant to keep you informed. There will be more urgent ones in the future.)

Commit 76eb1f48 authored by Lukas Riedel's avatar Lukas Riedel

Merge branch '2.0-patch' into '2.0-stable'

Resolve "Patch Release: 2.0.1"

See merge request !212
parents 77874f2e 398432b2
......@@ -115,8 +115,6 @@ prep:update-dune-clang:
script:
- docker build -f docker/dune-env-update.dockerfile
--build-arg DUNE_ENV_IMAGE=${DUNE_ENV_IMAGE}-clang
--build-arg CC=clang
--build-arg CXX=clang++
--build-arg PROCNUM=$CPUS_DIND
-t ${DUNE_ENV_IMAGE}-clang .
- docker push ${DUNE_ENV_IMAGE}-clang
......
# DORiE Changelog
## 2.0.1 (2020-07-16)
### Changed
* Simplify installation instructions !205
### Fixed
* Ensure UTF-8 locale definition in Docker images !210
## 2.0.0 (2020-05-14)
### Added
......
......@@ -15,6 +15,7 @@ in the User Manual to dive right in!
* [Overview](#overview)
* [Installation](#installation-instructions)
* [Docker Image](#download-docker-image)
* [Dependencies](#dependencies)
* [Manual Installation](#manual-installation)
* [Recommended Tools](#recommended-third-party-software)
* [Documentation](#documentation)
......@@ -59,7 +60,8 @@ DORiE is a [DUNE](https://dune-project.org/) module and requires several other
DUNE modules as well as third party software packages. Installation can be
handled manually on your local machine, but we recommend using a pre-compiled
image for the deployment software [Docker](https://www.docker.com/) to
inexperienced users instead.
inexperienced users instead. Docker can also be used to create a development
environment without installing the dependencies on the host machine.
### Download Docker Image
......@@ -84,6 +86,78 @@ You can then proceed directly to the the instructions on
to the usual commands for running a Docker container. See the description on
Docker Hub for further details.
#### Use Docker for Development
An intermediate solution for creating a development environment without
installing all dependencies is using the
[DUNE environment Docker image](https://hub.docker.com/r/dorie/dune-env) of
DORiE. It is based on a Ubuntu image and contains all dependencies of DORiE.
Developers can clone the DORiE source code onto their host system, modify it
there and then mount the directory into the Docker image to compile the program.
To start a container from the image with the local `<dorie_dir>` mounted,
execute
docker run -it -v <dorie_dir>:/opt/dune/ dorie/dune-env:<tag>
Inside the container, you can then execute the `dunecontrol` script as explained
in the installation instructions further below.
### Dependencies
Depending on your system configuration, there will be more packages necessary to
install DORiE on your machine. See the step-by-step manual for further details.
The specified versions are the _supported_ ones, where compatibility is ensured
by CI tests.
#### DUNE Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.6
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.6
| [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) | releases/2.6
| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.6
| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.6
| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.6
| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.6
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.6
| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | releases/2.6
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | *Optional:* For system tests
#### DUNE Requirements
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| CMake | 3.10.2 |
| GCC | 7.3 | Alternatively: LLVM Clang >=6, or Apple Clang 10
| git |
| pkg-config |
| FFTW3 | 3.3.7 | MPI support required
| Python | 3.6 |
| pip | 3.6 |
| MPI | | Tested with OpenMPI 2.1.1
| SuperLU | 5.2 |
#### DORiE Requirements
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required
| [yaml-cpp](https://github.com/jbeder/yaml-cpp) | >= 5.2.0 |
| [muparser](http://beltoforion.de/article.php?a=muparser) | master |
| [VTK](https://vtk.org/) | >= 7.1.1 | For the Python module only
| [spdlog](https://github.com/gabime/spdlog) | 1.5.0 | Included as Git Submodule
| [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule
#### Optional Packages
| Software | Version/Branch | Comments |
| -------- | -------------- | -------- |
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation
| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs
### Manual Installation
Installing all packages manually can be quite an effort, but useful for
......@@ -119,7 +193,7 @@ notice the warnings when compiling DORiE below!
executing
xcode-select --install
Make sure you have no pending software updates for your respective version
of macOS!
......@@ -177,41 +251,56 @@ notice the warnings when compiling DORiE below!
**Parallel runs without these two packages are possible but not supported!**
4. Clone the [DUNE modules](#dune-Packages) into a suitable folder on your
machine. Use `git checkout` to switch to the correct branches.
4. Create a directory for all your DUNE modules, including DORiE. If you already
cloned DORiE somewhere else, move the cloned folder into the DUNE module
directory.
5. Clone the [DUNE modules](#dune-Packages) into the DUNE module directory. Use
`git checkout` to switch to the correct branches. We provide a bash script
which clones all required repositories and checks out the correct branches
into the directory it is executed from. Move into the DUNE module folder and
execute it:
5. Clone DORiE into the same folder.
bash dorie/clone_dune
DORiE includes
[Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules),
which requires you to add the `--recurse-submodules` option to the
`git clone` command. Switch to the desired branch or tag.
6. Make sure the DORiE repository is correctly set up. DORiE includes
[Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules),
which are only downloaded if you add the `--recurse-submodules` option to the
`git clone` command. To make sure the submodules are cloned and checked out,
enter the DORiE repository and execute
6. Enter the parent folder, and call
git submodule init && git submodule update
CMAKE_FLAGS="-DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" ./dune-common/bin/dunecontrol all
6. Enter the DUNE module directory, and call
./dune-common/bin/dunecontrol --opts=dorie/build.opts all
to build all DUNE modules. Additionally, you can add `MAKE_FLAGS="-j X"`
to the command in order to compile on `X` processes in parallel.
If you installed software into paths not appended to your `PATH` variable,
you will have to add `CMAKE_FLAGS` to the call to make sure that CMake
finds all packages. Alternatively, you can add a custom options file. See
the [DUNE Installation Instructions](https://dune-project.org/doc/installation/)
for details. CMake will throw an error if required packages are not found.
The `build.opts` file in this repository contains required and useful CMake
variable settings for a build of DORiE. If you installed software into paths
not appended to your `PATH` variable, you will have to add more
`CMAKE_FLAGS` in the options file to make sure that CMake finds all
packages. If `<Package>_ROOT` variables suffice, you can simply prepend them
before the `dunecontrol` command. See the
[Dune Installation Docs](https://www.dune-project.org/doc/installation/) for
further information.
If you installed HDF5 from source (all **macOS** users) or use Anaconda,
specify the path to your HDF5 installation by using the `HDF5_ROOT`
variable. On Ubuntu, add the path to the APT package,
environment variable. On Ubuntu, prepend the path to the APT package,
-DHDF5_ROOT=/usr/
HDF5_ROOT=/usr/
and on macOS, add
and on macOS, prepend
-DHDF5_ROOT=<hdf5-path>
HDF5_ROOT=<hdf5-path>
to the `CMAKE_FLAGS` in the above command, replacing `<hdf5-path>` with the
path chosen as installation prefix when configuring HDF5.
in the `dunecontrol` command above, replacing `<hdf5-path>` with the
path chosen as installation prefix when configuring HDF5. Alternatively,
`export` these paths in your shell before calling `dunecontrol`, or add
them as CMake variables (with prefix `-D`) to the repository options file.
### Recommended Third-Party Software
......@@ -223,62 +312,6 @@ find a release that fits your operating system:
* [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the
`.msh` files used by DORiE to define unstructured meshes.
### Dependencies
Depending on your system configuration, there will be more packages necessary to
install DORiE on your machine. See the step-by-step manual for further details.
The specified versions are the _supported_ ones, where compatibility is ensured
by CI tests.
#### DUNE Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.6
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.6
| [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) | releases/2.6
| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.6
| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.6
| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.6
| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.6
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.6
| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | releases/2.6
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | *Optional:* For system tests
#### DUNE Requirements
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| CMake | 3.10.2 |
| GCC | 7.3 | Alternatively: LLVM Clang >=6, or Apple Clang 10
| git |
| pkg-config |
| FFTW3 | 3.3.7 | MPI support required
| Python | 3.6 |
| pip | 3.6 |
| MPI | | Tested with OpenMPI 2.1.1
| SuperLU | 5.2 |
#### DORiE Requirements
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required
| [yaml-cpp](https://github.com/jbeder/yaml-cpp) | >= 5.2.0 |
| [muparser](http://beltoforion.de/article.php?a=muparser) | master |
| [VTK](https://vtk.org/) | >= 7.1.1 | For the Python module only
| [spdlog](https://github.com/gabime/spdlog) | 1.5.0 | Included as Git Submodule
| [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule
#### Optional Packages
| Software | Version/Branch | Comments |
| -------- | -------------- | -------- |
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation
| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs
## Documentation
The documentation of DORiE is twofold. The Sphinx documentation contains a
......@@ -407,9 +440,11 @@ If the problem persists, take a look at the
and feel free to create an Issue yourself if the problem is not yet reported.
### Debugging
DORiE can be built with debugging flags via CMake. To do so, run
DORiE can be built with debugging flags via CMake. To do so, enter the
`build-cmake` directory and execute
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Debug" dunecontrol --only=dorie all
cmake -DCMAKE_BUILD_TYPE=Debug ..
make all
After building, a debugger can hook into the executables.
......@@ -421,7 +456,11 @@ CMake.
To re-create a release build, configure DORiE with the release build type by
executing
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release" dunecontrol --only=dorie all
cmake -DCMAKE_BUILD_TYPE=Release ..
make all
or by calling `dunecontrol` with the supplied options file as indicated in the
installation instructions above.
### Running System Tests
DORiE includes a testing system for comparing its results the ones of ODE
......
# NOTE: If you want to update this file with options for your own setup, create
# a copy of it. Make sure you *do not* commit any changes specific to your
# setup to the original file!
# CMake configuration options
# - Default build type: Release
# - Create virtual environment in dune-common
# - Fetch pip and install it into virtual environment
# - Prefer parallel over sequential HDF5 (required for Ubuntu/Debian)
CMAKE_FLAGS="
-DCMAKE_BUILD_TYPE=Release
-DDUNE_PYTHON_VIRTUALENV_SETUP=True
-DDUNE_PYTHON_ALLOW_GET_PIP=True
-DHDF5_PREFER_PARALLEL=True
"
#!/usr/bin/env bash
# Abort script on command failure
set -e
echo "=== Cloning DUNE modules into $(pwd) ==="
DEFAULT_BRANCH="releases/2.6"
git clone https://gitlab.dune-project.org/staging/dune-uggrid.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/oklein/dune-randomfield.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/core/dune-common.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/core/dune-geometry.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/core/dune-grid.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/core/dune-istl.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/core/dune-localfunctions.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/staging/dune-functions.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/pdelab/dune-pdelab.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/staging/dune-typetree.git -b $DEFAULT_BRANCH
git clone https://gitlab.dune-project.org/quality/dune-testtools.git -b $DEFAULT_BRANCH
......@@ -82,6 +82,26 @@ the Richards solver must be utilized to solve them. Use the value
``richards+transport`` in the ``simulation.mode`` keyword to run the solute
transport solver.
Advanced Solver Features
========================
* **Unstructured Grids**: The DG scheme of DORiE can be applied onto any grid
geometry. Users can load unstructured simplex grids into DORiE via GMSH
``.msh`` files. DORiE will then use an unstructured grid manager. See
:doc:`/manual/grid` for details.
* **Adaptive Grid Refinement** (h-refinement): DORiE supports adaptive local
grid refinement based on an a-posteriori flux error estimator. Enabling grid
refinement requires using an unstructured grid manager. Adaptivity can be
enabled by setting a refinement policy in the
:doc:`Configuration File </manual/config-file>`.
* **Parallel Execution:** DUNE modules are generally set up to support parallel
execution on distributed hardware via MPI. DORiE supports parallel execution
on a best effort basis. This feature is currently only supported for
structured rectangular grids. Parallel execution is controlled through the
:ref:`Command Line Interface <man-cli-commands>`.
Available Models
================
......@@ -92,21 +112,27 @@ combinations users may choose from via the
Docker image or with the default targets built locally on your machine, these
are the available combinations of options:
+----------------------+-------------------+-----------------------------+------------------------------+----------------+
|``simulation.mode`` |``grid.dimensions``|``richards.numerics.FEorder``|``transport.numerics.FEorder``| GMSH Grid and |
| | | | | grid refinement|
+======================+===================+=============================+==============================+================+
|``richards`` | 2 | <= 3 | ✗ | ✓* |
| +-------------------+-----------------------------+------------------------------+----------------+
| | 3 | <= 1 | ✗ | ✓* |
+----------------------+-------------------+-----------------------------+------------------------------+----------------+
|``richards+transport``| 2 | <= 3 | same as ``richards`` | ✓*\ :sup:`†` |
| +-------------------+-----------------------------+------------------------------+----------------+
| | 3 | <= 1 | same as ``richards`` | ✓*\ :sup:`†` |
+----------------------+-------------------+-----------------------------+------------------------------+----------------+
* *: Only for ``richards.numerics.FEorder`` > 0. Finite volume solvers do not
support unstructured grids.
+----------------------+-------------------+-----------------------------+------------------------------+----------------+---------------------+
|``simulation.mode`` |``grid.dimensions``|``richards.numerics.FEorder``|``transport.numerics.FEorder``| GMSH Grid and | Parallel |
| | | | | grid refinement| execution |
+======================+===================+=============================+==============================+================+=====================+
|``richards`` | 2 | 0 | ✗ | ✗ | ✓ |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 2 | 1..3 | ✗ | ✓ | on structured grids |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 3 | 0 | ✗ | ✗ | ✓ |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 3 | 1 | ✗ | ✓ | on structured grids |
+----------------------+-------------------+-----------------------------+------------------------------+----------------+---------------------+
|``richards+transport``| 2 | 0 | same as ``richards`` | ✗ | ✓ |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 2 | 1..3 | same as ``richards`` | ✓\ :sup:`†` | on structured grids |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 3 | 0 | same as ``richards`` | ✗ | ✓ |
| +-------------------+-----------------------------+------------------------------+----------------+---------------------+
| | 3 | 1 | same as ``richards`` | ✓\ :sup:`†` | on structured grids |
+----------------------+-------------------+-----------------------------+------------------------------+----------------+---------------------+
* :sup:`†`: Grid refinement on *rectangular* grids produces hanging nodes which
are currently not considered in the
:ref:`flux reconstruction <man-flux_reconstruction>`. This can result in
......
......@@ -9,9 +9,6 @@ LABEL maintainer="lriedel@iup.uni-heidelberg.de"
# number of cores for parallel builds
ARG PROCNUM=1
# Compilers to be used
ARG CC=gcc
ARG CXX=g++
# copy the build context to this image
WORKDIR /opt/dune/dorie
......@@ -20,8 +17,7 @@ COPY ./ ./
# build the executable
WORKDIR /opt/dune/
RUN MAKE_FLAGS="-j${PROCNUM}" \
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=${CC} -DCMAKE_CXX_COMPILER=${CXX} -DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" \
./dune-common/bin/dunecontrol --only=dorie all
./dune-common/bin/dunecontrol --opts=dorie/build.opts --only=dorie all
# Start a fresh image as production environment
FROM $DUNE_ENV_IMAGE as prod-env
......
......@@ -6,13 +6,20 @@ LABEL maintainer="lriedel@iup.uni-heidelberg.de"
# number of cores for parallel builds
ARG PROCNUM=1
# Compilers to be used
ARG CC=gcc
ARG CXX=g++
RUN apt-get clean && apt-get update && apt-get upgrade -y && apt-get clean
# Upgrade Ubuntu packages
# NOTE: "localedef" is required in case "locale" package is updated
RUN apt-get clean \
&& apt-get update \
&& apt-get upgrade -y \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/* \
&& localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
ENV LANG en_US.utf8
# Update and build DUNE modules
WORKDIR /opt/dune
COPY build.opts ./
RUN ./dune-common/bin/dunecontrol update
RUN MAKE_FLAGS="-j ${PROCNUM}" \
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=${CC} -DCMAKE_CXX_COMPILER=${CXX} -DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" \
./dune-common/bin/dunecontrol all
./dune-common/bin/dunecontrol --opts=build.opts all
......@@ -6,6 +6,9 @@ ARG PROCNUM=1
ARG CC=gcc
ARG CXX=g++
# Pass compilers as environment variables (will persist in other images)
ENV CC=$CC CXX=$CXX
# disable any prompts while installing packages
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get clean \
......@@ -37,26 +40,18 @@ RUN apt-get clean \
python3-dev \
python3-pip \
python3-vtk7 \
&& apt-get clean
RUN rm -rf /var/lib/apt/lists/* \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/* \
&& localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
ENV LANG en_US.utf8
WORKDIR /opt/dune
RUN git clone https://gitlab.dune-project.org/staging/dune-uggrid.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/oklein/dune-randomfield.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/core/dune-common.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/core/dune-geometry.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/core/dune-grid.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/core/dune-istl.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/core/dune-localfunctions.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/staging/dune-functions.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/pdelab/dune-pdelab.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/staging/dune-typetree.git -b releases/2.6 \
&& git clone https://gitlab.dune-project.org/quality/dune-testtools.git -b releases/2.6
WORKDIR /opt/dune
# Clone DUNE modules
COPY clone_dune ./
RUN bash clone_dune
# Configure and build DUNE modules
COPY build.opts ./
RUN MAKE_FLAGS="-j ${PROCNUM}" \
CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=${CC} -DCMAKE_CXX_COMPILER=${CXX} -DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" \
./dune-common/bin/dunecontrol all
./dune-common/bin/dunecontrol --opts=build.opts all
......@@ -4,7 +4,7 @@
#Name of the module
Module: dorie
Version: 2.0.0
Version: 2.0.1
Maintainer: dorieteam@iup.uni-heidelberg.de
#depending on
Depends: dune-pdelab dune-uggrid dune-randomfield
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment