Merge branch 'master' into 137-add-a-finite-volume-local-operator-for-the-richards-equation

.gitlab-ci.yml

@@ -10,7 +10,7 @@ variables:
   BASE_IMAGE: dorie/dune-env
   # Use semantic versioning (not the version of DUNE) and bump according to
   # to whether changes are backwards-compatible or not.
-  IMAGE_VERSION: "1.1"
+  IMAGE_VERSION: "1.2"
   DUNE_ENV_IMAGE: ${BASE_IMAGE}:img-v${IMAGE_VERSION}
 
   CMAKE_FLAGS:
@@ -69,6 +69,7 @@ setup:dune-env-clang:
 prep:update-dune: &update
   <<: *setup
   stage: prep
+  allow_failure: true
   only:
     - master
     - tags
@@ -97,6 +98,7 @@ build:system-tests: &build-tests
   script:
     - CMAKE_FLAGS="$CMAKE_FLAGS"
       $DUNECONTROL --only=dorie configure
+    - $DUNECONTROL --only=dorie make $MAKE_FLAGS dorie-rfg
     - $DUNECONTROL --only=dorie make $MAKE_FLAGS build_system_tests
     - $DUNECONTROL --only=dorie make doc
   artifacts:
@@ -122,6 +124,7 @@ build:debug: &debug
         -DCMAKE_BUILD_TYPE=Debug
         -DCMAKE_CXX_FLAGS_DEBUG='-Werror'"
       $DUNECONTROL --only=dorie configure
+    - $DUNECONTROL --only=dorie make $MAKE_FLAGS dorie-rfg
     - $DUNECONTROL --only=dorie make $MAKE_FLAGS build_unit_tests
 
 build:debug-clang:
@@ -135,6 +138,7 @@ build:debug-clang:
         -DCMAKE_CXX_COMPILER=clang++
         -DCMAKE_CXX_FLAGS_DEBUG='-Werror'"
       $DUNECONTROL --only=dorie configure
+    - $DUNECONTROL --only=dorie make $MAKE_FLAGS dorie-rfg
     - $DUNECONTROL --only=dorie make $MAKE_FLAGS build_unit_tests
 
 

CHANGELOG.md

@@ -40,6 +40,8 @@
 * Coupling between transient models for water flow and solute transport !96
 * Initial conditions generated from H5 input data !130
 * Generic Python VTK file reader !143
+* Parameterizations for hydrodynamic dispersion in solute transport !141
+* Generic Python VTK file reader !143, !150
 
 ### Changed
 * `Simulation` is renamed `RichardsSimulation` and moved to 
@@ -143,6 +145,8 @@
 * Specifying scaling field `extensions` and `offset` is now optional !133
 * Generalized initial condition specification in config file !129
 * Structure and setup of Sphinx user docs !126
+* Switch to stable `dune-randomfield` release branch !151, !153
+* System tests for executing `dorie pfg` module !153
 
 ### Fixed
 * Solver in `RichardsSimulation` was using the wrong time variable.

CMakeLists.txt

-cmake_minimum_required(VERSION 2.8.12)
-project(dorie CXX)
+cmake_minimum_required(VERSION 3.10)
+project(dorie C CXX)
 
 # set build type
 if(NOT CMAKE_BUILD_TYPE)

README.md

@@ -88,7 +88,7 @@ by CI tests.
 | [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) | master
+| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | releases/2.6
 
 
 #### Optional Packages
@@ -103,6 +103,9 @@ by CI tests.
 #### Step-by-step Instructions
 These instructions are suitable for a clean **Ubuntu** or **macOS** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
 
+Manual installations on macOS require installing HDF5 from source. This can
+be tricky, but the following instructions should work on a clean system.
+
 If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) on your machine, you don't need to install Python or Pip. Simply skip these packages when using the package managers for installing the software. However, notice the warnings when compiling DORiE below!
 
 1. **macOS** users need to start by installing the Apple Command Line Tools by executing
@@ -125,10 +128,33 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
     **macOS:**
 
         brew update
-        brew install cmake doxygen gcc libpng open-mpi muparser \
+        brew install cmake doxygen fftw gcc libpng open-mpi muparser \
                      pkg-config python3 superlu yaml-cpp
-        brew install hdf5 --with-mpi
-        brew install fftw --with-mpi
+
+2. **macOS only:** Install HDF5 with MPI support from source.
+
+    1. Download an archive of the
+    [HDF5 source code](https://www.hdfgroup.org/downloads/hdf5/source-code/),
+    and extract it.
+
+    2. Enter the extracted folder. In there, create a `build` directory, and
+    enter it:
+
+            mkdir build && cd build
+
+    3. Configure your build. If you followed the instructions above, the
+    OpenMPI C compiler is reachable via the command `mpicc`. If not, you have
+    to specify a full path to it. Use the option `prefix` to specify where
+    you want the package to be installed. This should *not* be a
+    system-reserved path like `/usr/local`, and *not* be located in a
+    sub-directory of the source code. Execute the configuration script:
+
+            ./../configure CC=mpicc --prefix=<hdf5-path> --enable-parallel
+
+    4. Build and install the library:
+
+            make && make install
+
 
 3. The parallel linear solver of DORiE can make use of the ParMETIS package. If you want to run DORiE in parallel on multiple processes, additionally install METIS and ParMETIS:
 
@@ -158,13 +184,21 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
 
     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.
 
-    **Warning:** Anacoda supplies its own version of HDF5 which is typically found first by CMake. If you have Anaconda installed on your machine, add
+    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,
+
+        -DHDF5_ROOT=/usr/
+
+    and on macOS, add
+
+        -DHDF5_ROOT=<hdf5-path>
 
-        HDF5_ROOT=/usr/local
+    to the `CMAKE_FLAGS` in the above command, replacing `<hdf5-path>` with the
+    path chosen as installation prefix when configuring HDF5.
 
-    to the `CMAKE_FLAGS` in the call to `dunecontrol` above.
 
-#### Experimental Features
+### Experimental Features
 The local operator implementing Richards equation's discretization supports
 multiple scheme settings. Setting these via the config file is disabled by
 default. You can enable this feature by reconfiguring DORiE with the CMake flag

cmake/modules/DorieMacros.cmake

-# find all required packages
-FIND_PACKAGE (HDF5 REQUIRED)
+# These macros check for the following packages, yielding the respective
+# targets
+#
+#   HDF5        ... hdf5
+#   yaml-cpp    ... yaml-cpp
+#   muparser    ... muparser::muparser
+#
+# All of these are required an will be autmatically linked to executables when
+# using the DorieTesting CMake macros.
+
+# Add CMake policy stack
+cmake_policy(PUSH)
+
+# Allow using `<Package>_ROOT` on CMake >3.12
+if(POLICY CMP0074)
+    cmake_policy(SET CMP0074 NEW)
+endif()
+
+# HDF5
+set(HDF5_PREFER_PARALLEL TRUE)
+find_package (HDF5 REQUIRED COMPONENTS C)
 if(NOT HDF5_IS_PARALLEL)
     message(SEND_ERROR "Parallel HDF5 must be installed!")
 endif()
-add_definitions(-DHDF5_PARALLEL)
 
-FIND_PACKAGE (FFTW REQUIRED)
-FIND_PACKAGE (SuperLU REQUIRED)
-FIND_PACKAGE (MPI REQUIRED)
+# Define a target because the CMake module does not
+add_library(hdf5 INTERFACE IMPORTED GLOBAL)
+
+# TODO: Use `target_XXX` functions after raising CMake requirements
+# Sanitize the definitions because we cannot use the proper CMake function...
+string(REPLACE -D "" HDF5_DEFINITIONS "${HDF5_DEFINITIONS}")
+# Set properties directly because of a bug in CMake 3.10
+set_target_properties(hdf5 PROPERTIES
+    INTERFACE_LINK_LIBRARIES "${HDF5_LIBRARIES}"
+    INTERFACE_INCLUDE_DIRECTORIES "${HDF5_INCLUDE_DIRS}"
+    INTERFACE_COMPILE_DEFINITIONS "${HDF5_DEFINITIONS};H5_HAVE_PARALLEL")
+
+# yaml-cpp
 find_package (yaml-cpp 0.5.2 REQUIRED)
-FIND_PACKAGE (muparser REQUIRED)
 
-FIND_PACKAGE (METIS)
-FIND_PACKAGE (ParMETIS)
+# muparser
+find_package (muparser REQUIRED)
 
-include_directories(${FFTW_INCLUDES}
-                    ${HDF5_INCLUDE_DIRS}
-                    ${YAML_CPP_INCLUDE_DIR})
+# Report the DUNE libs
+message (STATUS "DUNE Libraries: ${DUNE_LIBS}")
 
-list (APPEND DUNE_LIBS
-      ${FFTW_LIBRARIES}
-      ${HDF5_LIBRARIES}
-      ${YAML_CPP_LIBRARIES}
-      muparser::muparser)
-MESSAGE(STATUS "DUNE Libraries: ${DUNE_LIBS}")
+# Remove CMake policy stack
+cmake_policy(POP)
 
 # Add DORiE testing functions
 include(DorieTesting)

cmake/modules/DorieTesting.cmake

@@ -7,7 +7,8 @@ add_custom_target(unit_tests
 # Add the system test build target and test command
 add_custom_target(build_system_tests)
 add_custom_target(system_tests
-    COMMAND ctest --output-on-failure --exclude-regex ^ut.+$
+    COMMAND ctest
+            --output-on-failure --exclude-regex "^\\(ut.+\\|python_tests\\)$"
 )
 
 # create the mapping datafile as preparation for all tests
@@ -53,6 +54,9 @@ endfunction()
 #   tests within DORiE and adds flags for coverage reports. Notice that
 #   `dune_add_test` requires more parameters than this function alone.
 #
+#   The registered executable is automatically linked to the libraries DORiE
+#   DORiE depends on.
+#
 #   Use this function exactly like `dune_add_test`.
 #
 function(dorie_add_unit_test)
@@ -75,6 +79,8 @@ function(dorie_add_unit_test)
     endif()
 
     # add to build target and employ compile options
+    target_link_libraries(${UNIT_TEST_TARGET}
+        muparser::muparser hdf5 yaml-cpp spdlog)
     add_coverage_links(${UNIT_TEST_TARGET})
     add_dependencies(build_unit_tests ${UNIT_TEST_TARGET})
 endfunction()
@@ -129,6 +135,9 @@ endfunction()
 #   Use this function like `dune_add_system_test`, considering the options
 #   given above.
 #
+#   When registering a new executable (`TARGET` is not specified), this
+#   executable will be linked to the libraries DORiE depends on.
+#
 function(dorie_add_metaini_test)
     set(OPTIONS UNIT_TEST)
     set(SINGLE TARGET METAINI SCRIPT BASENAME CREATED_TARGETS)
@@ -177,9 +186,16 @@ function(dorie_add_metaini_test)
         SCRIPT ${SYSTEM_TEST_SCRIPT}
         CREATED_TARGETS created_targets
     )
+
     # report created targets to parent scope
     set(${SYSTEM_TEST_CREATED_TARGETS} ${created_targets} PARENT_SCOPE)
 
+    # Link to dependencies
+    if(NOT SYSTEM_TEST_TARGET)
+        target_link_libraries(${created_targets}
+            muparser::muparser hdf5 yaml-cpp spdlog)
+    endif()
+
     # add dependencies and flags
     if(SYSTEM_TEST_UNIT_TEST)
         add_coverage_links(${created_targets})

cmake/modules/FindFFTW.cmake

-# - Find the FFTW library
-#
-# Usage:
-#   find_package(FFTW [REQUIRED] [QUIET] )
-#     
-# It sets the following variables:
-#   FFTW_FOUND               ... true if fftw is found on the system
-#   FFTW_LIBRARIES           ... full path to fftw library
-#   FFTW_INCLUDES            ... fftw include directory
-#
-# The following variables will be checked by the function
-#   FFTW_USE_STATIC_LIBS    ... if true, only static libraries are found
-#   FFTW_ROOT               ... if set, the libraries are exclusively searched
-#                               under this path
-#   FFTW_LIBRARY            ... fftw library to use
-#   FFTW_INCLUDE_DIR        ... fftw include directory
-#
-
-#If environment variable FFTWDIR is specified, it has same effect as FFTW_ROOT
-if( NOT FFTW_ROOT AND ENV{FFTWDIR} )
-  set( FFTW_ROOT $ENV{FFTWDIR} )
-endif()
-
-# Check if we can use PkgConfig
-find_package(PkgConfig)
-
-#Determine from PKG
-if( PKG_CONFIG_FOUND AND NOT FFTW_ROOT )
-  pkg_check_modules( PKG_FFTW QUIET "fftw3" )
-endif()
-
-#Check whether to search static or dynamic libs
-set( CMAKE_FIND_LIBRARY_SUFFIXES_SAV ${CMAKE_FIND_LIBRARY_SUFFIXES} )
-
-if( FFTW_ROOT )
-
-  #find libs
-  find_library(
-    FFTW_LIB
-    NAMES "fftw3"
-    PATHS ${FFTW_ROOT}
-    PATH_SUFFIXES "lib" "lib64"
-    NO_DEFAULT_PATH
-  )
-
-  find_library(
-    FFTWF_LIB
-    NAMES "fftw3_mpi"
-    PATHS ${FFTW_ROOT}
-    PATH_SUFFIXES "lib" "lib64"
-    NO_DEFAULT_PATH
-  )
-
-  find_library(
-    FFTWL_LIB
-    NAMES "fftw3l"
-    PATHS ${FFTW_ROOT}
-    PATH_SUFFIXES "lib" "lib64"
-    NO_DEFAULT_PATH
-  )
-
-  #find includes
-  find_path(
-    FFTW_INCLUDES
-    NAMES "fftw3.h"
-    PATHS ${FFTW_ROOT}
-    PATH_SUFFIXES "include"
-    NO_DEFAULT_PATH
-  )
-
-else()
-
-  find_library(
-    FFTW_LIB
-    NAMES "fftw3"
-    PATHS ${PKG_FFTW_LIBRARY_DIRS} ${LIB_INSTALL_DIR}
-  )
-
-  find_library(
-    FFTWF_LIB
-    NAMES "fftw3_mpi"
-    PATHS ${PKG_FFTW_LIBRARY_DIRS} ${LIB_INSTALL_DIR}
-  )
-
-
-  find_library(
-    FFTWL_LIB
-    NAMES "fftw3l"
-    PATHS ${PKG_FFTW_LIBRARY_DIRS} ${LIB_INSTALL_DIR}
-  )
-
-  find_path(
-    FFTW_INCLUDES
-    NAMES "fftw3.h"
-    PATHS ${PKG_FFTW_INCLUDE_DIRS} ${INCLUDE_INSTALL_DIR}
-  )
-
-endif( FFTW_ROOT )
-
-set(FFTW_LIBRARIES ${FFTWF_LIB} ${FFTW_LIB})
-
-if(FFTWL_LIB)
-  set(FFTW_LIBRARIES ${FFTWL_LIB} ${FFTW_LIBRARIES})
-endif()
-
-set( CMAKE_FIND_LIBRARY_SUFFIXES ${CMAKE_FIND_LIBRARY_SUFFIXES_SAV} )
-
-MESSAGE(STATUS "Found FFTW library: ${FFTW_LIBRARIES}")
-
-include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(FFTW DEFAULT_MSG
-                                  FFTW_INCLUDES FFTW_LIBRARIES)
-
-mark_as_advanced(FFTW_INCLUDES FFTW_LIBRARIES)

cmake/modules/Findmuparser.cmake

-# - Find the muParser library
+# Find the muparser library
 #
 # Usage:
-#   find_package(muParser [REQUIRED] [QUIET] )
+#   find_package(muparser [REQUIRED] [QUIET] )
 #
 # Hints may be given by the (environment) variables
-#   MUPARSER_ROOT                ... Path to the installation library
+#   muparser_ROOT                ... Path to the installation library
 #
 # It sets the following variables:
-#   MUPARSER_FOUND               ... true if muParser is found on the system
-#   MUPARSER_LIBRARIES           ... full path to muParser library
-#   MUPARSER_INCLUDES            ... muParser include directory
+#   muparser_FOUND               ... true if muparser is found on the system
+#   muparser_LIBRARIES           ... full path to muparser library
+#   muparser_INCLUDES            ... muparser include directory
 #
 # It defines the following targets:
 #   muparser::muparser           ... muparser library to link against
 #
 
-find_library(MUPARSER_LIBRARY
-  NAMES muparser muparserd
-  HINTS ${MUPARSER_ROOT} ENV MUPARSER_ROOT
+find_library(muparser_LIBRARY
+    NAMES muparser muparserd
+    HINTS ${muparser_ROOT} ENV muparser_ROOT
 )
 
-find_path(MUPARSER_INCLUDE_DIR
-  muParserDef.h
-  HINTS ${MUPARSER_ROOT} ENV MUPARSER_ROOT
+find_path(muparser_INCLUDE_DIR
+    muParserDef.h
+    HINTS ${muparser_ROOT} ENV muparser_ROOT
 )
 
-mark_as_advanced(MUPARSER_INCLUDE_DIR MUPARSER_LIBRARY)
+mark_as_advanced(muparser_INCLUDE_DIR muparser_LIBRARY)
 
-find_package_handle_standard_args(MUPARSER
-  DEFAULT_MSG
-  MUPARSER_LIBRARY MUPARSER_INCLUDE_DIR)
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(muparser
+    DEFAULT_MSG
+    muparser_LIBRARY muparser_INCLUDE_DIR)
 
-if (MUPARSER_FOUND)
-    set(MUPARSER_LIBRARIES ${MUPARSER_LIBRARY} )
-    set(MUPARSER_INCLUDES ${MUPARSER_INCLUDE_DIR} )
+if (muparser_FOUND)
+    set(muparser_LIBRARIES ${muparser_LIBRARY} )
+    set(muparser_INCLUDES ${muparser_INCLUDE_DIR} )
 
     # add the target
     add_library(muparser::muparser SHARED IMPORTED)
     set_target_properties(muparser::muparser
-      PROPERTIES IMPORTED_LOCATION ${MUPARSER_LIBRARIES}
-                 INTERACE_INCLUDE_DIRECTORIES ${MUPARSER_INCLUDES}
+      PROPERTIES IMPORTED_LOCATION ${muparser_LIBRARIES}
+                 INTERACE_INCLUDE_DIRECTORIES ${muparser_INCLUDES}
     )
 endif()

doc/default_files/CMakeLists.txt

@@ -119,7 +119,7 @@ endfunction()
 # copy BC & parameter files
 file(COPY   2d_infiltr.bcdat 3d_infiltr.bcdat 
             2d_solute.bcdat 3d_solute.bcdat 
-            param.yml 
+            richards_param.yml  transport_param.yml
     DESTINATION .)
 
 # Random field generator

doc/default_files/common-parameters.xml

@@ -32,10 +32,15 @@ adding an empty line, make text **bold** or ``monospaced``.
 <dorie>
   <category name="simulation">
     <parameter name="mode">
-      <definition> Mode of simulation in DORiE. </definition>
+      <definition> Sets the simulation mode of DORiE. 
+        (``richards``) mode calculates the matric head with a
+        DG scheme and produce water fluxes with Raviart Thomas reconstruction.
+        (``richards+transport``) mode calculates (``richards``) mode and use 
+        the generated water flux and saturation at each step to calculate the 
+        solute transport model for unsaturated media with a DG scheme.
+        </definition>
       <suggestion> richards </suggestion>
       <values> richards, richards+transport </values>
-      <comment> richards, richards+transport </comment>
     </parameter>
   </category>
 

doc/default_files/param.yml

-volumes:
-  sand:
-    index: 0
-    type: MvG
-    parameters:
-      alpha: -2.3
-      n: 4.17
-      k0: 2.2E-5
-      theta_r: 0.03
-      theta_s: 0.31
-      tau: -1.1
-
-  silt:
-    index: 1
-    type: MvG
-    parameters:
-      alpha: -0.7
-      n: 1.3
-      k0: 1.0E-5
-      theta_r: 0.01
-      theta_s: 0.41
-      tau: 0.0
-
-scaling:
-  type: None

doc/default_files/richards-parameters.xml

@@ -227,6 +227,7 @@ adding an empty line, make text **bold** or ``monospaced``.
       <definition> YAML file containing the parameter definitions.
       </definition>
       <values> path </values>
+      <suggestion> richards_param.yml </suggestion>
     </parameter>
   </category>
 

doc/default_files/richards_param.yml

+volumes:
+  sand:
+    index: 0
+    richards: 
+      type: MvG
+      parameters:
+        alpha: -2.3
+        n: 4.17
+        k0: 2.2E-5
+        theta_r: 0.03
+        theta_s: 0.31
+        tau: -1.1
+      
+  silt:
+    index: 1
+    richards: 
+      type: MvG
+      parameters:
+        alpha: -0.7
+        n: 1.3
+        k0: 1.0E-5
+        theta_r: 0.01
+        theta_s: 0.41
+        tau: 0.0
+
+scaling:
+  type: None

doc/default_files/transport-parameters.xml

@@ -67,6 +6