...
 
Commits (81)
......@@ -3,6 +3,8 @@ build-cmake/
# Exclude generated files
doc/manual/config-file.rst
doc/default_files/config.ini
doc/cookbook/1-infiltration-sand/config.ini
python/dorie/wrapper/pf_from_file.py
python/dorie/wrapper/test_dorie.py
python/dorie/dorie/cli/cmds.py
......
......@@ -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.2"
IMAGE_VERSION: "1.3"
DUNE_ENV_IMAGE: ${BASE_IMAGE}:img-v${IMAGE_VERSION}
CMAKE_FLAGS:
......@@ -22,11 +22,38 @@ variables:
-j $CPUS_MULTICORE
RUN_IN_DUNE_ENV: $CI_PROJECT_DIR/build-cmake/run-in-dune-env
# Documentation server configuration
DOC_HOST: root@hermes.iup.uni-heidelberg.de
DOC_PORT: 2345 # ... forwards to utopia_doc_server container. root ok ;)
DOC_REMOTE_BASE_DIR: /var/dorie_doc
DOC_REMOTE_PATH: $DOC_REMOTE_BASE_DIR/$CI_COMMIT_REF_SLUG
image: $DUNE_ENV_IMAGE
before_script:
- cd /opt/dune
# Provide SSH access via the SSH_PRIVATE_KEY and SSH_KNOWN_HOSTS variables
.ssh-access: &ssh_access
before_script:
# Run ssh-agent (inside the build environment)
- eval $(ssh-agent -s)
# Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
# We're using tr to fix line endings which makes ed25519 keys work
# without extra base64 encoding.
# https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
# Create the SSH directory and give it the right permissions
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
# Add the known hosts lists to ensure this ssh connection is the right one
- echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
- chmod 644 ~/.ssh/known_hosts
stages:
- setup
- prep
......@@ -100,7 +127,6 @@ build:system-tests: &build-tests
$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:
name: "$CI_JOB_NAME"
paths:
......@@ -126,6 +152,7 @@ build:debug: &debug
$DUNECONTROL --only=dorie configure
- $DUNECONTROL --only=dorie make $MAKE_FLAGS dorie-rfg
- $DUNECONTROL --only=dorie make $MAKE_FLAGS build_unit_tests
- $DUNECONTROL --only=dorie make $MAKE_FLAGS richards_d2_r1 transport_d2_r0_t0
build:debug-clang:
<<: *debug
......@@ -140,7 +167,19 @@ build:debug-clang:
$DUNECONTROL --only=dorie configure
- $DUNECONTROL --only=dorie make $MAKE_FLAGS dorie-rfg
- $DUNECONTROL --only=dorie make $MAKE_FLAGS build_unit_tests
- $DUNECONTROL --only=dorie make $MAKE_FLAGS transport_d2_r0_t0 transport_d2_r1_t0
build:docs:
stage: build
script:
- CMAKE_FLAGS="$CMAKE_FLAGS"
$DUNECONTROL --only=dorie configure
- $DUNECONTROL --only=dorie make doc
artifacts:
name: "$CI_JOB_NAME"
paths:
- $CI_PROJECT_DIR/build-cmake/doc
expire_in: 1 day
# --- Tests ---
test:system-tests: &test
......@@ -212,9 +251,12 @@ deploy:dockerhub-devel: &deploy
- $DOCKER_LOGIN
script:
- docker build -f docker/dorie.dockerfile
--build-arg DUNE_ENV_IMAGE=$DUNE_ENV_IMAGE --build-arg PROCNUM=$CPUS_DIND
--build-arg BASE_IMG_VERSION=$IMAGE_VERSION --build-arg PROCNUM=$CPUS_DIND
-t dorie/dorie:devel .
- docker push dorie/dorie:devel
environment:
name: docker/devel
url: https://hub.docker.com/r/dorie/dorie
deploy:dockerhub-stable:
<<: *deploy
......@@ -222,29 +264,55 @@ deploy:dockerhub-stable:
- tags@dorie/dorie
script:
- docker build -f docker/dorie.dockerfile
--build-arg DUNE_ENV_IMAGE=$DUNE_ENV_IMAGE --build-arg PROCNUM=$CPUS_DIND
--build-arg BASE_IMG_VERSION=$IMAGE_VERSION --build-arg PROCNUM=$CPUS_DIND
-t dorie/dorie:$CI_COMMIT_TAG .
- docker push dorie/dorie:$CI_COMMIT_TAG
environment:
name: docker/$CI_COMMIT_TAG
url: https://hub.docker.com/r/dorie/dorie
deploy:sphinx-docs:
deploy:docs:
stage: deploy
only:
- tags@dorie/dorie
- branches@dorie/dorie
dependencies:
- build:system-tests
before_script:
# install the netfly CLI
- apt-get install -y golang-go golang-glide
- go get -d github.com/netlify/netlifyctl
- cd $HOME/go/src/github.com/netlify/netlifyctl/
- make deps build
- go install
- cd $HOME/go/bin
script:
- ./netlifyctl deploy
-A $NETFLY_DEPLOY_TOKEN
-s $NETFLY_SITE_ID
-P $CI_PROJECT_DIR/build-cmake/doc/html
- build:docs
needs: ["build:docs"]
<<: *ssh_access
script:
# Create the directory on the remote, removing any prior version
- echo "Creating remote directory $DOC_REMOTE_PATH ..."
- ssh -p $DOC_PORT $DOC_HOST "rm -rf $DOC_REMOTE_PATH"
- ssh -p $DOC_PORT $DOC_HOST "mkdir -p $DOC_REMOTE_PATH/doxygen/"
# Copy sphinx & doxygen HTML documentation to remote
- cd build-cmake/doc
- echo "Uploading documentation to $DOC_REMOTE_PATH/ ..."
- scp -P $DOC_PORT -pr html $DOC_HOST:$DOC_REMOTE_PATH/
- scp -P $DOC_PORT -pr doxygen/html $DOC_HOST:$DOC_REMOTE_PATH/doxygen/
environment:
name: docs/$CI_COMMIT_REF_NAME
url: https://hermes.iup.uni-heidelberg.de/dorie_doc/$CI_COMMIT_REF_SLUG/html/
on_stop: deploy:stop_docs
# This job is called when the environment is stopped, which automatically
# happens when the respective branch is deleted
deploy:stop_docs:
stage: deploy
when: manual
variables:
# Stop GitLab from checking out the commit again (branch is deleted)
GIT_STRATEGY: none
dependencies: []
needs: ["build:docs"]
<<: *ssh_access
script:
- echo "Removing remote directory $DOC_REMOTE_PATH ..."
- ssh -p $DOC_PORT $DOC_HOST "rm -rf $DOC_REMOTE_PATH"
environment:
name: sphinx-docs
url: https://dorie-doc.netlify.com/
name: docs/$CI_COMMIT_REF_NAME
action: stop
(One-sentence description of what kind of bug you would like to report)
_One-sentence description of what kind of bug you would like to report_
#### Summary
(Summarise the encountered bug concisely)
### Summary
_Summarise the encountered bug concisely_
#### Steps to reproduce
(How can this be reproduced? If you can, point to specific files/configurations where the bug occurs)
### Steps to reproduce
_How can this be reproduced? If you can, point to specific files/configurations where the bug occurs_
#### What is the current _bug_ behaviour?
(More about the behaviour of the bug)
### What is the current _bug_ behaviour?
_More about the behaviour of the bug_
#### What is the expected _correct_ behaviour?
(Which behaviour would you have expected?)
### What is the expected _correct_ behaviour?
_Which behaviour would you have expected?_
#### Relevant logs, screenshots, files...?
(Anything that helps reproducing the bug)
### Relevant logs, screenshots, files...?
_Anything that helps reproducing the bug_
<!-- Put very long log outputs within the <pre></pre> tags below -->
<!-- If this doesn't apply, delete the whole <details></details> block -->
......@@ -28,8 +28,21 @@
</pre>
</details>
#### Reproducing input
_Do you have input files reproducing the problem? Insert them here:_
#### Ideas how to fix this?
(Add them here, if you have any.)
| Input data | |
| - | - |
| Simulation Case | _Description goes here_ |
| PFG config file | _if any_ |
| Grid mapping file | _if any_ |
| GMSH grid file | _if any_ |
| Boundary Condition file | |
| Parameterization file | |
| Run config file | |
/label ~bug
\ No newline at end of file
### Ideas how to fix this?
_Add them here, if you have any._
/label ~Bug
<!-- _Set the title to: "Patch Release: X.Y.Z" -->
<!-- Replace X.Y.Z with the actual version numbers everywhere -->
We're releasing patch version `X.Y.Z` for branch `X.Y-stable`! :tada:
### 1 — List of MRs to be Included
List the MRs and the commit SHA of their respective merge commits here.
Placing them in chronological order here ensures fewer issues when
cherry-picking them!
The MRs are indicated by the ~"Pick into X.Y" label.
| MR | Merge Commit SHA |
| -- | ---------------- |
| ! | ... |
### 2 — On GitLab
Use the "patch-release" template for creating a new Merge Request.
- [ ] [Create a branch][new branch] `X.Y-patch` from `X.Y-stable`
- [ ] [Create a Merge Request][new mr] with source branch `X.Y-patch` and
target branch `X.Y-stable`: !
- [ ] Merge this MR: !
- [ ] [Create tag][new tag] `X.Y.Z` from branch `X.Y-stable`
- Message:
```
Version X.Y.Z (YYYY-MM-DD)
```
- Release Notes:
```
# Version X.Y.Z (YYYY-MM-DD)
-> Copy appropriate entries from MR changelog here <-
```
- [ ] Update "Release" [project badge][badge] <!-- only if applicable -->
### 3 — On Docker Hub
- [ ] Update [description on DockerHub][DockerHub description]
- [ ] Push new `latest` tag to DockerHub <!-- only if applicable -->
### 4 — All done? :white_check_mark:
Close this issue!
/label ~Release
[new branch]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/branches/new
[new mr]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/merge_requests/new
[new tag]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/tags/new
[changelog]: (https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/CHANGELOG.md)
[DockerHub description]: https://hub.docker.com/r/dorie/dorie
[badge]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/edit
......@@ -8,7 +8,7 @@
### Related issues
See #...
See #
<!--
PLEASE READ THIS
......
<!-- _Set the title to: "Release: X.Y.0" -->
<!-- Replace X.Y with the actual version numbers everywhere -->
We're rolling out version `X.Y.0`! :tada:
### 1 — In the Code
- [ ] `master`: Update version numbers in `VERSION`, `CHANGELOG.md`,
`dune.module` to `X.Y.0`.
### 2 — On GitLab
- [ ] [Create branch][new branch] `X.Y-stable` from `master`
- [ ] [Create label][new label] ~"Pick into X.Y"
- [ ] [Create tag][new tag] `X.Y.0` from branch `X.Y-stable`
- Message:
```
Version X.Y.0 (YYYY-MM-DD)
```
- Release Notes:
```
# Version X.Y.0 (YYYY-MM-DD)
-> Insert version changelog here! <-
```
Shortcut to the most up-to-date [CHANGELOG.md][changelog]
- [ ] Update "Release" [project badge][badge] <!-- only if applicable -->
### 3 — In the Code
- [ ] `master`: Update version numbers in `VERSION`, `CHANGELOG.md`,
`dune.module` to `X.Y+1-pre`.
### 4 — On Docker Hub
- [ ] Update [description on DockerHub][DockerHub description]
- [ ] Push new `latest` tag to DockerHub <!-- only if applicable -->
### 5 — All done? :white_check_mark:
Close this issue!
/label ~Release
[new branch]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/branches/new
[new tag]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/tags/new
[changelog]: (https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/blob/master/CHANGELOG.md)
[new label]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/-/labels/new
[DockerHub description]: https://hub.docker.com/r/dorie/dorie
[badge]: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/edit
### What does this MR do?
_Fill this in_
### Is there something that needs to be double checked?
<!-- Is there something a reviewer should look out for _especially_? -->
_Fill this in_
### Can this MR be accepted?
- [ ] Implemented ...
- [ ] Added test to ...
- ...
- [ ] Pipeline passing
- [ ] ...
- [ ] Added/Updated tests:
- [ ] ...
- [ ] Added/Updated documentation
- [ ] Pipeline passing <!-- please check for new warnings -->
- [ ] Squash option set <!-- unless there's a good reason -->
- [ ] Delete branch option set <!-- unless there's a good reason -->
- [ ] Added entry to `CHANGELOG.md`
### Related issues
Closes #, # and #
Closes #
<!-- For automatic closing, do not forget the commas between issue numbers-->
......
<!-- _Set the title to: "Resolve "Patch Release: X.Y.Z"" -->
<!-- Replace X.Y.Z with the actual version numbers everywhere -->
We're releasing patch version `X.Y.Z` for branch `X.Y-stable`! :tada:
### Release Issue
<!-- DO NOT use automatic Issue resolution here! -->
The MRs to be considered in this update are listed in #
### Tasks
- [ ] Cherry-pick the listed commits into `X.Y-patch`
- [ ] `CHANGELOG.md`: Move appropriate entries into new section
- [ ] Update version numbers in `VERSION`, `CHANGELOG.md`, `dune.module`
#### Help on Cherry-Picking
Cherry-picking merge commits requires specifying the "mainline" parent, which
should always be number 1. Append a line indicating a cherry-pick to the commit
message with the `-x` argument. The following should do the trick:
```bash
git cherry-pick -m 1 -x <commits>
```
Replace `<commits>` with the Commit SHAs listed above, separated by a single
whitespace each. Make sure they are in chronological order to reduce the
number of merge conflicts! Fix such conflicts as unintrusively as possible.
### Can this MR be merged?
- [ ] Pipeline passing <!-- please check for new warnings -->
- [ ] Delete branch option set <!-- unless there's a good reason -->
### Related Issues
[submodule "plugins/vendor/spdlog"]
path = plugins/vendor/spdlog
url = https://github.com/gabime/spdlog.git
[submodule "plugins/vendor/googletest"]
path = plugins/vendor/googletest
url = https://github.com/google/googletest.git
This diff is collapsed.
......@@ -14,12 +14,6 @@ endif()
# add extra flags to debug compiler flags
set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wall")
# option to change DG scheme via config file
option(EXPERIMENTAL_DG_FEATURES
"Enable experimental DG settings through the config file"
OFF
)
#
if(NOT (dune-common_DIR OR dune-common_ROOT OR
"${CMAKE_PREFIX_PATH}" MATCHES ".*dune-common.*"))
......@@ -40,6 +34,10 @@ dune_project()
dune_enable_all_packages()
dune_require_cxx_standard(MODULE "dorie" VERSION 14)
# Cache the executable path
set(DORIE_EXE_PATH ${PROJECT_BINARY_DIR}/dune/dorie/
CACHE STRING "Path to the directory containing the executables")
# add subdirectories
add_subdirectory("plugins/vendor")
add_subdirectory("m4")
......@@ -48,8 +46,9 @@ add_subdirectory("python")
add_subdirectory("doc")
add_subdirectory("dune")
add_subdirectory("lib")
if(dune-testtools_FOUND)
if(DORIE_TESTING)
add_subdirectory("test")
add_subdirectory("doc/cookbook")
endif()
# finalize the dune project, e.g. generating config.h etc.
......
......@@ -77,6 +77,7 @@ by CI tests.
| SuperLU | 5.2 |
| [yaml-cpp](https://github.com/jbeder/yaml-cpp) | >= 5.2.0 |
| [spdlog](https://github.com/gabime/spdlog) | 1.1.0 | Included as Git Submodule
| [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule
| [muparser](http://beltoforion.de/article.php?a=muparser) | master |
| [VTK](https://vtk.org/) | >= 7.1.1 | For the Python module only
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
......@@ -94,7 +95,7 @@ by CI tests.
#### Optional Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | Handles system tests
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | Required for tests and parts of the user manual
| [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
......@@ -198,16 +199,6 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
path chosen as installation prefix when configuring HDF5.
### 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
`-DEXPERIMENTAL_DG_FEATURES=On`, and rebuilding it.
The configuration settings in the section `[dg.experimental]` will then override
the default settings.
### Recommended Third-Party Software
The following software packages are cross-platform, so you should be able to find a release that fits your operating system:
......@@ -219,9 +210,16 @@ The following software packages are cross-platform, so you should be able to fin
### Documentation
The documentation of the latest release branch can be found [online](https://dorie-doc.netlify.com/).
The documentation of active branches is automatically deployed to our server.
You will find the latest [user manual](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/)
and [C++ code documentation](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/doxygen/html/)
there. The documentation for other branches can be accessed via the
[overview page](https://hermes.iup.uni-heidelberg.de/dorie_doc/).
The documentation can be built after DORiE has been properly configured (i.e., by calling `dunecontrol`). Note that you might have to re-configure DORiE once after installing it, because some dependencies are installed at configure time (e.g. by `dunecontrol --only=dorie configure`). To build the documentation, just run
The documentation can also be built locally after DORiE has been properly
configured following the step-by-step instructions above. To build the
documentation, just run
dunecontrol --only=dorie make doc
......@@ -229,8 +227,9 @@ or navigate to the `dorie/build-cmake` directory and call
make doc
You will then find the index page of the documentation at
`dorie/build-cmake/doc/html/index.html`.
You will then find the index page of the Sphinx user manual at
`dorie/build-cmake/doc/html/index.html` and the index page of the Doxygen C++
code documentation at `dorie/build-cmake/doc/doxygen/html/index.html`.
### Run, DORiE, Run!
DORiE provides a command line interface (CLI) for all its functions.
......
# Default Dorie model targets
add_custom_target(richards)
add_custom_target(transport)
add_custom_target(dorie ALL)
add_dependencies(dorie richards transport)
# Maximum polynomial orders of Richards model for available targets
set(DORIE_MAX_RORDER_2 6)
set(DORIE_MAX_RORDER_3 6)
# Maximum polynomial orders of transport model for available targets
set(DORIE_MAX_TORDER_2 0)
set(DORIE_MAX_TORDER_3 0)
# Maximum polynomial orders of Richards model for default targets
set(DORIE_MAX_DEFAULT_RORDER_2 3)
set(DORIE_MAX_DEFAULT_RORDER_3 1)
# Maximum polynomial orders of transport model for default targets
set(DORIE_MAX_DEFAULT_TORDER_2 0)
set(DORIE_MAX_DEFAULT_TORDER_3 0)
#
# .. cmake_function:: dorie_compile_instance
#
# Adds an executable and library for the specified model.
#
# The parameters specify static settings for the model instance. If these
# settings comply to the limits of the default variables, the instance is
# added to the global "richards" or "transport" targets, depending on which
# MODEL type is built.
#
# In case of "transport", the appropriate "richards" library must be available.
# Otherwise, it is also defined by this function.
#
# A sanity check for the input variables is not performed by CMake, but by
# the C++ code during compile-time.
#
# This function takes the following arguments:
#
# - MODEL: Name of the model. Accepts "richards" or "transport".
# - DIMENSION: Spatial dimension.
# - RORDER: Finite element polynomial order of the Richards module.
# - TORDER: Finite element polynomial order of the Transport module.
# - CREATED_LIB: Variable to store the created library target name in.
#
function(dorie_compile_instance)
# parse the function arguments
set(SINGLE_ARGS MODEL DIMENSION RORDER TORDER CREATED_LIB)
cmake_parse_arguments(ARGS "" "${SINGLE_ARGS}" "" ${ARGN})
if (ARGS_UNPARSED_ARGUMENTS)
message(WARNING "Unparsed arguments when calling "
"'dorie_create_executable: "
"${ARGS_UNPARSED_ARGUMENTS}")
endif ()
# set dimension string
set(DIM_STR "d${ARGS_DIMENSION}")
# set option string
set(OPTION_STR "r${ARGS_RORDER}")
# issue warning if transport order is given for 'richards'
if (ARGS_MODEL STREQUAL "richards")
set (lib_src ${PROJECT_SOURCE_DIR}/dune/dorie/model/richards/impl/impl.cc)
if (ARGS_TORDER)
message(WARNING "Ignoring argument TORDER for MODEL "
"'richards'")
endif ()
# append transport order to option string
elseif (ARGS_MODEL STREQUAL "transport")
set (lib_src ${PROJECT_SOURCE_DIR}/dune/dorie/model/coupling/impl/impl.cc)
string(APPEND OPTION_STR "_t${ARGS_TORDER}")
# unknown model
else ()
message(SEND_ERROR "Unsupported model: ${ARGS_MODEL}. "
"Must be either 'richards' or 'transport'")
endif ()
# register the library
set(lib_name "dorie_${ARGS_MODEL}_${DIM_STR}_${OPTION_STR}")
if (NOT TARGET ${lib_name})
add_library(${lib_name} EXCLUDE_FROM_ALL STATIC ${lib_src})
# link to dependencies
target_link_libraries(${lib_name}
PUBLIC
spdlog
muparser::muparser
hdf5
yaml-cpp
${DUNE_LIBS}
)
# register the executable
set(exe_name "${ARGS_MODEL}_${DIM_STR}_${OPTION_STR}")
set(src_file ${CMAKE_SOURCE_DIR}/dune/dorie/${ARGS_MODEL}.cc)
add_executable(${exe_name} EXCLUDE_FROM_ALL ${src_file})
target_link_libraries(${exe_name} PUBLIC ${lib_name})
# Add the executable to the default targets
if ((ARGS_RORDER LESS_EQUAL DORIE_MAX_DEFAULT_RORDER_${ARGS_DIMENSION})
AND ((NOT ARGS_TORDER)
OR ARGS_TORDER LESS_EQUAL DORIE_MAX_DEFAULT_TORDER_${ARGS_DIMENSION})
)
add_dependencies(${ARGS_MODEL} ${exe_name})
endif()
# set compile definitions
target_compile_definitions(${lib_name}
PUBLIC
DORIE_DIM=${ARGS_DIMENSION}
DORIE_RORDER=${ARGS_RORDER})
if (ARGS_MODEL STREQUAL "transport")
target_compile_definitions(${lib_name}
PUBLIC DORIE_TORDER=${ARGS_TORDER})
endif ()
endif()
# If we build a transport model, build the Richards library as well
if (ARGS_MODEL STREQUAL "transport")
dorie_compile_instance(MODEL "richards"
DIMENSION ${ARGS_DIMENSION}
RORDER ${ARGS_RORDER}
CREATED_LIB richards_lib
)
# ... and link to it!
target_link_libraries(${exe_name} PUBLIC ${richards_lib})
endif()
# Report the library target name
if (ARGS_CREATED_LIB)
set(${ARGS_CREATED_LIB} ${lib_name} PARENT_SCOPE)
endif ()
endfunction()
# --- DEPENDENCIES --- #
# These macros check for the following packages, yielding the respective
# targets
#
......@@ -47,5 +48,17 @@ message (STATUS "DUNE Libraries: ${DUNE_LIBS}")
# Remove CMake policy stack
cmake_policy(POP)
# Add DORiE testing functions
include(DorieTesting)
# --- CMAKE MODULES --- #
# Include the CMake modules used in the project
include(DorieCompileInstance)
# Check if testing is enabled
if (dune-testtools_FOUND)
message(STATUS "Testing enabled: dune-testtools found.")
set(DORIE_TESTING TRUE)
# include the DORiE testing macros
include(DorieTesting)
else()
message(STATUS "Testing disabled: dune-testtools not found.")
endif()
......@@ -18,6 +18,11 @@ add_custom_target(prepare_testing
add_dependencies(system_tests prepare_testing)
add_dependencies(unit_tests prepare_testing)
# Create a fake library target to satisfy dune-testtools
add_library(dorie_test UNKNOWN IMPORTED)
set_property(TARGET dorie_test
PROPERTY IMPORTED_LOCATION ${PROJECT_BINARY_DIR}/activate)
#
# .. cmake_function:: add_coverage_links
#
......@@ -48,6 +53,12 @@ endfunction()
# The target this test applies to. This is only required if no SOURCES
# are specified.
#
# .. cmake_param:: CUSTOM_MAIN
# :option:
#
# Write a custom `main()` function for the unit test executables instead
# of generating a default one automatically.
#
# This function serves as wrapper around the function `dune_add_test` which
# registers test for existing targets or adds new test executables from the
# given source files. This function additionally registers the tests as unit
......@@ -61,7 +72,8 @@ endfunction()
#
function(dorie_add_unit_test)
set(SINGLE NAME TARGET)
cmake_parse_arguments(UNIT_TEST "" "${SINGLE}" "" ${ARGN})
set(OPTION CUSTOM_MAIN)
cmake_parse_arguments(UNIT_TEST "${OPTION}" "${SINGLE}" "" ${ARGN})
# use name prefix for test
if(NOT UNIT_TEST_NAME)
......@@ -81,7 +93,19 @@ function(dorie_add_unit_test)
# 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_coverage_links(${UNIT_TEST_TARGET})
target_compile_definitions(${UNIT_TEST_TARGET}
PUBLIC
GTEST
)
if (UNIT_TEST_CUSTOM_MAIN)
target_link_libraries(${UNIT_TEST_TARGET} gtest)
else ()
target_link_libraries(${UNIT_TEST_TARGET} gtest_main)
endif()
add_dependencies(build_unit_tests ${UNIT_TEST_TARGET})
endfunction()
......@@ -94,6 +118,13 @@ endfunction()
# Registers the created tests as unit tests, including coverage flags.
# If not specified, the tests are registered as system tests.
#
# .. cmake_param:: CUSTOM_MAIN
# :option:
#
# Write a custom `main()` function for the unit test executables instead
# of generating a default one automatically. Only applies if UNIT_TEST
# is enabled.
#
# .. cmake_param:: TARGET
# :single:
#
......@@ -139,7 +170,7 @@ endfunction()
# executable will be linked to the libraries DORiE depends on.
#
function(dorie_add_metaini_test)
set(OPTIONS UNIT_TEST)
set(OPTIONS UNIT_TEST CUSTOM_MAIN)
set(SINGLE TARGET METAINI SCRIPT BASENAME CREATED_TARGETS)
cmake_parse_arguments(SYSTEM_TEST "${OPTIONS}" "${SINGLE}" "" ${ARGN})
......@@ -147,6 +178,11 @@ function(dorie_add_metaini_test)
message(SEND_ERROR "No meta ini file given!")
endif()
if(SYSTEM_TEST_CUSTOM_MAIN AND NOT SYSTEM_TEST_UNIT_TEST)
message(WARNING "Ignoring option CUSTOM_MAIN because option UNIT_TEST "
"was not enabled")
endif()
# configure meta ini file or just copy.
get_filename_component(metaini-name ${SYSTEM_TEST_METAINI} NAME_WE)
get_filename_component(metaini-extension ${SYSTEM_TEST_METAINI} EXT)
......@@ -198,8 +234,19 @@ function(dorie_add_metaini_test)
# add dependencies and flags
if(SYSTEM_TEST_UNIT_TEST)
add_coverage_links(${created_targets})
# add_coverage_links(${created_targets})
add_dependencies(build_unit_tests ${created_targets})
target_compile_definitions(${created_targets}
PUBLIC
GTEST
)
if (SYSTEM_TEST_CUSTOM_MAIN)
target_link_libraries(${created_targets} gtest)
else ()
target_link_libraries(${created_targets} gtest_main)
endif()
else()
add_dependencies(build_system_tests ${created_targets})
endif()
......
......@@ -213,9 +213,14 @@ breathe_default_project = "dorie"
# -- Pass special options to build setup -------------------------------------
# Config: dune-testtools module was found by CMake
meta_ini_available = "@DORIE_TESTING@".lower() in ["1", "true", "yes", "on"]
# Apply custom configuration to the Sphinx app
def setup(app):
app.add_config_value('recommonmark_config', {
'enable_math': True,
'enable_inline_math': True
}, True)
app.add_config_value('meta_ini_available', False, 'env')
app.add_transform(AutoStructify)
dorie_add_metaini_test(TARGET dorie_test
METAINI tutorial-1.mini.in)
configure_file(${CMAKE_CURRENT_BINARY_DIR}/tutorial-1.ini
${CMAKE_CURRENT_SOURCE_DIR}/config.ini
COPYONLY)
# Copy files needed for the test to run
configure_file(${CMAKE_BINARY_DIR}/doc/default_files/infiltration.yml
infiltration.yml
COPYONLY)
configure_file(${CMAKE_BINARY_DIR}/doc/default_files/richards_param.yml
richards_param.yml
COPYONLY)
include ${CMAKE_BINARY_DIR}/doc/default_files/config.ini
_test_command = run
__name = tutorial-1
# WARNING: Any change in the line ordering of this file will affect the
# tutorial view on this file
[simulation]
mode = richards
[grid]
gridType = rectangular
dimensions = 2
extensions = 1 4
cells = 1 200
[grid.mapping]
volume = 0
[richards.parameters]
file = richards_param.yml
[richards.initial]
type = analytic
quantity = matricHead
equation = -h
[richards.boundary]
file = infiltration.yml
[richards.output]
fileName = infiltr_homogeneous_sand_2D
outputPath = ./
\ No newline at end of file
**********************************
Infiltration in Homogeneous Medium
**********************************
One of the most simple DORiE simulations is the case of constant infiltration on
a 2D homogeneous medium. In particular, we will create a similar simulation to
the one conducted by Kurt Roth in his
`Soil Physics Lecture Notes <http://ts.iup.uni-heidelberg.de/teaching/#c520>`_,
Chapter 6.3.1.
Study Case
----------
Consider a uniform and isotropic soil with constant water table
(:math:`h_m = 0\,\text{m}`) at height :math:`y=0\,\text{m}` and vertical flux
in the vadose zone. We choose the :math:`y`-axis to point upwards.
For times :math:`t < 0`, the water phase is in static equilibrium, i.e.,
:math:`j_w = 0\,\text{ms}^{-1}` in the entire domain. The soil surface is
located at :math:`y=4\,\text{m}`. For :math:`t \leq 0`, the water flux through
the surface boundary is set to
:math:`j_w = 5.56 \cdot 10^{−6}\,\text{ms}^{-1} = 20\,\text{mm}\,\text{h}^{-1}`,
equivalent to heavy rainfall.
Configure DORiE Input Files
---------------------------
In what follows, we will set up input files and run the simulation step-by-step
reviewing the most important parts of the DORiE work-flow.
Simulation Mode
^^^^^^^^^^^^^^^
The first decision to make is to choose the mode of your simulation. In this
case, we are only interested in the water flow movement. Hence, the richards
mode in the configuration file is well suited for our purpose.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 9-10
:caption: config.ini
Grid Creation
^^^^^^^^^^^^^
For any simulation, the :doc:`grid settings </manual/grid>` have to be
setup exactly once since all models share the same grid.
In this case, we will create a ``rectangular`` grid by specifying the number
of ``cells`` and the ``extensions`` of the domain. Grids of this type are
directly created within DORiE, thus, the keyword ``gridFile`` is ignored.
.. note::
The original simulation is one dimensional, but DORiE only supports two and
three dimensions. Hence, we use a 2D simulation with 1 cell for the
:math:`x`-direction, as the simulation is symmetrical along this axis.
We set ``1 4`` as the ``extensions`` of the domain. This means that the
rectangular grid will be generated with an extension of :math:`1\,\text{m}` in
the :math:`x`-direction and an extension of :math:`4\,\text{m}` in
the :math:`y`-direction. Notice that the :math:`x`-direction points to the
right, and the :math:`y`-direction upwards. The point of origin in DORiE's
reference frame is located at the lower left point.
Now we have to fill a domain of this size with rectangular grid cells by
specifying the number of cells into each direction. For the
:math:`x`-direction, we will set this to ``1``. For the :math:`y`-direction,
we choose a reasonable resolution of :math:`2\,\text{cm}` per cell, meaning
that we need ``200`` cells in total. That is, we set the pair ``1 200`` of
``cells`` in the config file.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 12-16
:caption: config.ini
Soil Parameterization
^^^^^^^^^^^^^^^^^^^^^
First, in the configuration file we set the
:ref:`parameterization file <man-parameter_file>` that we want to use. In this
case, we select the file ``richards_param.yml`` provided by the
``dorie create`` command.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 21-22
:caption: config.ini
Now, for homogeneous materials, the key ``grid.mapping.volume`` in the config
file refers to the keyword ``index`` to use in the parameterization file for
the whole domain. That said, if the parameterization file looks like this:
.. literalinclude:: ../../default_files/richards_param.yml
:emphasize-lines: 2-3,14-15
:language: yaml
:caption: richards_param.yml
then, a ``volume`` set to ``0`` will have a parameterization for ``sand`` while
a ``volume`` set to ``1`` will have a parameterization for
``silt``. For now, let's say we want to simulate an homogeneous sand.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 18-19
:caption: config.ini
Initial Condition
^^^^^^^^^^^^^^^^^
The :doc:`initial condition </manual/initial>` can be fed with HDF5 data
files or with analytic functions. In this case, we set an initial
condition with the water table at :math:`y = 0\,\text{m}` with a fluid phase in
hydrostatic equilibrium. This can be represented by an ``analytic`` function
where the ``matricHead`` is simply set to ``-h``. See the documentation of
:ref:`analytic initial conditions <man-initial-types>` for details.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 24-27
:caption: config.ini
Boundary Condition
^^^^^^^^^^^^^^^^^^
The :doc:`boundary conditions file </manual/bcfile>` has to be specified by the
keyword ``richards.boundary.file`` in the configuration file. For now, we will
use the infiltration file, ``infiltration.yml``, provided by the command
``dorie create``. By default, this file sets a constant infiltration of
:math:`j_w = -5.55\cdot 10^{-6}\,\text{ms}^{-1}` at the top, a constant matric
head of :math:`h_m = 0\,\text{m}` at the bottom, and a no-flux condition on the
sides of the domain.
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 29-30
:caption: config.ini
Output
^^^^^^
Finally, we give a name and a path to the
:doc:`output files </introduction/data-io>` of the simulation:
.. literalinclude:: tutorial-1.mini.in
:language: ini
:lines: 32-34
:caption: config.ini
Run DORiE
---------
Once everything is set up, we :doc:`run DORiE </manual/cli>` by calling the
command ``dorie run`` followed by the configuration file ``confing.ini``:
.. code-block:: bash
dorie run config.ini
By doing this, the simulation should start and provide information about the
status of the simulation depending on the on the ``logLevel`` keyword on the
configuration file. A typical DORiE simulation has the following output:
.. code-block:: none
[18:27:32.762 I] Starting DORiE
[18:27:32.762 I] Reading configuration file: config.ini
[18:27:32.768 I] Creating output directory: ./
[18:27:32.768 I] Creating a rectangular grid in 2D
[18:27:32.776 I] [RIC] Loading parameter data file: richards_param.yml
[18:27:32.779 I] [RIC] Reading boundary condition data file: 2d_infiltr.bcdat
[18:27:32.784 I] [RIC] Setup complete
[18:27:33.296 I] [RIC] Time Step 0: 0.00e+00 + 1.00e+01 -> 1.00e+01
[18:27:33.581 I] [RIC] Time Step 1: 1.00e+01 + 1.50e+01 -> 2.50e+01
[18:27:33.899 I] [RIC] Time Step 2: 2.50e+01 + 2.25e+01 -> 4.75e+01
[18:27:34.177 I] [RIC] Time Step 3: 4.75e+01 + 3.38e+01 -> 8.12e+01
...
[18:27:46.863 I] [RIC] Time Step 51: 7.67e+05 + 1.00e+05 -> 8.67e+05
[18:27:46.894 I] [RIC] Time Step 52: 8.67e+05 + 1.00e+05 -> 9.67e+05
[18:27:46.923 I] [RIC] Time Step 53: 9.67e+05 + 3.34e+04 -> 1.00e+06
[18:27:46.938 I] DORiE finished after 1.47e+01s :)
Results
-------
The :ref:`results <intro-io-output>` should have been written in several
:file:`.vtu` files, one for each time step, and gathered by a :file:`.pvd`
file. By opening the latter in Paraview_ (or VisIt_) it is possible to
visualize the dynamics of the matric head, water content, and water flux as
shown below.
.. _Paraview: http://www.paraview.org/
.. _VisIt: https://visit.llnl.gov/
.. image:: result.gif
.. admonition:: Input files
============= ======================================================================
Configuration :download:`config.ini <config.ini>`
Boundary :download:`infiltration.yml </default_files/infiltration.yml>`
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`
============= ======================================================================
message(STATUS "Handling cookbook tests")
add_subdirectory(1-infiltration-sand)
......@@ -2,17 +2,65 @@ Introduction
************
This part of the documentation guides through increasingly complicated
use-cases of DORiE. It is intended for users who wish to jump right into using
DORiE, without much knowledge of all its functions. The relevant manual pages
will be linked on the way.
use-cases of DORiE. It is intended for users who are using DORiE for the first
time. It explains the usage of the program, how to execute a simulation and how
to analyze its results. The relevant manual pages will be linked on the way.
Prerequisites
=============
You need a working application. You can either use the image shipped via
`Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
installation. See the installation manual for details.
Additionally, install Paraview_ for analyzing the output.
installation. See the :doc:`installation manual </introduction/readme>` for
details. Additionally, install Paraview_ for analyzing the output.
.. _Paraview: http://www.paraview.org/download/
.. _Gmsh: http://gmsh.info
Setup DORiE virtual environment
===============================
Before of any proper calculation, it is necessary to set up the DORiE virtual
environment in your terminal. This will allow you to call the DORiE commands
anywhere in your system. For this, follow the instructions in the
:doc:`command line interface documentation </manual/cli>`.
Once ready, create a directory where you want to perform the simulations.
For instance
.. code-block:: bash
mkdir $HOME/Documents/dorie/ex1
cd $HOME/Documents/dorie/ex1
Create DORiE Input Files
========================
DORiE needs multiple :doc:`input files </introduction/data-io>` to work.
Although these files seem to be quite overwhelming at the beginning, you will
notice that most of their parameters will not be modified in most of the
cases. Now, you can find an example of these input files using the command
.. code-block:: bash
dorie create
which will provide the files for a simple DORiE application in your
current folder. Explore them!
.. tip::
Most recipes in this cookbook provide a complete set of input files for the
specified simulation. You will find them at the end of the recipe in blocks
as the one below.
.. admonition:: Input files
============= ======================================================================
Configuration :download:`config.ini </default_files/config.ini>`
Boundary :download:`2d_infiltr.bcdat <../default_files/2d_infiltr.bcdat>`,
:download:`3d_infiltr.bcdat </default_files/3d_infiltr.bcdat>`,
:download:`2d_solute.bcdat </default_files/2d_solute.bcdat>`,
:download:`3d_solute.bcdat </default_files/3d_solute.bcdat>`
Parameters :download:`richards_param.yml </default_files/richards_param.yml>`,
:download:`transport_param.yml </default_files/transport_param.yml>`
============= ======================================================================
......@@ -5,7 +5,7 @@ Restart
Currently, DORiE does not have an option to restart simulations. However, it
is possible to make a pseudo-restart from a past simulation using
:doc:`initial conditions<initial>` from data files.
:doc:`initial conditions<initial>` from output data files.
Pseudo-restart
--------------
......@@ -75,3 +75,6 @@ Notice that this qualifies as a pseudo-restart because the degrees of freedom
of the last simulation are not completely recovered. Indeed, they are
degenerated! Hence, strictly speaking, a pseudo-restart will lead to different
results compared with respect to a one-run simulation.
.. todo:: Add files
.. todo:: Add test
\ No newline at end of file
spatial_resolution_north 0
spatial_resolution_south 0
spatial_resolution_west -1
spatial_resolution_east -1
number_BC_change_times 1
0 neumann -5.55e-6 dirichlet 0
\ No newline at end of file
spatial_resolution_north 2 0.25 0.75
spatial_resolution_south -1
spatial_resolution_west -1
spatial_resolution_east -1
number_BC_change_times 2
0 neumann 0 dirichlet 1 neumann 0
1E3 neumann 0 neumann 0 neumann 0
spatial_resolution_north_we 0
spatial_resolution_north_fb 0
spatial_resolution_south_we 0
spatial_resolution_south_fb 0
spatial_resolution_west_sn -1
spatial_resolution_west_fb -1
spatial_resolution_east_sn -1
spatial_resolution_east_fb -1
spatial_resolution_front_sn -1
spatial_resolution_front_we -1
spatial_resolution_back_sn -1
spatial_resolution_back_we -1
number_BC_change_times 1
0 neumann -5.55e-6 dirichlet 0
\ No newline at end of file
spatial_resolution_north_we 2 0.25 0.75
spatial_resolution_north_fb 2 0.25 0.75
spatial_resolution_south_we -1
spatial_resolution_south_fb -1
spatial_resolution_west_sn -1
spatial_resolution_west_fb -1
spatial_resolution_east_sn -1
spatial_resolution_east_fb -1
spatial_resolution_front_sn -1
spatial_resolution_front_we -1
spatial_resolution_back_sn -1
spatial_resolution_back_we -1
number_BC_change_times 2
0 neumann 0 neumann 0 neumann 0 neumann 0 dirichlet 1 neumann 0 neumann 0 neumann 0 neumann 0
1E3 neumann 0 neumann 0 neumann 0 neumann 0 neumann 0 neumann 0 neumann 0 neumann 0 neumann 0
\ No newline at end of file
......@@ -117,9 +117,10 @@ function(create_default_config INPUT OUTPUT SOURCE_DIR CSS)