{"id":142846,"name":"DORiE","description":"A Discontinuous Galerkin Solver for Soil Water Flow and Passive Solute Transport Based on DUNE.","url":"https://gitlab.dune-project.org/dorie/dorie","last_synced_at":"2026-04-14T17:00:18.870Z","repository":{"id":249051397,"uuid":"1088","full_name":"dorie/dorie","owner":"dorie","description":"Solver for the Richards Equation and passive solute transport. NOTE: This repository was recently migrated. Beware of dead links!","archived":null,"fork":false,"pushed_at":null,"size":null,"stargazers_count":0,"open_issues_count":null,"forks_count":0,"subscribers_count":null,"default_branch":"master","last_synced_at":"2026-02-21T16:40:51.965Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":null,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":null,"icon_url":null,"metadata":{},"created_at":"2022-06-22T15:06:16.031Z","updated_at":"2022-12-21T08:46:16.572Z","dependencies_parsed_at":null,"dependency_job_id":"dde74177-1a1b-425f-a1e8-aadec0202cf7","html_url":"https://gitlab.dune-project.org/dorie/dorie","commit_stats":null,"previous_names":["dorie/dorie"],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:gitlab/dorie/dorie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/owners/dorie","download_url":"https://gitlab.dune-project.org/dorie/dorie/-/archive/master/dorie-master.zip","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/sbom","scorecard":null,"host":{"name":"gitlab.dune-project.org","url":"https://gitlab.dune-project.org","kind":"gitlab","repositories_count":579,"owners_count":20,"icon_url":"https://github.com/gitlab.png","version":null,"created_at":"2024-07-18T11:23:55.436Z","updated_at":"2024-07-18T11:23:55.436Z","status":"online","status_checked_at":"2026-02-25T02:20:13.315Z","response_time":195,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T07:05:35.790Z","robots_txt_url":"https://gitlab.dune-project.org/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/owners"}},"owner":{"login":"dorie","name":"dorie","uuid":"organization-1463","kind":"organization","description":"","email":null,"website":null,"location":null,"twitter":null,"company":null,"icon_url":null,"repositories_count":1,"last_synced_at":"2024-07-18T13:50:10.870Z","metadata":{},"html_url":"https://gitlab.dune-project.org/dorie","funding_links":[],"total_stars":0,"followers":null,"following":null,"created_at":"2024-07-18T13:50:10.879Z","updated_at":"2024-07-18T13:50:10.879Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/owners/dorie","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/owners/dorie/repositories"},"packages":[],"commits":{"id":1638604,"full_name":"dorie/dorie","default_branch":"master","total_commits":1626,"total_committers":11,"total_bot_commits":0,"total_bot_committers":0,"mean_commits":147.8181818181818,"dds":0.45018450184501846,"past_year_total_commits":0,"past_year_total_committers":0,"past_year_total_bot_commits":0,"past_year_total_bot_committers":0,"past_year_mean_commits":0.0,"past_year_dds":0.0,"last_synced_at":"2026-04-12T06:57:49.508Z","last_synced_commit":"b09bd1b1f47d55ea2805800321bb109e8cd5125e","created_at":"2024-07-23T20:00:18.523Z","updated_at":"2026-04-12T06:57:49.425Z","committers":[{"name":"Lukas Riedel","email":"mail@lukasriedel.com","login":null,"count":894},{"name":"Santiago Ospina","email":"santiago.ospina@iup.uni-heidelberg.de","login":null,"count":421},{"name":"Dion Häfner","email":"mail@dionhaefner.de","login":null,"count":100},{"name":"Santiago Ospina De Los Ríos","email":"santiago.ospina@iup.uni-heildelberg.de","login":null,"count":71},{"name":"Santiago","email":"sospinar@gmail.com","login":null,"count":61},{"name":"Santiago Ospina","email":"saospina@hugo.iwr.uni-heidelberg.de","login":null,"count":56},{"name":"Dion Häfner","email":"dhaefner@iup.uni-heidelberg.de","login":null,"count":13},{"name":"Santiago Ospina","email":"Soil19@hotmail.com","login":null,"count":7},{"name":"Hannes Bauser","email":"hannes.bauser@iup.uni-heidelberg.de","login":null,"count":1},{"name":"Santiago Ospina De Los Rios","email":"santiago.ospina@iwr.uni-heidelberg.de","login":null,"count":1},{"name":"Santiago Ospina De Los Ríos","email":"soil19@hotmail.com","login":null,"count":1}],"past_year_committers":[],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/commits","host":{"name":"gitlab.dune-project.org","url":"https://gitlab.dune-project.org","kind":"gitlab","last_synced_at":"2026-04-12T00:00:15.847Z","repositories_count":13,"commits_count":46456,"contributors_count":548,"owners_count":3,"icon_url":"https://github.com/gitlab.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories"}},"issues_stats":{"full_name":"dorie/dorie","html_url":"https://gitlab.dune-project.org/dorie/dorie","last_synced_at":"2026-04-12T16:01:42.497Z","status":"error","issues_count":null,"pull_requests_count":null,"avg_time_to_close_issue":null,"avg_time_to_close_pull_request":null,"issues_closed_count":null,"pull_requests_closed_count":null,"pull_request_authors_count":null,"issue_authors_count":null,"avg_comments_per_issue":null,"avg_comments_per_pull_request":null,"merged_pull_requests_count":null,"bot_issues_count":null,"bot_pull_requests_count":null,"past_year_issues_count":null,"past_year_pull_requests_count":null,"past_year_avg_time_to_close_issue":null,"past_year_avg_time_to_close_pull_request":null,"past_year_issues_closed_count":null,"past_year_pull_requests_closed_count":null,"past_year_pull_request_authors_count":null,"past_year_issue_authors_count":null,"past_year_avg_comments_per_issue":null,"past_year_avg_comments_per_pull_request":null,"past_year_bot_issues_count":null,"past_year_bot_pull_requests_count":null,"past_year_merged_pull_requests_count":null,"created_at":"2024-07-19T18:00:26.787Z","updated_at":"2026-04-12T16:01:42.497Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories/dorie%2Fdorie/issues","issue_labels_count":{},"pull_request_labels_count":{},"issue_author_associations_count":{},"pull_request_author_associations_count":{},"issue_authors":{},"pull_request_authors":{},"host":{"name":"gitlab.dune-project.org","url":"https://gitlab.dune-project.org","kind":"gitlab","last_synced_at":"2026-04-12T00:00:15.909Z","repositories_count":0,"issues_count":0,"pull_requests_count":0,"authors_count":0,"icon_url":"https://github.com/gitlab.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/gitlab.dune-project.org/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{},"past_year_pull_request_author_associations_count":{},"past_year_issue_authors":{},"past_year_pull_request_authors":{},"maintainers":[],"active_maintainers":[]},"events":null,"keywords":[],"dependencies":[],"score":null,"created_at":"2023-11-23T17:27:45.974Z","updated_at":"2026-04-14T17:00:18.871Z","avatar_url":null,"language":null,"category":"Natural Resources","sub_category":"Water Supply and Quality","monthly_downloads":0,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"# DORiE\n(**D**UNE-**O**perated **Ri**chards equation solving **E**nvironment)\n\nDORiE is a software package for solving the Richards equation coupled with the\npassive transport equation. The core feature is a C++ PDE-solver powered by\n[DUNE](https://dune-project.org/) and especially the\n[DUNE-PDELab](https://dune-project.org/modules/dune-pdelab/) module.\n\nJust getting started? Use the\n[Cook Book](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/cookbook/index.html)\nin the User Manual to dive right in!\n\n### Contents of this README\n\n* [Overview](#overview)\n* [Installation](#installation-instructions)\n    * [Docker Image](#download-docker-image)\n    * [Dependencies](#dependencies)\n    * [Manual Installation](#manual-installation)\n    * [Recommended Tools](#recommended-third-party-software)\n* [Documentation](#documentation)\n* [Usage](#usage)\n* [Troubleshooting](#troubleshooting)\n\n---\n\n## Overview\n\nDORiE offers a variety of solver and discretization solutions. The passive\ntransport module is optional. For both modules independently, users may choose\nfinite volume (FV) or discontinuous Galerkin (DG) discretizations. The latter\nmay be used on unstructured grids and can take advantage of adaptive local grid\nrefinement.\n\nThe C++ routines are accompanied by various tools for program setup,\nprogram testing, and output analysis, which are mostly written in Python.\n\nDORiE is developed and maintained by the\n[DORiE Developers](mailto:dorieteam@iup.uni-heidelberg.de) of the\n[TS-CCEES](http://ts.iup.uni-heidelberg.de/) research group at the\n[Institute of Environmental Physics (IUP) Heidelberg](http://www.iup.uni-heidelberg.de/),\nsupervised by\n[Kurt Roth](http://ts.iup.uni-heidelberg.de/people/prof-dr-kurt-roth/),\nin collaboration with\n[Ole Klein](https://conan.iwr.uni-heidelberg.de/people/oklein/) and the\n[Scientific Computing Group](https://conan.iwr.uni-heidelberg.de/) of the\n[Interdisciplinary Center for Scientific Computing (IWR) Heidelberg](https://typo.iwr.uni-heidelberg.de/home/).\n\nDORiE is free software and licensed under the\n[GNU General Public License Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html).\nFor the copyright notice and the list of copyright holders,\nsee [`COPYING.md`](COPYING.md).\n\nContributions to the project are always welcome! Please notice our\n[Contribution Guidelines](CONTRIBUTING.md).\n\n### How to Cite DORiE\n\nDORiE v2.0 was reviewed and published in the [Journal of Open Source Software (JOSS)](https://joss.theoj.org/).\nPlease cite at least the following publication if you use DORiE (or a modified version thereof) for your own work:\n\n\u003e Riedel, Lukas, Santiago Ospina Los De Ríos, Dion Häfner, and Ole Klein. 2020. “DORiE: A Discontinuous Galerkin Solver for Soil Water Flow and Passive Solute Transport Based on DUNE.” *Journal of Open Source Software* 5 (52): 2313. https://doi.org/10.21105/joss.02313.\n\nThe [`CITATION.cff`](CITATION.cff) file in this repository follows the [citation file format](https://citation-file-format.github.io/) and contains additional metadata to reference this software, its authors, and associated publications.\n\n## Installation Instructions\n\nDORiE is a [DUNE](https://dune-project.org/) module and requires several other\nDUNE modules as well as third party software packages. Installation can be\nhandled manually on your local machine, but we recommend using a pre-compiled\nimage for the deployment software [Docker](https://www.docker.com/) to\ninexperienced users instead. Docker can also be used to create a development\nenvironment without installing the dependencies on the host machine.\n\n### Download Docker Image\n\nNo installation is necessary if you download DORiE as Docker image from\n[Docker Hub](https://hub.docker.com/r/dorie/dorie/).\n\nIf you want to use any stable version of DORiE, or the most recent unstable\nversion, you can download the appropriate images from Docker Hub. To do so,\nexecute\n\n    docker pull dorie/dorie[:\u003ctag\u003e]\n\nOmitting the tag information downloads the image with tag `latest` which\nrefers to the latest stable version. You can download any tag by specifying\n`\u003ctag\u003e`. The list of\n[available tags](https://hub.docker.com/r/dorie/dorie/tags) can be found on\nDocker Hub and matches the release tags list of the Git repository. The latest\nunstable version is tagged as `devel`.\n\nYou can then proceed directly to the the instructions on\n[how to execute DORiE](#running-dorie). The commands listed there are appended\nto the usual commands for running a Docker container. See the description on\nDocker Hub for further details.\n\n#### Use Docker for Development\n\nAn intermediate solution for creating a development environment without\ninstalling all dependencies is using the\n[DUNE environment Docker image](https://hub.docker.com/r/dorie/dune-env) of\nDORiE. It is based on a Ubuntu image and contains all dependencies of DORiE.\nDevelopers can clone the DORiE source code onto their host system, modify it\nthere and then mount the directory into the Docker image to compile the program.\nTo start a container from the image with the local `\u003cdorie_dir\u003e` mounted,\nexecute\n\n    docker run -it -v \u003cdorie_dir\u003e:/opt/dune/ dorie/dune-env:\u003ctag\u003e\n\nInside the container, you can then execute the `dunecontrol` script as explained\nin the installation instructions further below.\n\n### Dependencies\n\nDepending on your system configuration, there will be more packages necessary to\ninstall DORiE on your machine. See the step-by-step manual for further details.\nThe specified versions are the _supported_ ones, where compatibility is ensured\nby CI tests.\n\n#### DUNE Packages\n\n| Software | Version/Branch | Comments |\n| ---------| -------------- | -------- |\n| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6\n| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.6\n| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.6\n| [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) | releases/2.6\n| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.6\n| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.6\n| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.6\n| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.6\n| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.6\n| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | releases/2.6\n| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.6 | *Optional:* For system tests\n\n#### DUNE Requirements\n\n| Software | Version/Branch | Comments |\n| ---------| -------------- | -------- |\n| CMake | 3.16 |\n| GCC | 9.3 | Full C++17 support required\n| *or* LLVM Clang | 10 | Full C++17 support required\n| *or* AppleClang | 11 | Full C++17 support required\n| git |\n| pkg-config |\n| FFTW3 | 3.3.8 | MPI support required\n| Python | 3.8 |\n| pip | 20 |\n| MPI | | Tested with OpenMPI 4.0.3\n| SuperLU | 5.2 |\n| OpenGL | 1.3 | Or another GL implementation compatible with VTK 9\n\n#### DORiE Requirements\n\n| Software | Version/Branch | Comments |\n| ---------| -------------- | -------- |\n| [HDF5](https://www.hdfgroup.org/solutions/hdf5/) | 1.10 | MPI support required\n| [yaml-cpp](https://github.com/jbeder/yaml-cpp) | \u003e= 5.2.0 |\n| [muparser](http://beltoforion.de/article.php?a=muparser) | master |\n| [spdlog](https://github.com/gabime/spdlog) | \u003e= 1.0 |\n| [Google Test](https://github.com/google/googletest) | `HEAD` | Included as Git Submodule\n\n#### Optional Packages\n\n| Software | Version/Branch | Comments |\n| -------- | -------------- | -------- |\n| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.17 | Builds documentation\n| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs\n| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs\n\n### Manual Installation\n\nInstalling all packages manually can be quite an effort, but useful for\ndevelopers who want to have easy access to the source files or users who prefer\nto run DORiE without the Docker overhead.\n\nWhenever possible, dependencies should be installed using a package manager\nlike [APT](https://wiki.ubuntuusers.de/APT/) on Ubuntu or\n[Homebrew](http://brew.sh/) on Mac. Manual installation on a Windows\nenvironment is not supported!\n\nDORiE is configured, built, and installed via the\n[DUNE Buildsystem](https://dune-project.org/doc/installation/), using the\n`dunecontrol` script to handle DUNE-internal dependencies.\n\n#### Step-by-step Instructions\nThese instructions are suitable for a clean **Ubuntu** or **macOS** setup.\nThe main difference between the two systems is the package manager.\nDebian-based systems have the APT manager already built in. On Mac, we\nrecommend installing [Homebrew](http://brew.sh/). If you prefer to use\n[MacPorts](https://www.macports.org/), notice that packages will need to be\ninstalled differently than indicated here.\n\nManual installations on macOS require installing HDF5 from source. This can\nbe tricky, but the following instructions should work on a clean system.\n\nIf you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html)\non your machine, you don't need to install Python or Pip. Simply skip these\npackages when using the package managers for installing the software. However,\nnotice the warnings when compiling DORiE below!\n\n1. **macOS** users need to start by installing the Apple Command Line Tools by\n    executing\n\n        xcode-select --install\n\n    Make sure you have no pending software updates for your respective version\n    of macOS!\n\n2. Install third party packages:\n\n    **Ubuntu:**\n\n        apt update\n        apt install cmake doxygen gcc g++ gfortran \\\n                    git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \\\n                    libfreetype6-dev libgl-dev libhdf5-mpi-dev libmuparser-dev \\\n                    libopenmpi-dev libpng-dev libspdlog-dev libsuperlu-dev \\\n                    libyaml-cpp-dev libxft-dev python3-dev python3-pip\n\n    **macOS:**\n\n        brew update\n        brew install cmake doxygen fftw gcc libpng open-mpi muparser \\\n                     pkg-config python3 spdlog superlu yaml-cpp\n\n3. **macOS only:** Install HDF5 with MPI support from source.\n\n    1. Download an archive of the\n    [HDF5 source code](https://www.hdfgroup.org/downloads/hdf5/source-code/),\n    and extract it.\n\n    1. Enter the extracted folder. In there, create a `build` directory, and\n    enter it:\n\n            mkdir build \u0026\u0026 cd build\n\n    1. Configure your build. If you followed the instructions above, the\n    OpenMPI C compiler is reachable via the command `mpicc`. If not, you have\n    to specify a full path to it. Use the option `prefix` to specify where\n    you want the package to be installed. This should *not* be a\n    system-reserved path like `/usr/local`, and *not* be located in a\n    sub-directory of the source code. Execute the configuration script:\n\n            ./../configure CC=mpicc --prefix=\u003chdf5-path\u003e --enable-parallel\n\n    1. Build and install the library:\n\n            make \u0026\u0026 make install\n\n4. The parallel linear solver of DORiE can make use of the ParMETIS package.\n    If you want to run DORiE in parallel on multiple processes, additionally\n    install METIS and ParMETIS:\n\n    **Ubuntu:**\n\n        apt install libmetis-dev libparmetis-dev\n\n    **macOS:** _Support is dropped because ParMETIS is currently unavailable\n    from Homebrew._\n\n    **Parallel runs without these two packages are possible but not supported!**\n\n5. Create a directory for all your DUNE modules, including DORiE. If you already\n   cloned DORiE somewhere else, move the cloned folder into the DUNE module\n   directory.\n\n6. Clone the [DUNE modules](#dune-Packages) into the DUNE module directory. Use\n   `git checkout` to switch to the correct branches. We provide a bash script\n   which clones all required repositories and checks out the correct branches\n   into the directory it is executed from. Move into the DUNE module folder and\n   execute it:\n\n        bash dorie/clone_dune\n\n7. Make sure the DORiE repository is correctly set up. DORiE includes\n   [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules),\n   which are only downloaded if you add the `--recurse-submodules` option to the\n   `git clone` command. To make sure the submodules are cloned and checked out,\n   enter the DORiE repository and execute\n\n        git submodule init \u0026\u0026 git submodule update\n\n8. Enter the DUNE module directory, and call\n\n        ./dune-common/bin/dunecontrol --opts=dorie/build.opts all\n\n    to build all DUNE modules. Additionally, you can add `MAKE_FLAGS=\"-j X\"`\n    to the command in order to compile on `X` processes in parallel.\n\n    The `build.opts` file in this repository contains required and useful CMake\n    variable settings for a build of DORiE. If you installed software into paths\n    not appended to your `PATH` variable, you will have to add more\n    `CMAKE_FLAGS` in the options file to make sure that CMake finds all\n    packages. If `\u003cPackage\u003e_ROOT` variables suffice, you can simply prepend them\n    before the `dunecontrol` command. See the\n    [Dune Installation Docs](https://www.dune-project.org/doc/installation/) for\n    further information.\n\n    If you installed HDF5 from source (all **macOS** users) or use Anaconda,\n    specify the path to your HDF5 installation by using the `HDF5_ROOT`\n    environment variable. On Ubuntu, prepend the path to the APT package,\n\n        HDF5_ROOT=/usr/\n\n    and on macOS, prepend\n\n        HDF5_ROOT=\u003chdf5-path\u003e\n\n    in the `dunecontrol` command above, replacing `\u003chdf5-path\u003e` with the\n    path chosen as installation prefix when configuring HDF5. Alternatively,\n    `export` these paths in your shell before calling `dunecontrol`, or add\n    them as CMake variables (with prefix `-D`) to the repository options file.\n\n### Recommended Third-Party Software\n\nThe following software packages are cross-platform, so you should be able to\nfind a release that fits your operating system:\n\n* [ParaView](http://www.paraview.org/): A powerful post-processing tool for VTK\n    files. Offers both visualization and data analysis tools.\n* [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the\n    `.msh` files used by DORiE to define unstructured meshes.\n\n## Documentation\n\nThe documentation of DORiE is twofold. The Sphinx documentation contains a\nmanual with guidelines and tutorials for users of the compiled software\npackage. The Doxygen documentation of the C++ source code is intended for\ndevelopers only and explains the inner workings of the software.\n\nBoth parts of the documentation are deployed to our documentation server for\nevery branch pushed to the main repository. You will find the latest\n[user manual](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/) and\n[C++ code documentation](https://hermes.iup.uni-heidelberg.de/dorie_doc/master/doxygen/html/)\nthere. The documentation for other branches can be accessed via the\n[overview page](https://hermes.iup.uni-heidelberg.de/dorie_doc/).\n\nThe documentation can also be built locally after DORiE has been properly\nconfigured following the step-by-step instructions above. To build the\ndocumentation, move to the `dorie/build-cmake` directory and simply run\n\n    make doc\n\nYou will then find the index page of the Sphinx user documentation at\n`dorie/build-cmake/doc/html/index.html` and the index page of the Doxygen\nsource code documentation at `dorie/build-cmake/doc/doxygen/html/index.html`.\n\n## Usage\n\nDORiE provides a command line interface (CLI) for all its user functions.\nThe required Python modules and all their dependencies are readily installed\ninto a Python virtual environment (`venv`), which has to be activated within a\nshell session. You can do so by activating it in your current session\n(Manual Installation only) or by running the Docker application.\n\n### Run the `venv` using the Docker application\nIf you did not install DORiE locally, you can use the Docker application to\nboot up the virtual environment in a mounted directory of your choice.\n\nStart up the Docker application by calling\n\n    docker run -it -v \u003cdir\u003e:/mnt \u003cimg\u003e\n\nwhere you replace `\u003cdir\u003e` with a local directory for storing input and output\ndata, and `\u003cimg\u003e` with `dorie/dorie[:\u003ctag\u003e]`. We recommend moving into the\ndesignated input and output directory on your local machine and inserting\n`$PWD` as `\u003cdir\u003e` to mount the current directory into the container.\n\nThe command boots up a (`bash`) shell inside a Docker container and mounts\nthe directory `\u003cdir\u003e` and all its subdirectories into the directory `/mnt`\ninside the container. Your shell session starts in this directory with the\nvirtual environment activated.\n\nNotice, that you can only use **local file paths** in all configuration\nsettings due to the directory mount.\n\n### Activate the `venv` locally\nTo activate the virtual environment within your current shell session, execute\n\n    source \u003cpath/to/\u003edorie/build-cmake/activate\n\nwhere you replace `\u003cpath/to/\u003e` with the path to the appropriate directory.\n\nYour shell will now display the prefix `(dune-env)` to indicate that it is\nconfigured appropriately. You can exit the environent at any time by simply\nexecuting\n\n    deactivate\n\nNotice that any virtual environment only applies to, and lasts for, your\ncurrent terminal session!\n\n_With the virtual environment activated,_ you can now navigate to any directory\nthat you would like to contain your simulation input and/or output data.\n\n### Execute the application\nAny command to the DORiE application has the signature\n\n    dorie \u003ccmd\u003e [\u003copts\u003e] [\u003cargs\u003e]\n\nUsing the `-h` or `--help` option, you can find all available commands and\nfurther help. To start your first simulation run, create a new directory and\nenter it.\n\n#### 1 — Default input files\nCreate some exemplary configuration files along with parameter and boundary\ncondition data files by calling\n\n    dorie create\n\nThe data files are valid input files for very limited scenarios. The main\nconfiguration file `config.ini` requires tweaking by the user. Most `UNDEFINED`\nvalues must be properly defined before starting the simulation. A cheat sheet\nfor the single config file entries as well as manuals on how the boundary\ncondition and parameter files are used can be found in the user documentation.\n\n#### 2 — _Optional:_ Create a random field\nDORiE implements a lightweight wrapper around the `dune-randomfield`\ngenerator. You can use it to easily create a heterogeneous soil architecture.\nThis step is optional. Tweak the parameters of `parfield.ini` to your liking\nand then call\n\n    dorie pfg parfield.ini\n\nA cheat sheet for this config file is also available from the documentation.\n\n#### 3 — Perform a simulation\nThe DORiE main routine is executed with the `run` command.\nTweak the parameters of `config.ini` to your liking. You will need to\nreference several additional input files for soil parameters, boundary\nconditions, GMSH grid files (optional), and grid mappings (optional).\nRefer to the documentation for further information.\n\nOnce prepared, call\n\n    dorie run config.ini\n\nto execute the solver.\n\n## Troubleshooting\n\nCMake heavily caches the results of its configuration process. In case you\nencounter errors or strange behavior, especially after an update, you should\ndelete the DORiE build folder (called `build-cmake` by default) and re-build\nDORiE using `dunecontrol`.\n\nIf the problem persists, take a look at the\n[list of Issues](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues),\nand feel free to create an Issue yourself if the problem is not yet reported.\n\n### Debugging\nDORiE can be built with debugging flags via CMake. To do so, enter the\n`build-cmake` directory and execute\n\n    cmake -DCMAKE_BUILD_TYPE=Debug ..\n    make all\n\nAfter building, a debugger can hook into the executables.\n\n**Note:** If no `CMAKE_BUILD_TYPE` is specified during re-configuration, the\nlast configuration build type is used. If no CMake files exist, it defaults to\n`Release`. You will find the actual value displayed in the final output of\nCMake.\n\nTo re-create a release build, configure DORiE with the release build type by\nexecuting\n\n    cmake -DCMAKE_BUILD_TYPE=Release ..\n    make all\n\nor by calling `dunecontrol` with the supplied options file as indicated in the\ninstallation instructions above.\n\n### Running System Tests\nDORiE includes a testing system for comparing its results the ones of ODE\nsolvers or former versions of itself. This ensures that DORiE is running\ncorrectly and producing the expected results. We distinguish _unit tests_ for\ntesting certain features of the code, and _system tests_ for verifying the\nresults of the final application. As system tests require executing the DUNE\nsolvers, it is recommended to build them in a `Release` environment.\nAdditionaly, there is a set of tests for the Python module.\n\n| Test category | Build tests | Execute tests | Recommended build type |\n| ------------- | ----------- | ------------- | ---------------------- |\n| Unit tests | `make build_unit_tests` | `make unit_tests` | `Debug` |\n| System tests | `make build_system_tests` | `make system_tests` | `Release` |\n| Python tests | _Not required_ | `make test_python` | _Any_ |\n| Cookbook examples (no testing performed) | `make all` | `make example_tests` | `Release` |\n\nThe `make` commands are to be executed from within the `build-cmake` directory.\n\n#### Code Coverage Report\nTo enable code coverage reports, configure DORiE with the CMake option\n`COVERAGE_REPORT` enabled, like so (from the `build-cmake` directory):\n\n    cmake -DCOVERAGE_REPORT=On ..\n\nThis will add the appropriate compiler flags to _all_ targets. You then have to\nre-build all binaries. After running tests or executing the application, you\ncan retrieve code coverage information using the\n[`gcovr`](https://gcovr.com/index.html) utility.\n\n### Developing Python Code\nDORiE installs its Python module into the DUNE-controlled Python virtual\nenvironment (`venv`) during the CMake configuration phase. This means that\nchanges to its source code are only reflected after running CMake again. For\nless tedious Python code development, set the option\n`DUNE_PYTHON_INSTALL_EDITABLE` in the `build.opts` file to `TRUE`. This will\ninstall the Python packages in editable mode, meaning that they are \"symlinked\"\nto their original location and changes to the source code are immediately\nreflected inside the virtual environment.\n\nNote however, that this is not compatible with a re-locatable installation\nbecause editable installs require the source code in its original location.\n\n### Further Help\n[Open an Issue](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/new),\non GitLab or write to the\n[DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).\n","funding_links":[],"readme_doi_urls":["https://doi.org/10.21105/joss.02313"],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":["Diffusion-Reaction","Finite Element Method (FEM)","Multiple domains"],"project_url":"https://ost.ecosyste.ms/api/v1/projects/142846","html_url":"https://ost.ecosyste.ms/projects/142846"}