Merge pull request #428 from nens/release-june-2024-pt2

Some improvements after review plus water quality "how to" improvement

source/a_howto_use_water_quality.rst

@@ -1,7 +1,8 @@
 .. _howto_use_water_quality:
 
-Use water quality
-=================
+
+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`.
 
@@ -14,28 +15,53 @@ 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. 
+    .. 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.
+
+    .. 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.
+Water quality simulations in the 3Di Modeller Interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The water quality module can be used in simulations started from the 3Di Modeller Interface. 
+
+At the moment, the simulation wizard supports adding substances to laterals only. 
+
+Follow the :ref:`same workflow as for starting any other simulation <simulate_api_qgis>`, with the following additional steps.
+
+.# On the scenario options page that is shown before the simulation wizard starts, check the box *Include substances*
+.# After having filled in the *Name* and *Duration* pages, the :ref:`simulation_wizard_substances` page lets you define the substances that you want to use in the simulation.
+.# On the :ref:`simulate_api_qgis_laterals` page, upload a CSV for 1D or 2D laterals and a :ref:`CSV with time series of concentrations <laterals_substance_concentrations>` for each of the substances that you want to add to your simulations.
+.# Go through the rest of the steps of the simulation wizard to start the simulation
+
+Water quality simulations using the 3Di API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to use water quality features that are not yet supported in the 3Di Modeller Interface, such as substance decay or adding substance concentrations to forcings other than laterals, you can use the :ref:`a_api` directly. Contact the :ref:`servicedesk` for example scripts that fit your specific purpose.
+
 
 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<wq_netcdf>`.
 
-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.
+A summary of the water quality calculations is available in the simulation logging. This :ref:`log file<wq_logging>` includes a substance summary, similar to the flow summary.
 
-Currently, there is not yet a graphical user interface for visualising water quality results. Use :ref:`threedigrid` to do this.
+At the moment, the :ref:`time_series_plotter` is the 3Di Results Analysis tool with support for the 3Di water quality module.
 
-A summary of the water quality calculations is available in the simulation logging. This :ref:`log file<wq_logging>` includes a substance summary, similar to the flow summary.
+.# :ref:`Download the simulation results <dl_via_models_simulations>` via the 3Di Models & Simulations panel. The :ref:`wq_netcdf` file will also be downloaded.
+.# Load the results using the :ref:`3Di Results Manager<3di_results_manager>`
+.# Open the :ref:`time_series_plotter`
+.# Add one or more nodes to the plot
+.# In the *Variable* dropdown menu in the Time series plotter, select the substance you want to see the concentration for.
+
+For other visualisations of substance concentrations, e.g. as a map of the substance concentrations at a specific moment in time, or an animation of such maps, use :ref:`threedigrid`. Contact the :ref:`servicedesk` for example scripts that fit your specific purpose.

source/a_releasenotes_3di_mi.rst

@@ -9,7 +9,7 @@ June 5th, 2024
 3Di Results Analysis 3.8.1
 """"""""""""""""""""""""""
 
-- Time series plotter: allow users to choose substance concentrations as variable (#975)
+- Time series plotter: you can now plot substance concentrations for individual nodes in the Time series plotter (#975)
 
 - Result layers in the Result Aggregation, Cross-Sectional Discharge, and Watershed tools now have the exact same fields and field names as the input node, cell, and flowline layers (#914) 
 
@@ -34,7 +34,7 @@ June 5th, 2024
 
 - Several new features and improvements have been implemented in the Simulation wizard:
 
-	- The laterals page has been improved (#467) 
+	- The laterals page has been improved (#467). See :ref:`simulate_api_qgis_laterals` for more information.
 
 	- The CSV file format requirements for :ref:`simulate_api_qgis_boundary_conditions`, :ref:`simulate_api_qgis_laterals`, and :ref:`dry_weather_flow` have been made less strict (#560)
 
@@ -62,27 +62,35 @@ June 5th, 2024
 
 	- Channel ID is filled in when drawing a potential breach (#230)
 
-	- When moving or changing the geometry of schematisation objects, related objects are also moved (topological editing). The implementation of topological editing has been improved to make it more consistent (#219, #220, #232). The new implementation is:
+	- When moving or changing the geometry of schematisation objects, related objects are also moved (topological editing). The implementation of topological editing has been improved to make it more consistent (#219, #220, #232).
+
 		- General topological editing for Connection nodes; when moving a connection node, all schematisation objects that are connected to it are also affected.
-		- Specific logic for Channels:
+
+		- Specific logic for Channels
+
 			- Cross-section locations are topologically edited when a Channel geometry is edited. Cross-section location can be on a channel vertex or segment.
+
 			- Potential breaches (start vertex) are topologically edited when Channel geometry is edited. Start vertex of a Potential breach can be on a channel vertex or segment.
-		- Specific logic for Impervious surface:
-			- Impervious surface map is topologically edited when Impervious surface geometry changes. The start vertex of the Impervious surface map is on the *point on surface* of the Impervious surface
-		- Specific logic for Surface:
+
+		- Specific logic for Impervious surface
+
+			- Impervious surface map is topologically edited when Impervious surface geometry changes. The start vertex of the Impervious surface map is on the *point on surface* of the Impervious surface.
+
+		- Specific logic for Surface
+
 			- Surface map is topologically edited when Surface geometry changes. The start vertex of the Surface map is on the *point on surface* of the Surface
 
 - Several improvements have been made to the **vector data importers**:
 
-	- Vector data importers: do not commit changes (#228)
+	- Changes to the layers affected by the import are no longer committed automatically, so that you can review the added features before deciding to commit them to the layer (#228)
 
-	- Vector data importer: try to convert incompatible geometries to singlepart Point/Polygon/Linestring (#222)
+	- If geometries in the source layer are different from the geometry type of the target layer, the vector data importer will try to convert them to a compatible type. For example, multipart to singlepart, or MultiCurve to polygon (#222)
 
-	- Vector data importer: add "expression" as a method (#211)
+	- "Expression" has been added as a method to convert source attributes to target attributes (#211). This can be used e.g. to convert millimeters to meters, to create a code from a combination of source attributes, or to apply more complex if/then/else logic to the source attributes.
 
-	- Vector data importer: auto-select source attribute if it matches target attribute#190
+	- Source attributes are automatically selected if they have the same name as the target attribute (#190)
 
-	- Import manholes: skip manholes that are snapped to connection nodes that already have a manhole (#224)
+	- Import manholes: source manholes are skipped if they are snapped to connection nodes that already have a manhole (#224)
 
 - In the processing algorithm "Map (impervious) surfaces to connection nodes", the option has been added to use "Selected features only" for all vector layer inputs (#227)
 

source/a_releasenotes_computational_core.rst

@@ -6,7 +6,7 @@
 June 5, 2024
 ^^^^^^^^^^^^
 
-- Add two step method corrector for water quality calculations to improve stability and reduce numerical diffusion (#794)
+- In the water quality module, a discretisation method has been implemented that improves the stability and reduces numerical diffusion. It uses a combination of explicit and implicit solving methods. This two-step method overcomes limitations of the accurate explicit method and ensures stability with the implicit part of the method. (#794)
 
 - Improved stability of water quality calculations in case of shallow, fast flowing water (#795)
 

source/h_water_quality.rst

@@ -7,7 +7,19 @@ Water quality
 
 - 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
+- Each forcing can contain concentrations of one or multiple substances
+
+- Units can be defined for each substance
+
+- A decay coefficient (s\ :sup:`-1`) can be defined for each substance. If the decay coefficient is specified, the substance decreases at a rate that is proportional to the current concentration; the substance will decay exponentially in time. The decay coefficient is inversely proportional to a so-called mean lifetime (T). The decay coefficient is defined as 
+
+.. math::
+   :label: Decay coefficient
+
+   C_{decay} = frac{1}{T}
+
+| where: 
+| :math:`T`: mean lifetime in seconds
 
 - The :ref:`output of water quality simulations<wq_netcdf>` is in NetCDF format; the file has the same structure as hydrodynamic results (results_3di.nc).