# DORiE Changelog ## Unreleased ### Added * DORiE now depends on [`yaml-cpp`](https://github.com/jbeder/yaml-cpp/), a library for reading YAML files. The version required is >=5.2.0. * New classes representing parameterizations. Every parameterization must now derive from `RichardsParameterization`, and return function objects representing parameterization functions. * Added a abstract base class [`SimulationBase`](dune/dorie/interface/base_simulation.hh) that models the concept of simulation steps so that they can be later coupled with other simulations. * Added an abstract base class [`SimulationBase`](dune/dorie/common/simulation_base.hh) that models the concept of simulation steps so that they can be later coupled with other simulations. * New classes representing parameterizations. Every parameterization must now derive from `RichardsParameterization`, and return function objects representing parameterization functions. * CMake module `DorieTesting.cmake`. The module contains multiple functions which facilitate registering tests in the two new testing categories: System tests and Unit tests. Unit tests are compiled with appropriate flags for code coverage reports. * Code coverage reports for unit tests. Detailed reports can be retrieved from the artifacts of the `test:unit-tests` test in the folder `build-cmake/test/coverage`. The total coverage is reported to GitLab. * New class [`SimulationTransport`](dune/dorie/interface/transport_simulation.hh) which solves the transport equation with a finite volume scheme for give grid functions of water content and velocity. * Grid function container to store transient grid functions !115 * Infrastructure for the input of Miller scaling fields. !110 * Add logging framework 'spdlog' as submodule !106 * Support input of boundary segmentations !119 * Reconstruction of continuous fluxes using RT finite elements !105 * Custom DG finite element map for simplices based on Pk polynomials !125 * Initial conditions expressed as analytic functions using [muparser](http://beltoforion.de/article.php?a=muparser) !131 * 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 * Linear interpolator for initial conditions and scaling fields !145, !156 * Parameterizations for hydrodynamic dispersion in solute transport !141 * Generic Python VTK file reader !143, !150 * Define compile-time settings via CPP macros !144 * [Google Test](https://github.com/google/googletest) unit test framework as Git Submodule !159 * Upwinding options for Richards finite volume local operator !161 ### Changed * `Simulation` is renamed `RichardsSimulation` and moved to [richards.hh](dune/dorie/model/richards/richards.hh). * `RichardsSimulation` now has its own `RichardsSimulationTraits` derived from `BaseTraits`, which defines all its member types. `BaseTraits` now have reduced content and are intended to be shared between models/simulations. * Data structures for storing and accessing parameters. The new class `FlowParameters` maps parameter sets and scaling factors to every grid cell on the coarsest grid level, and only stores one set of parameters for each soil layer. Before querying the parameterization functions, users need to call `FlowParameters::bind` with a grid entity to cache the appropriate data. All classes and functions querying parameter data have been updated. The old parameterization classes located in [`param_base.hh`](dune/dorie/solver/param_base.hh), [`param_factory.hh`](dune/dorie/solver/param_factory.hh), and [`param_van_genuchten.hh`](dune/dorie/solver/param_van_genuchten.hh) are still used for reading in data for the new storage scheme. The respective objects are freed once a simulation commences. * Grid adaptation now is done in two steps: (1) mark entities of the grid to refine/coarse and (2) adapt the grid and project the degrees of freedom on the new grid. The old parameterization classes have been removed. * `RichardsSimulation` now uses one vector of coefficients instead of two, which now is a `shared_ptr` instead a `unique_ptr`. * Every `VTKAdapter` is now able to be used as `GridFunctionAdapter` of the solution vector. * `GradientFluxAdapter` was reimplemented and renamed `WaterFluxAdapter`. * Every grid function adapter has its own file and are gathered in the subdirectory [dune/dorie/model/richards/adapters](dune/dorie/model/richards/adapters). * `VTKAdapters` are now managed with `shared_ptr` instead of references. * `OutputWriter` class is deprecated in favor of an minimal extension of the usual `VTKSequenceWriter` for grid functions called `GridFunctionVTKSequenceWriter`. * `RichardsSimulation` now models the `SimulationBase` class (See details in https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/94). For this, several methods were renamed with basically no change in behaviour. * `RichardsSimulation` and `TimeController` are able to receive a suggestion for the next timestep. * Static const `bool`s for adaptivity and output writing in `BaseTraits` were removed in favor of run-time policies (See details in https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/94). * Swich to the stable release branch `releases/2.6` of `dune-testtools`. * The `build` CI stage now explicitly builds system tests and unit tests. The job `build:main` has been removed. The `build:debug` jobs now build the unit test targets. * Merge Python packages into single new package `dorie`. * Executables and files of unit-tests and system-tests are now located in [`dune/dorie/test/`](dune/dorie/test/) and [`test/`](test/) respectively. * The `dorie` CLI has been moved into the DORiE Python package. It can now only be invoked after activating the DUNE virtual environment. The usage instructions in docs and `README.md` have been updated accordingly. * Soil architecture and parameter input has been completely revised. DORiE now expects a YAML file containing parameterization data and separate domain mapping data which can be supplied through the input GMSH file, or as H5 dataset. See the documentation for more information. Several keys in the main routine config file have been changed. See [#86](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/86). * The Parameter Field Generator (PFG) module has been revised and does not write parameterization data anymore. It can be used to create mappings for heterogeneous media through the binary converter, or continuous scaling fields (feature pending). Several keys in the PFG config file have been changed. See [#86](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/issues/86). * Improved and refurbished `Dorie::H5File`. The source file was renamed to `dune/dorie/common/util_h5file.hh`. The `read_dataset` function is now capable of directly opening dataset paths that contain groups. * The following changes were done in order to have a consistent API to support different models: * Folder structure has changed to a model based structure: in the main [C++ source directory](dune/dorie/) there now is a `common` folder, and a folder for `model` containing the source files for each model. * The API has been updated to support several models: from now, categories that target a specific model has to be preceded by a keyword identifying the corresponding model (e.g. `richards.initial`, `richards.output`, etc.), while common categories stay with no prefix at all (e.g. `grid`, `adaptivity`, etc.). * The parameter scraper now accepts the argument `--model ` which adds the prefix `.` to every category in the scraper. This helps to be able to use the method `sub()` from the `ParameterTree` object. It dumps its data into a YAML file which is then loaded for writing the default configuration files and the cheat sheet. * Use logging framework 'spdlog' for all terminal output !106 * DORiE now writes vertex data by default. #129 * Switch license from MIT to GPLv3 !135 * 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 * Finite volume solver for the Richards equation !132 * Build independent library and executable for each compile-time setting !144 * `SimulationBase` unit test now uses Google Test !159 * Deploy online documentation for each branch to private server !163 ### Fixed * Solver in `RichardsSimulation` was using the wrong time variable. [!116](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/merge_requests/116) * Shape of input datasets was flipped when loading scaling factors !124 ### Deprecated * The configuration file key `[parameters.interpolation]` is deprecated due to the new scheme for storing parameterization data. DORiE now only supports nearest-neighbor interpolation of parameters and scaling factors. * The `adaptivity.useAdaptity` keyword is deprecated, please use the new keyword `adaptivity.policy` (see the [DORiE Configuration File Guide documentation](https://dorie-doc.netlify.com/quickstart-parameters.html#main-routine) for details). ### Removed * The class `H5File::AttributeReader` was completely removed. * Boundary conditions `evaporation` and `limitedInflux` !120 ## 1.1.1 (2018-08-21) ### Added * Documentation of Docker images and their usage in the CI/CD pipeline. ### Changed * Rebuilds of the DUNE environment Docker image are now triggered by setting the CI variable `REBUILD_BASE_IMAGE` to a non-empty value. Previously, the builds in stage `setup` where triggered by any manual pipeline run. * The test system folder was renamed from `testing` to [`test`](test). * File `operator_DG.hh` is renamed [`richards_operator_DG.hh`](dune/dorie/solver/richards_operator_DG.hh) ### Fixed * Removed VTK output from `dorie_mass_conservation` executable, which would cause the corresponding test to fail if the designated output directory did not exist. * Removed CI artifacts of `test` stage from `deploy` jobs. * Correctly estimate the number of row entries in the matrix backend based on the DG discretization and proper static blocking. This can lead to a performance improvement for large problems. * VTK output is now written _before_ the grid is adapted. Previously, the output displayed the adapted grid and not the one the solution was computed on. * Grid adaptation is skipped after computing the final solution. * Path to Pipeline artifacts for `test` stage. The artifacts are now correctly captured and can be viewed and downloaded from the GitLab web interface. * Fix a bug in the boundary condition evaluation where an `end()` iterator was dereferenced without error. * Re-introduced deployment of the documentation which can now be found online at https://dorie-doc.netlify.com/. ## 1.1.0 (2018-07-27) ### Added * DORiE now employs a `SubsamplingVTKWriter` for higher output precision. Subsampling levels are controlled via the new key `output.subsamplingLevel`. * Automatic deployment of `devel` and stable DORiE Docker Images to Docker Hub. * Automatic update of the DUNE environment Docker Image for `master` builds. * CI pipeline now also compiles a Debug build with the LLVM Clang compiler. * Add `.gitattributes` for `CHANGELOG.md` to reduce merge conflicts with `merge=union`. * Public API definition in documentation. ### Changed * Update code base to *DUNE v2.6*. * Raise software requirements to versions available on Ubuntu 18.04 LTS (Bionic Beaver). * Switch VTK output from conforming to non-conforming. * Use `multicore` build tag only for `test:parallel` build because the current GitLab Runner cannot handle the load. * Use the `OVLP_AMG_4_DG` linear solver for all computations, including sequential ones. This significantly improves performance for large problems. * Change compilation order which reduces RAM usage when compiling in parallel. * Decentralization of the header system so that in most of the header files are independent of each other. ### Deprecated * `output.subsamplingLevel` is optional and defaults to 0 if not given explicitly in the config file. The key will become mandatory in future versions. ### Removed * Complete doxygen documentation from Sphinx docs. ### Fixed * The source code is now compatible to the Clang LLVM compiler. DORiE can now be compiled with the onboard compiler on macOS. * Fix finite element map used for simplex grids. The old one did not implement a discontinuous function space. * Allow warnings on ParMETIS not being available for parallel computations. ## 1.0.0 (2018-03-28) First stable version.