From adebfca6a35a2263d154355de1e81c556bee9c70 Mon Sep 17 00:00:00 2001 From: OlofBaltus <112857147+OlofBaltus@users.noreply.github.com> Date: Fri, 22 Dec 2023 15:59:23 +0100 Subject: [PATCH 1/4] eerste opbouw van water kwaliteit --- source/a_how_to.rst | 1 + source/a_howto_add_external_modules.rst | 11 +++++++++++ source/h_water_quality.rst | 5 +++++ source/index.rst | 1 + 4 files changed, 18 insertions(+) create mode 100644 source/a_howto_add_external_modules.rst create mode 100644 source/h_water_quality.rst diff --git a/source/a_how_to.rst b/source/a_how_to.rst index b3ba1855..5d7fe888 100644 --- a/source/a_how_to.rst +++ b/source/a_how_to.rst @@ -19,4 +19,5 @@ If want to become familiar with the basics of working with 3Di and its common wo a_howto_convert_to_1d2d a_howto_use_inflow a_howto_combine_0d_rain + a_howto_add_external_modules d_vegetation_howto diff --git a/source/a_howto_add_external_modules.rst b/source/a_howto_add_external_modules.rst new file mode 100644 index 00000000..54b3a642 --- /dev/null +++ b/source/a_howto_add_external_modules.rst @@ -0,0 +1,11 @@ +.. _howto_add_external_modules: + +How to add external modules +=========================== + +External modules in 3Di are developed to add extra features to your model which are apart from the direct hydrodynamics. Currently, only water quality is implemented as external module. In the future als morphodynamics will be implemented as external module in 3Di. In this section will be explained how these external modules can be implemented in your simulation. + +Water Quality +----------------------------- + +This external module can be added if you want to calculate the water quality in your model. The technical functioning of this module is explained in :ref:`water_quality`. At this point waterquality can only be added through the use of the 3Di api. \ No newline at end of file diff --git a/source/h_water_quality.rst b/source/h_water_quality.rst new file mode 100644 index 00000000..ae51b449 --- /dev/null +++ b/source/h_water_quality.rst @@ -0,0 +1,5 @@ +.. _water_quality: + +Water Quality +------ +In the current state water quality can only \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 900cba1b..e5a864d5 100755 --- a/source/index.rst +++ b/source/index.rst @@ -69,6 +69,7 @@ Table of contents h_grid h_flow h_simulation_settings + h_water_quality h_outputs From 139ee424b8dcfa73680ff8e31aa2f6f19a1b3873 Mon Sep 17 00:00:00 2001 From: OlofBaltus <112857147+OlofBaltus@users.noreply.github.com> Date: Mon, 22 Jan 2024 13:35:25 +0100 Subject: [PATCH 2/4] - intermediate result --- source/a_howto_add_external_modules.rst | 9 ++------- source/h_logging.rst | 9 ++++++++- source/h_outputs.rst | 1 + source/h_results.rst | 2 +- source/h_water_quality_results.rst | 10 ++++++++++ 5 files changed, 22 insertions(+), 9 deletions(-) create mode 100644 source/h_water_quality_results.rst diff --git a/source/a_howto_add_external_modules.rst b/source/a_howto_add_external_modules.rst index 54b3a642..bb583f4e 100644 --- a/source/a_howto_add_external_modules.rst +++ b/source/a_howto_add_external_modules.rst @@ -1,11 +1,6 @@ .. _howto_add_external_modules: -How to add external modules +Use water quality =========================== -External modules in 3Di are developed to add extra features to your model which are apart from the direct hydrodynamics. Currently, only water quality is implemented as external module. In the future als morphodynamics will be implemented as external module in 3Di. In this section will be explained how these external modules can be implemented in your simulation. - -Water Quality ------------------------------ - -This external module can be added if you want to calculate the water quality in your model. The technical functioning of this module is explained in :ref:`water_quality`. At this point waterquality can only be added through the use of the 3Di api. \ No newline at end of file +This external module can be added if you want to calculate the water quality in your model. The technical functioning of this module is explained in :ref:`water_quality`. At this point waterquality can only be added through the use of the 3Di api. The waterquality has two options to add substance to your model. The first, add a substance by intitial value and the second add substance via one of the model forcings. diff --git a/source/h_logging.rst b/source/h_logging.rst index 2b0ba882..2f43112f 100644 --- a/source/h_logging.rst +++ b/source/h_logging.rst @@ -6,12 +6,19 @@ Log files Flow summary ------------ -File name: flow_summary.log +File name: flow_summary.json This file provides a full water balance of the entire model domain for the entire simulation duration. It is recommended to always check this file after the simulation has finished. The maximum volume error is also included in the volume balance; large volume errors are an indication that there may be something wrong with the schematisation. What constitutes a large volume error depends on the size of the model and the type of forcing that is used. By frequently inspecting the flow summary, an expert judgement can be trained to judge wether the volume error is normal. In very general terms, volume errors above 10 m³ are somewhat large; if the volume error is more than 1.000 m³, there is almost certainly something wrong with the schematisation. +Water quality substance summary +------------ + +File name: water_quality_substance_summary.json + +This file provides de the substance balance when water quality is implemented in a simulation. It is recommended to check this file for any inconsistencies in the substance balance. + Iteration --------- diff --git a/source/h_outputs.rst b/source/h_outputs.rst index 7822876a..6eaf54ab 100644 --- a/source/h_outputs.rst +++ b/source/h_outputs.rst @@ -7,5 +7,6 @@ Outputs :maxdepth: 1 h_results + h_water_quality_results h_aggregate_results h_logging \ No newline at end of file diff --git a/source/h_results.rst b/source/h_results.rst index b399a79a..fa059a52 100644 --- a/source/h_results.rst +++ b/source/h_results.rst @@ -7,7 +7,7 @@ The results of a simulation are written to a `NetCDF `_ file called `results_3di.nc`, which follows the `CF Conventions `_ . The CF convention stipulates that the 2D and 1D mesh data are stored in separate parts of the file. The results_3di.nc file contains snapshots of values of all relevant flow variables (1D and 2D). The output timestep, i.e. the interval at which these snapshot values are written to the NetCDF file, is set at the start of the simulation. + +The file size is determined by the output time step, the size of the model (number of nodes and flowlines), and the duration of the simulation. + +In addition to these snap shots, 3Di can generate aggregated results. More about this can be found in :ref:`aggregationnetcdf`. \ No newline at end of file From de29abdcaa8adbc212191ef5fe305208592661a6 Mon Sep 17 00:00:00 2001 From: OlofBaltus <112857147+OlofBaltus@users.noreply.github.com> Date: Mon, 22 Jan 2024 13:58:55 +0100 Subject: [PATCH 3/4] Update h_water_quality_results.rst --- source/h_water_quality_results.rst | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/source/h_water_quality_results.rst b/source/h_water_quality_results.rst index 71ee4a22..8440bceb 100644 --- a/source/h_water_quality_results.rst +++ b/source/h_water_quality_results.rst @@ -3,8 +3,30 @@ Water quality results 3Di ================= -The results of a simulation are written to a `NetCDF `_ file called `results_3di.nc`, which follows the `CF Conventions `_ . The CF convention stipulates that the 2D and 1D mesh data are stored in separate parts of the file. The results_3di.nc file contains snapshots of values of all relevant flow variables (1D and 2D). The output timestep, i.e. the interval at which these snapshot values are written to the NetCDF file, is set at the start of the simulation. +The results of a simulation are written to a `NetCDF `_ file called `water_quality_results_3di.nc`, which follows the `CF Conventions `_ . The CF convention stipulates that the 2D and 1D mesh data are stored in separate parts of the file. The results_3di.nc file contains snapshots of values of all relevant flow variables (1D and 2D). The output timestep, i.e. the interval at which these snapshot values are written to the NetCDF file, is set at the start of the simulation. -The file size is determined by the output time step, the size of the model (number of nodes and flowlines), and the duration of the simulation. +Water quality results can be retrieved from the nodes in the 1D and 2D. The amount of variables in your netcdf depends on the amount of added substances in the model. A overview of the configuration of the variables is given below. -In addition to these snap shots, 3Di can generate aggregated results. More about this can be found in :ref:`aggregationnetcdf`. \ No newline at end of file +**Water quality Variables 2D**. + + Mesh2D_substance_1_2D: Concentration of substance 1 at the specified node. + + - Name: substance_1_2D + - Unit: substance per m3 + + Mesh2D_substance_2_2D: Concentration of substance 2 at the specified node. + + - Name: substance_2_2D + - Unit: substance per m3 + +**Water quality Variables 1D**. + + Mesh2D_substance_1_2D: Concentration of substance 1 at the specified node. + + - Name: substance_1_1D + - Unit: substance per m3 + + Mesh2D_substance_2_2D: Concentration of substance 2 at the specified node. + + - Name: substance_1_1D + - Unit: substance per m3 From bc75a6aae11a1dd374dc1a80b67f4117edb7f4ef Mon Sep 17 00:00:00 2001 From: leendertvanwolfswinkel Date: Wed, 31 Jan 2024 17:25:17 +0100 Subject: [PATCH 4/4] MVP --- source/a_how_to.rst | 2 +- source/a_howto_add_external_modules.rst | 6 ---- source/a_howto_use_water_quality.rst | 41 +++++++++++++++++++++++++ source/h_logging.rst | 6 ++-- source/h_water_quality.rst | 18 +++++++++-- source/h_water_quality_results.rst | 17 ++++++++-- 6 files changed, 75 insertions(+), 15 deletions(-) delete mode 100644 source/a_howto_add_external_modules.rst create mode 100644 source/a_howto_use_water_quality.rst diff --git a/source/a_how_to.rst b/source/a_how_to.rst index 5d7fe888..4b81f5b8 100644 --- a/source/a_how_to.rst +++ b/source/a_how_to.rst @@ -19,5 +19,5 @@ If want to become familiar with the basics of working with 3Di and its common wo a_howto_convert_to_1d2d a_howto_use_inflow a_howto_combine_0d_rain - a_howto_add_external_modules + a_howto_use_water_quality d_vegetation_howto diff --git a/source/a_howto_add_external_modules.rst b/source/a_howto_add_external_modules.rst deleted file mode 100644 index bb583f4e..00000000 --- a/source/a_howto_add_external_modules.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _howto_add_external_modules: - -Use water quality -=========================== - -This external module can be added if you want to calculate the water quality in your model. The technical functioning of this module is explained in :ref:`water_quality`. At this point waterquality can only be added through the use of the 3Di api. The waterquality has two options to add substance to your model. The first, add a substance by intitial value and the second add substance via one of the model forcings. diff --git a/source/a_howto_use_water_quality.rst b/source/a_howto_use_water_quality.rst new file mode 100644 index 00000000..cce78200 --- /dev/null +++ b/source/a_howto_use_water_quality.rst @@ -0,0 +1,41 @@ +.. _howto_use_water_quality: + +Use water quality +================= + +3Di can be used in water quality assessments. More specifically, you can introduce concentrations of substances to the simulation, and compute how these substances spread through the water system due to advective forces and (numerical) diffusion. See :ref:`water_quality`. + +Running water quality simulations +--------------------------------- + +Simulations with water quality can be run with any 3Di model. You do not need to make any changes to the model schematisation. + +It involves the following steps: + +- Define one or more substances that you want to use in the simulation, e.g. "Benzene hexachloride", "Biological Oxygen Demand (BOD)", or "Contaminant". + +.. note: + + All substances must be defined at the start of the simulation (the substances themselves, not their concentrations). You cannot define new substances while the simulation is already running. + +- If the simulation includes initial water (in the 1D and/or 2D domain), you may set an initial concentration of the substance(s) you have defined in the initial water. + +- If the simulation includes forcings, such as rain, boundary conditions, or laterals, you may add a concentration of the substance(s) you have defined to these forcings. Each forcing can contain concentrations of multiple substances at the same time. + +.. note:: + The way substance concentrations are defined, mirrors the way that the initials or forcings are defined. I.e., 2D initial water levels are supplied as a raster, so 2D initial substance concentrations are also supplied as a raster; substance concentrations in time series rain is also provided as a time series; et cetera. + +- Run the simulation in the same way as you are used to + +- Currently, there is not yet a graphical user interface for adding substances to simulations. Use the :ref:`a_api` to use this functionality. + +Viewing and analysing water quality results +------------------------------------------- + +The results of a water quality simulation are the concentrations of each substance at each node, for each output time step. These values are written to a :ref:`separate NetCDF file`. + +You can visualise these concentrations by plotting a graph of the concentration of a substance at specific locations over time. Or you can generate a map of the substance concentrations at a specific moment in time, e.g. by scaling the color of the nodes or cells by their concentration. + +Currently, there is not yet a graphical user interface for visualising water quality results. Use :ref:`threedigrid` to do this. + +A summary of the water quality calculations is available in the simulation logging. This :ref:`log file` includes a substance summary, similar to the flow summary. diff --git a/source/h_logging.rst b/source/h_logging.rst index 2f43112f..bfb1bf59 100644 --- a/source/h_logging.rst +++ b/source/h_logging.rst @@ -12,12 +12,14 @@ This file provides a full water balance of the entire model domain for the entir The maximum volume error is also included in the volume balance; large volume errors are an indication that there may be something wrong with the schematisation. What constitutes a large volume error depends on the size of the model and the type of forcing that is used. By frequently inspecting the flow summary, an expert judgement can be trained to judge wether the volume error is normal. In very general terms, volume errors above 10 m³ are somewhat large; if the volume error is more than 1.000 m³, there is almost certainly something wrong with the schematisation. +.. _wq_logging: + Water quality substance summary ------------- +------------------------------- File name: water_quality_substance_summary.json -This file provides de the substance balance when water quality is implemented in a simulation. It is recommended to check this file for any inconsistencies in the substance balance. +This file provides the substance balance when water quality is used in a simulation. It is recommended to check this file for any inconsistencies in the substance balance. Iteration --------- diff --git a/source/h_water_quality.rst b/source/h_water_quality.rst index ae51b449..079a8342 100644 --- a/source/h_water_quality.rst +++ b/source/h_water_quality.rst @@ -1,5 +1,17 @@ .. _water_quality: -Water Quality ------- -In the current state water quality can only \ No newline at end of file +Water quality +------------- + +3Di has a module that can be used for water quality calculations. More specifically, you can introduce concentrations of substances to the simulation, and compute how these substances spread through the water system due to advective forces and (numerical) diffusion. + +- Substances can enter the model domain as concentrations in initial water, boundary conditions, laterals, rain, leakage, surface sources and sinks. This applies to the entire model domain (1D, 2D, and groundwater). + +- Each forcing can contain concentrations of multiple substances at the same time + +- The :ref:`output of water quality simulations` is in NetCDF format; the file has the same structure as hydrodynamic results (results_3di.nc). + +.. warning:: + + You cannot add multiple laterals to a single node or cell if they have different substance concentrations + diff --git a/source/h_water_quality_results.rst b/source/h_water_quality_results.rst index 8440bceb..4d44c50f 100644 --- a/source/h_water_quality_results.rst +++ b/source/h_water_quality_results.rst @@ -1,11 +1,11 @@ .. _wq_netcdf: Water quality results 3Di -================= +========================= -The results of a simulation are written to a `NetCDF `_ file called `water_quality_results_3di.nc`, which follows the `CF Conventions `_ . The CF convention stipulates that the 2D and 1D mesh data are stored in separate parts of the file. The results_3di.nc file contains snapshots of values of all relevant flow variables (1D and 2D). The output timestep, i.e. the interval at which these snapshot values are written to the NetCDF file, is set at the start of the simulation. +The water quality results of a simulation are written to a `NetCDF `_ file called *water_quality_results_3di.nc*, which follows the `CF Conventions `_ . The CF convention stipulates that the 2D and 1D mesh data are stored in separate parts of the file. The *water_quality_results_3di.nc* file contains snapshots of concentrations at nodes (1D and 2D). The output timestep, i.e. the interval at which these snapshot values are written to the NetCDF file, is set at the start of the simulation. -Water quality results can be retrieved from the nodes in the 1D and 2D. The amount of variables in your netcdf depends on the amount of added substances in the model. A overview of the configuration of the variables is given below. +Water quality results can be retrieved from the nodes in the 1D and 2D. The amount of variables in the netcdf depends on the amount of added substances in the model. An overview of the configuration of the variables is given below. **Water quality Variables 2D**. @@ -19,6 +19,12 @@ Water quality results can be retrieved from the nodes in the 1D and 2D. The amou - Name: substance_2_2D - Unit: substance per m3 + Mesh2D_substance_*n*_2D: Concentration of substance *n* at the specified node. + + - Name: substance_*n*_2D + - Unit: substance per m3 + + **Water quality Variables 1D**. Mesh2D_substance_1_2D: Concentration of substance 1 at the specified node. @@ -30,3 +36,8 @@ Water quality results can be retrieved from the nodes in the 1D and 2D. The amou - Name: substance_1_1D - Unit: substance per m3 + + Mesh2D_substance_*n*_2D: Concentration of substance *n* at the specified node. + + - Name: substance_*n*_1D + - Unit: substance per m3