From 3ebc502ae1dc91f61409de53fb883510866699f4 Mon Sep 17 00:00:00 2001 From: Cinzia Mazzetti Date: Mon, 2 Dec 2024 18:38:12 +0000 Subject: [PATCH] updating model documentation --- docs/3_step3_preparing-setting-file/index.md | 57 ++++++++++++++++++-- docs/3_step4_preparing-input-files/index.md | 6 +-- docs/4_Static-Maps_channel-geometry/index.md | 5 ++ docs/4_annex_input-files/index.md | 1 + docs/4_annex_output-files/index.md | 3 +- docs/4_annex_settings_and_options/index.md | 25 ++++++++- docs/4_annex_tests/index.md | 21 ++++++++ 7 files changed, 109 insertions(+), 9 deletions(-) diff --git a/docs/3_step3_preparing-setting-file/index.md b/docs/3_step3_preparing-setting-file/index.md index baa75acb..0cca1871 100644 --- a/docs/3_step3_preparing-setting-file/index.md +++ b/docs/3_step3_preparing-setting-file/index.md @@ -378,6 +378,41 @@ These parameters are all related to the [routing of water in the channels](https +### Diffusive wave routing parameters + +The following parameters are related to the [diffusive wave routing](https://ec-jrc.github.io/lisflood-model/3_14_optLISFLOOD_diffusive-wave/) in river channels. The multiplier *CalChanMan3* can be used to fine-tune the diffusive wave propagation when using the Muskingum-Cunge-Todini (MCT) routing, and it can be defined as either a single value or a map. The map *ChannelsMCT* is a Bolean map with the mask of rivers where MCT wave routing must be used. The parameter *ChanGradMaxMCT* defines the maximum riverbed slope for river grid cells using the MCT wave routing. The parameter is provided as a single number and it is recommended to set it to values < 0.001 and > *ChanGradMin* +```xml + + ************************************************************** + MUSKINGUM-CUNGE-TODINI ROUTING PARAMETERS + ************************************************************** + + + + default: 3.0 [-] + Multiplier [-] applied to Channel Manning's n for MCT routing + + + + + Boolean map with value 1 at channel pixels where MCT is + used, and 0 at all other pixels + + + + + Maximum channel gradient for channels using MCT routing [-] (for MCT wave: slope cannot be 0) + Default: 0.001 + + +``` + +- **CalChanMan3** is a multiplier that is applied to the Manning’s roughness map of the [channel system](https://ec-jrc.github.io/lisflood-model/2_16_stdLISFLOOD_channel-routing/) [-] for the grid cells where MCT routing is used +- **ChannelsMCT** is Bolean mask including the rivers grid cells using the MCT wave routing [-] +- **ChanGradMaxMCT** is a upper limit for the channel gradient used in the calculation of the MCT wave routing [m/m] + + + ### Parameters related to numerics This category only contains one parameter at the moment, which can only be a single value. We strongly recommend keeping this parameter at its default value. @@ -530,8 +565,8 @@ Note that a couple of variables can be [initialized internally](https://ec-jrc.g -************************************************************** - The following variables can also be initialized in the model internally. if you want this to happen set them to bogus value of -9999 + ************************************************************** + The following variables can also be initialized in the model internally. If you want this to happen set them to bogus value of -9999 ************************************************************** @@ -571,7 +606,19 @@ Note that a couple of variables can be [initialized internally](https://ec-jrc.g only needed for lakes reservoirs and transmission loss -9999: use discharge of half bankfull - + + + + Courant number at previous step for MCT routing + Cold start: -9999: use 1 + + + + + Reynolds number at previous step for MCT routing + Cold start: -9999: use 0 + + ``` - **WaterDepthInitValue** is the initial amount of water on the soil surface $[mm]$ @@ -604,6 +651,10 @@ Note that a couple of variables can be [initialized internally](https://ec-jrc.g - **PrevDischarge** is the initial discharge from previous run $[\frac{m^3} {s}]$ used for lakes, reservoirs and transmission loss (only needed if option is on for lakes or reservoirs or transmission loss). Note that PrevDischarge is discharge as an average over the time step (a flux) . A value of **-9999** sets the initial amount of discharge to equivalent of half bankfull. +- **PrevCmMCTInitValue** is the Courant number at the end of the previous step and it is only used for MCT wave routing [-]. A value of **-9999 ** sets the initial value to 1. + +- **PrevDmMCTInitValue** is the Reynols number at the end of the previous step and it is only used for MCT wave routing [-]. A value of **-9999 ** sets the initial value to 0. + ```xml ************************************************************** diff --git a/docs/3_step4_preparing-input-files/index.md b/docs/3_step4_preparing-input-files/index.md index 1f041c64..efde4f2c 100644 --- a/docs/3_step4_preparing-input-files/index.md +++ b/docs/3_step4_preparing-input-files/index.md @@ -31,7 +31,7 @@ The section [Static Maps](../4_Static-Maps-introduction) provides detailed guide + [land use maps](../4_Static-Maps_land-use/): fraction of forest; fraction of irrigated crops; fraction of rice crops; fraction of inland water; fraction of sealed surfaces; fraction of other land uses. + [land use depending](../4_Static-Maps_land-use-depending/):crop coefficient; crop group number; Manning/s's surface roughness; soil depth. + [soil hydraulic properties](../4_Static-Maps_soil-hydraulic-properties/): saturated hydraulic conductivity; soil water content at saturation; residual soil water content; parameters alpha and lambda of Van Genuchten's equations. -+ [channel geometry](../4_Static-Maps_channel-geometry/): channels mask; channels side slope; channels length; channels gradient; Manning's rougheness coefficient of the channels; channels bottom width; floodplain width; bankfull channels depth. ++ [channel geometry](../4_Static-Maps_channel-geometry/): channels mask; channels side slope; channels length; channels gradient; Manning's rougheness coefficient of the channels; channels bottom width; floodplain width; bankfull channels depth; MCT diffusive wave routing channels. + [leaf area index](../4_Static-Maps_leaf-area-index/): evolution of vegetation over time (leaf area index) for land covers forest, irrigated areas, others. + [reservoirs and lakes](../4_Static-Maps_reservoirs-lakes/): lake mask; lakes ID points; reservoirs ID points. These maps are required only upon activation of the [lakes module](https://ec-jrc.github.io/lisflood-model/3_02_optLISFLOOD_lakes/) and/or of the [reservoirs module](https://ec-jrc.github.io/lisflood-model/3_03_optLISFLOOD_reservoirs/). + [rice calendar](../4_Static-Maps_rice-calendar/): rice calendar for planting and harvesting seasons. These maps are required only when activating the [rice irrigation module](https://ec-jrc.github.io/lisflood-model/2_17_stdLISFLOOD_irrigation/) @@ -39,9 +39,9 @@ The section [Static Maps](../4_Static-Maps-introduction) provides detailed guide + water demand maps: domestic, energetic, livestock, industrial water use. These maps represent the time series of spatially distributed values of water demand for domestic, energetic, livestock, and industrial water use. These maps are required only when activating the [water use module](https://ec-jrc.github.io/lisflood-model/2_18_stdLISFLOOD_water-use/) + outlet points: locations and IDs of the points for which LISFLOOD provides the time series of discharge values. -#### Role of "mask" and "channels" maps +#### Role of "mask", "channels" ans "channelsMCT" maps -The mask map (i.e. "area.map") defines the model domain. In order to avoid unexpected results, **it is vital that all maps that are related to topography, land use and soil are defined** (i.e. don't contain a missing value) for each pixel that is "true" (has a Boolean 1 value) on the mask map. The same applies for all meteorological input and the Leaf Area Index maps. Similarly, all pixels that are "true" on the channels map must have some valid (non-missing) value on each of the channel parameter maps. Undefined pixels can lead to unexpected behaviour of the model, output that is full of missing values, loss of mass balance and possibly even model crashes. Some maps needs to have values in a defined range e.g. the gradient map has to be greater than 0. +The mask map (i.e. "area.map") defines the model domain. In order to avoid unexpected results, **it is vital that all maps that are related to topography, land use and soil are defined** (i.e. don't contain a missing value) for each pixel that is "true" (has a Boolean 1 value) on the mask map. The same applies for all meteorological input and the Leaf Area Index maps. Similarly, all pixels that are "true" on the channels map must have some valid (non-missing) value on each of the channel parameter maps. At the same time, all pixels that have value "true" in the MCT rivers mask must also belong to the "channels" map. Undefined pixels can lead to unexpected behaviour of the model, output that is full of missing values, loss of mass balance and possibly even model crashes. Some maps needs to have values in a defined range e.g. the gradient map has to be greater than 0. #### Geometrical properties of the computational grid cell diff --git a/docs/4_Static-Maps_channel-geometry/index.md b/docs/4_Static-Maps_channel-geometry/index.md index 638e5b0a..f8588a2c 100644 --- a/docs/4_Static-Maps_channel-geometry/index.md +++ b/docs/4_Static-Maps_channel-geometry/index.md @@ -2,6 +2,7 @@ In the LISFLOOD model flow through the channel is simulated using the kinematic wave equations. Channel maps describe the sub grid information of the channel geometry, i.e. the length, slope, width and depth of the main channel inside a grid-cell.
+ The **channel mask** map is the Boolean field with '1' for all grid-cells with channels and NoData for all grid-cells with no channels.
++ The **MCT channel mask** map is the Boolean field with '1' for all river grid-cells using MCT wave routing and '0' for other channel grid cells.
+ The **channel side slope** map (referred as 's' in Figure 41) defines the slope of the channel banks.
+ The **channel length** map is the length of the river in each grid-cell, and the value can exceed grid-size to account for meandering rivers.
+ The **channel gradient** (or channel slope) map is the average gradient of the main river inside a cell.
@@ -23,6 +24,7 @@ Channel characteristics, explained above, are shown in the Figure 41 below.
Type: Boolean | Units: -;
Range: NoData or 1 |Boolean map that identifies the channel grid-cells | +|MCT Channel mask | chanmct.nc;
Type: Boolean | Units: -;
Range: [0-1] |Boolean map that identifies the channel grid-cells using the MCT diffusive river routing | |Side slope |chans.nc;
Type: Float32 | Units: m;
Range>0 |Channel side slope| |Channel length |chanlength.nc;
Type: Float32 | Units: m;
Range>0 |Channel length (value can exceed grid size, to account for meandering rivers)| |Channel gradient |changrad.nc;
Type: Float32 |Units: m/m;
Range: [0-1] |Channel longitudinal gradient| @@ -45,6 +47,9 @@ Channel characteristics, explained above, are shown in the Figure 41 below.
R.: map>0 | Saturated conductivity layer 2 | | **CHANNEL GEOMETRY** | | | | | Channels | chan.map | U.: [-]
R.: 0 or 1 | Map with Boolean 1 for all channel pixels, and Boolean 0 for all other pixels on MaskMap | +| MCT Channels | chanmct.map | U.: [-]
R.: 0 or 1 | Map with Boolean 1 for channel pixels using MCT diffusive wave routing, and Boolean 0 for all other pixels on MaskMap | | ChanGrad | changrad.map | U.: $\frac{m} {m}$
R.: map > 0
!!! | Channel gradient | | ChanMan | chanman.map | U.: $m^{-1/3} s$
R.: map > 0 | Manning's roughness coefficient for channels | | ChanLength | chanleng.map | U.: $m$
R.: map > 0 | Channel length (can exceed grid size, to account for meandering rivers) | diff --git a/docs/4_annex_output-files/index.md b/docs/4_annex_output-files/index.md index 2811aa3d..6843e6e5 100644 --- a/docs/4_annex_output-files/index.md +++ b/docs/4_annex_output-files/index.md @@ -9,7 +9,8 @@ LISFLOOD can generate a wide variety of outputs. Output files can be time series | Description | Units | File name | | ------------------------------------------------------------ | ---------------- | --------------------- | | **RATE VARIABLES AT GAUGES** | | | -| $^{1,2}$ channel discharge | $\frac{m^3} {s}$ | dis.tss | +| $^{1,2}$ average river discharge | $\frac{m^3} {s}$ | dis.tss | +| $^{1,2}$ instantaneous rivers discharge | $\frac{m^3} {s}$ | chanq.tss | | **NUMERICAL CHECKS** | | | | $^2$ cumulative mass balance error | $m^3$ | mbError.tss | | $^2$ cumulative mass balance error, expressed as mm water slice (average over catchment) | $mm$ | mbErrorMm.tss | diff --git a/docs/4_annex_settings_and_options/index.md b/docs/4_annex_settings_and_options/index.md index 378c9bc6..98d7d049 100644 --- a/docs/4_annex_settings_and_options/index.md +++ b/docs/4_annex_settings_and_options/index.md @@ -20,6 +20,7 @@ The Tables below presents a comprehensive list of setting options, inputs, and o | lfoptions | | WATER ABSTRACTION | | useWaterDemandAveYear | | | switch | input | Use "average" year for water demand and loop it over years | | lfoptions | | TRANSMISSION LOSS | | TransLoss | | | switch | input | Activate transmission loss | | lfoptions | | DOUBLE KINEMATIC WAVE | | SplitRouting | | | switch | input | Activate double kinematic wave routing | +| lfoptions | | MCT DIFFUSIVE WAVE | | MCTRouting | | | switch | input | Activate MCT diffusive wave routing | | lfoptions | | WATER ABSTRACTION | | wateruse | | | switch | input | Activate water use computation | | lfoptions | | GROUNDWATER | | groundwaterSmooth | | | switch | input | Activate smoothing for groundwater to correct error by using windowtotal, based on groundwater bodies and catchments | | lfoptions | | WATER ABSTRACTION | | wateruseRegion | | | switch | input | Use water regions in water use module | @@ -127,6 +128,7 @@ The Tables below presents a comprehensive list of setting options, inputs, and o | lfuser | ROUTING | KINEMATIC WAVE | n | CalChanMan | $(PathParams)/params_CalChanMan1 | $(PathParams)/params_CalChanMan1 | value/map | input calib par | It is a multiplier that is applied to the Manning's roughness map of the channel system default: 2.0 $(PathParams)/params_CalChanMan1.nc | | lfuser | SNOW AND FROST | SNOW | Cm | SnowMeltCoef | $(PathParams)/params_SnowMeltCoef | $(PathParams)/params_SnowMeltCoef | value/map | input calib par | Snowmelt coefficient [mm/deg C /day]. It is the degree-day factor that controls the rate of snowmelt default: 4.0 $(PathParams)/params_SnowMeltCoef.nc SRM: 0.45 cm/C/day ( = 4.50 mm/C/day), Kwadijk: 18 mm/C/month (= 0.59 mm/C/day) See also Martinec et al., 1998. | | lfuser | ROUTING | DOUBLE KINEMATIC WAVE | n? | CalChanMan2 | $(PathParams)/params_CalChanMan2 | $(PathParams)/params_CalChanMan2 | value/map | input calib par | PBchange Multiplier applied to Channel Manning's n for second routing line default: 3.0 $(PathParams)/params_CalChanMan2.nc | +| lfuser | ROUTING | MCT DIFFUSIVE WAVE | n? | CalChanMan3 | $(PathParams)/params_CalChanMan3 | $(PathParams)/params_CalChanMan3 | value/map | input calib par | Multiplier [-] applied to Channel Manning's n for MCT diffusive wave routing default: 3.0 $(PathParams)/params_CalChanMan3.nc | | lfuser | CALIBRATION | LAKES | | LakeMultiplier | $(PathParams)/params_LakeMultiplier | $(PathParams)/params_LakeMultiplier | value/map | input calib par | default: 1.0 $(PathParams)/params_LakeMultiplier.nc Multiplier applied to the lake parameter A | | lfuser | CALIBRATION | RESERVOIRS | | adjust_Normal_Flood | $(PathParams)/params_adjust_Normal_Flood | $(PathParams)/params_adjust_Normal_Flood | value/map | input calib par | default: 0.8 $(PathParams)/params_adjust_Normal_Flood.nc adjusting the balance between normal and flood storage big values (= closer to 1.0 = close to flood) results in keeping the outflow longer at rnormq Range 0.01 - 0.99 | | lfuser | CALIBRATION | RESERVOIRS | | ReservoirRnormqMult | $(PathParams)/params_ReservoirRnormqMult | $(PathParams)/params_ReservoirRnormqMult | value/map | input calib par | default: 1.0 $(PathParams)/params_ReservoirRnormqMult.nc Reservoir rnormq (normal outflow) fraction of the value in table rnormq.txt range: 0.5 - 2 | @@ -164,6 +166,8 @@ The Tables below presents a comprehensive list of setting options, inputs, and o | lfuser | INITIAL CONDITIONS | SOIL | | ThetaInit3Value | -9999 | $(PathInit)/thc | value/map | input initial/internal | initial soil moisture content layer 2 -9999: use field capacity values It is the initial moisture content [mm3 mm-3] of the lower soil layer. | | lfuser | INITIAL CONDITIONS | DOUBLE KINEMATIC WAVE | | CrossSection2AreaInitValue | -9999 | $(PathInit)/ch2cr | value/map | input initial/internal | initial channel cross-sectional area [m2] of the water in the river channels for 2nd routing channel -9999: use 0 | | lfuser | INITIAL CONDITIONS | DOUBLE KINEMATIC WAVE | | PrevSideflowInitValue | -9999 | $(PathInit)/chside | value/map | input initial/internal | initial inflow from each pixel to the channel [mm]. A value of -9999 sets the initial amount of sideflow to thye channel to 0 | +| lfuser | INITIAL CONDITIONS | MCT DIFFUSIVE WAVE | | PrevCmMCTInitValue | -9999 | $(PathInit)/prevcm | value/map | input initial/internal | Courant number at previous step for MCT diffusive routing [-]. A value of -9999 sets the initial value to 0 | +| lfuser | INITIAL CONDITIONS | MCT DIFFUSIVE WAVE | | PrevDmMCTInitValue | -9999 | $(PathInit)/prevdm | value/map | input initial/internal | Reynolds number at previous step for MCT diffusive routing [-]. A value of -9999 sets the initial value to 1 | | lfuser | INITIAL CONDITIONS | LAKES | | LakeInitialLevelValue | -9999 | $(PathInit)/lakeh | value/map | input initial/internal | Initial lake level [m] -9999 sets initial value to steady-state level | | lfuser | INITIAL CONDITIONS | KINEMATIC WAVE | | PrevDischarge | -9999 | $(PathInit)/chanq | value/map | input initial/internal | initial discharge from previous run for lakes, reservoirs and transmission loss only needed for lakes reservoirs and transmission loss -9999: use 0 It is the initial discharge from previous run [m3s-1] used for lakes, reservoirs and transmission loss (only needed if option is on for lakes or reservoirs or transmission loss). Note that PrevDischarge is discharge as an average over the time step (a flux) . | | lfuser | INITIAL CONDITION FOREST | INTERCEPTION | | CumIntForestInitValue | 0 | $(PathInit)/cumf | value/map | input initial/internal | cumulative interception forest [mm] | @@ -242,6 +246,8 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfuser | ROUTING | KINEMATIC WAVE | | OFDepRef | 5 | 5 | value | input par | It is a reference flow depth from which the flow velocity of the surface runoff is calculated [mm] Reference depth of overland flow [mm], used to compute overland flow Alpha for kin. wave | | lfuser | ROUTING | KINEMATIC WAVE | | GradMin | 0.001 | 0.001 | value | input par | Minimum slope gradient of the surface (for kin. wave: slope cannot be 0) It is a lower limit for the slope gradient used in the calculation of the surface runoff flow velocity [m m-1] | | lfuser | ROUTING | KINEMATIC WAVE | | ChanGradMin | 0.0001 | 0.0001 | value | input par | Minimum channel gradient (for kin. wave: slope cannot be 0) It is a lower limit for the channel gradient used in the calculation of the channel flow velocity [m m-1] | +| lfuser | ROUTING | MCT DIFFUSIVE WAVE | | ChannelsMCT | $(PathRoot)/maps/chanmct | $(PathRoot)/maps/chanmct | map | input | Boolean map with value 1 at channel pixels where MCT is used, and 0 at all other pixels | +| lfuser | ROUTING | MCT DIFFUSIVE WAVE | | ChanGradMaxMCT | 0.001 | 0.001 | value | input par | Maximum channel gradient for channels using MCT routing [-] (for MCT wave: slope cannot be 0) [m m-1] | | lfuser | ROUTING | DOUBLE KINEMATIC WAVE | | QSplitMult | 2 | 2 | value | input par | PBchange Multiplier applied to average Q to split into a second line of routing | | lfuser | NUMERICS | SOIL | | CourantCrit | 0.4 | 0.4 | value | input par | Minimum value for Courant condition in soil moisture routine. Always less than or equal to 1. Small values result in improved numerical accuracy, at the expense of increased computing time (more sub-steps needed). If reported time series of soil moisture contain large jumps, lowering CourantCrit should fix this | | lfuser | OPTION RESERVOIR | RESERVOIRS | | DtSecReservoirs | 3600 | 3600 | value | input | Sub time step used for reservoir simulation [s]. Within the model, the smallest out of DtSecReservoirs and DtSec is used. | @@ -296,11 +302,14 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfbinding | TRANSMISSION LOSS | TRANSMISSION | | UpAreaTrans | $(UpAreaTrans) | $(UpAreaTrans) | 0 | input | upstream area for transmission loss | | lfbinding | ROUTING | KINEMATIC WAVE | | CalChanMan | $(CalChanMan) | $(CalChanMan) | 0 | input | It is a multiplier that is applied to the Manning's roughness map of the channel system default: 2.0 $(PathParams)/params_CalChanMan1.nc | | lfbinding | ROUTING | DOUBLE KINEMATIC WAVE | | CalChanMan2 | $(CalChanMan2) | $(CalChanMan2) | value/map | input | PBchange Multiplier applied to Channel Manning's n for second routing line default: 3.0 $(PathParams)/params_CalChanMan2.nc | +| lfbinding | ROUTING | MCT DIFFUSIVE WAVE | | CalChanMan3 | $(CalChanMan3) | $(CalChanMan3) | value/map | input | Multiplier [-] applied to Channel Manning's n for MCT routing default: 3.0 $(PathParams)/params_CalChanMan3.nc | | lfbinding | ROUTING | DOUBLE KINEMATIC WAVE | | QSplitMult | $(QSplitMult) | $(QSplitMult) | value | input | PBchange Multiplier applied to average Q to split into a second line of routing | | lfbinding | ROUTING | KINEMATIC WAVE | | beta | $(beta) | $(beta) | 0 | input | It is the routing coefficient in Manning's equation (2/3). kinematic wave parameter: 0.6 is for broad sheet flow | | lfbinding | ROUTING | KINEMATIC WAVE | | OFDepRef | $(OFDepRef) | $(OFDepRef) | 0 | input | It is a reference flow depth from which the flow velocity of the surface runoff is calculated [mm] Reference depth of overland flow [mm], used to compute overland flow Alpha for kin. wave | | lfbinding | ROUTING | KINEMATIC WAVE | | GradMin | $(GradMin) | $(GradMin) | 0 | input | Minimum slope gradient of the surface (for kin. wave: slope cannot be 0) It is a lower limit for the slope gradient used in the calculation of the surface runoff flow velocity [m m-1] | | lfbinding | ROUTING | KINEMATIC WAVE | | ChanGradMin | $(ChanGradMin) | $(ChanGradMin) | 0 | input | Minimum channel gradient (for kin. wave: slope cannot be 0) It is a lower limit for the channel gradient used in the calculation of the channel flow velocity [m m-1] | +| lbinding | ROUTING | MCT DIFFUSIVE WAVE | | ChannelsMCT | $(ChannelsMCT) | $(ChannelsMCT) | map | input | Boolean map with value 1 at channel pixels where MCT is used, and 0 at all other pixels | +| lbinding | ROUTING | MCT DIFFUSIVE WAVE | | ChanGradMaxMCT | $(ChanGradMaxMCT) | $(ChanGradMaxMCT) | map | input | Maximum channel gradient for channels using MCT routing [-] (for MCT wave: slope cannot be 0) | | lfbinding | NUMERICS | SOIL | | CourantCrit | $(CourantCrit) | $(CourantCrit) | value | input | Minimum value for Courant condition in soil moisture routine. Always less than or equal to 1. Small values result in improved numerical accuracy, at the expense of increased computing time (more sub-steps needed). If reported time series of soil moisture contain large jumps, lowering CourantCrit should fix this | | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | GROUNDWATER | | LZAvInflowMap | $(PathMaps)/lzavin.map | $(PathMaps)/lzavin.map | map | input | $(PathInit)/lzavin.map Reported map of average percolation rate from upper to lower groundwater zone (reported for end of simulation) | | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | KINEMATIC WAVE | | AvgDis | $(PathMaps)/avgdis.map | $(PathMaps)/avgdis.map | map | input | $(PathInit)/avgdis.map CHANNEL split routing in two lines Average discharge map [m3/s] | @@ -323,6 +332,8 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | SOIL | | ThetaInit3Value | $(ThetaInit3Value) | $(ThetaInit3Value) | 0 | input | initial soil moisture content layer 2 -9999: use field capacity values | | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | DOUBLE KINEMATIC WAVE | | CrossSection2AreaInitValue | $(CrossSection2AreaInitValue) | $(CrossSection2AreaInitValue) | value/map | input | initial channel crosssection for 2nd routing channel -9999: use 0 | | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | DOUBLE KINEMATIC WAVE | | PrevSideflowInitValue | $(PrevSideflowInitValue) | $(PrevSideflowInitValue) | value/map | input | initial inflow from each pixel to the channel [mm]. A value of -9999 sets the initial amount of sideflow to thye channel to 0 | +| lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | MCT DIFFUSIVE WAVE | | PrevCmMCTInitValue | $(PrevCmMCTInitValue) | $(PrevCmMCTInitValue) | value/map | input initial/internal | Courant number at previous step for MCT diffusive routing [-]. A value of -9999 sets the initial value to 0 | +| lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | MCT DIFFUSIVE WAVE | | PrevDmMCTInitValue | $(PrevDmMCTInitValue) | $(PrevDmMCTInitValue) | value/map | input initial/internal | Reynolds number at previous step for MCT diffusive routing [-]. A value of -9999 sets the initial value to 1 | | lfbinding | INITIAL CONDITIONS WATER BALANCE MODEL | KINEMATIC WAVE | | PrevDischarge | $(PrevDischarge) | $(PrevDischarge) | 0 | input | initial discharge from previous run for lakes, reservoirs and transmission loss only needed for lakes reservoirs and transmission loss -9999: use 0 | | lfbinding | INITIAL CONDITION FOREST | INTERCEPTION | | CumIntForestInitValue | $(CumIntForestInitValue) | $(CumIntForestInitValue) | 0 | input | cumulative interception forest [mm] | | lfbinding | INITIAL CONDITION FOREST | GROUNDWATER | | UZForestInitValue | $(UZForestInitValue) | $(UZForestInitValue) | 0 | input | Initial water storage water in upper groundwater zone for forest [mm] | @@ -406,6 +417,8 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | DOUBLE KINEMATIC WAVE | | CrossSection2State | $(PathOut)/ch2cr | $(PathOut)/ch2cr | map | output/state | Cross section area for split routing [m2] | | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | DOUBLE KINEMATIC WAVE | | ChSideState | $(PathOut)/chside | $(PathOut)/chside | map | output/state | Reported sideflow to channel for first line of routing [m3/s] | | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | ROUTING | | ChanQState | $(PathOut)/chanq | $(PathOut)/chanq | map | output/state | Reported istantaneous discharge at end of computation step [cu m/s] ChanQ | +| lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | ROUTING | | PrevCmMCTState | $(PathOut)/prevcm | $(PathOut)/prevcm | map | output/state | Reported Courant number at previous step for MCT routing | +| lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | ROUTING | | PrevDmMCTState | $(PathOut)/prevdm | $(PathOut)/prevdm | map | output/state | Reported Reynolds number at previous step for MCT routing | | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | SOIL | | DSLRForestState | $(PathOut)/dslf | $(PathOut)/dslf | map | output/state | Reported days since last rain for forest | | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | INTERCEPTION | | CumInterceptionForestState | $(PathOut)/cumf | $(PathOut)/cumf | map | output/state | Reported interception storage for forest | | lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | SOIL | | Theta1ForestState | $(PathOut)/thfa | $(PathOut)/thfa | map | output/state | theta for soil layer 1a forest fraction | @@ -441,7 +454,10 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfbinding | REPORTED OUTPUT MAPS (END) | DOUBLE KINEMATIC WAVE | | CrossSection2End | $(PathOut)/ch2cr.end | $(PathOut)/ch2cr.end | map | output/end | Cross section area for split routing [m2] | | lfbinding | REPORTED OUTPUT MAPS (END) | DOUBLE KINEMATIC WAVE | | ChSideEnd | $(PathOut)/chside.end | $(PathOut)/chside.end | map | output/end | Reported channel side flow | | lfbinding | REPORTED OUTPUT MAPS (END) | ROUTING | | ChanQEnd | $(PathOut)/chanq.end | $(PathOut)/chanq.end | map | output/end | Reported istantaneous discharge at end of computation step [cu m/s] ChanQ | -| lfbinding | REPORTED OUTPUT MAPS (END) | KINEMATIC WAVE | | DischargeEnd | $(PathOut)/dis.end | $(PathOut)/dis.end | map | output/end | Reported discharge [m3/s] for lakes and reservoirs | +| lfbinding | REPORTED OUTPUT MAPS (END) | KINEMATIC WAVE | | DischargeEnd | $(PathOut)/dis.end | $(PathOut)/dis.end | map | output/end | Reported average discharge [m3/s] for lakes and reservoirs | +| lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | ROUTING | | PrevCmMCTEnd | $(PathOut)/prevcm.end | $(PathOut)/prevcm.end | map | output/end | Reported Courant number at previous step for MCT routing | +| lfbinding | REPORTED OUTPUT MAPS (STATE VARIABLES AT SELECTED TIME STEPS) | ROUTING | | PrevDmMCTEnd | $(PathOut)/prevdm.end | $(PathOut)/prevdm.end +| Reported Reynolds number at previous step for MCT routing | | lfbinding | REPORTED OUTPUT MAPS (END) | SOIL | | DSLRForestEnd | $(PathOut)/dslf.end | $(PathOut)/dslf.end | map | output/end | Reported days since last rain for forest | | lfbinding | REPORTED OUTPUT MAPS (END) | INTERCEPTION | | CumInterceptionForestEnd | $(PathOut)/cumf.end | $(PathOut)/cumf.end | map | output/end | Reported interception storage for forest | | lfbinding | REPORTED OUTPUT MAPS (END) | SOIL | | Theta1ForestEnd | $(PathOut)/thfa.end | $(PathOut)/thfa.end | map | output/end | Reported volumetric soil moisture content for soil layer 1a for forest [V/V] | @@ -490,6 +506,7 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | lfoptions | | | | useWaterDemandAveYear | 0 | WATER ABSTRACTION | switch | input | 0 | | | | Use "average" year for water demand and loop it over years | | lfoptions | | | | TransLoss | 0 | TRANSMISSION LOSS | switch | input | 0 | | | | Activate transmission loss | | lfoptions | | | | SplitRouting | 0 | KINEMATIC WAVE | switch | input | 0 | | | | Activate double kinematic wave routing | +| lfoptions | | | | MCTRouting | 0 | MCT DIFFUSIVE WAVE| switch | input | 0 | | | | Activate MCT diffusive wave routing | | lfoptions | | | | wateruse | 0 | WATER ABSTRACTION | switch | input | 0 | | | | Activate water use computation | | lfoptions | | | | groundwaterSmooth | 0 | GROUNDWATER | switch | input | 0 | | | | Activate smoothing for groundwater to correct error by using windowtotal, based on groundwater bodies and catchments | | lfoptions | | | | wateruseRegion | 0 | WATER ABSTRACTION | switch | input | 0 | | | | Use water regions in water use module | @@ -582,7 +599,7 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | key | outputVar | where | repoption | restrictoption | operation | Description | | -------------------- | ------------------------------------------------------------ | -------------- | ---------------------- | --------------------------- | --------------- | ------------------------------------------------------------ | -| DisTS | ChanQAvg | Gauges | repDischargeTs | | | Reported discharge at gauges [m3/s] | +| DisTS | ChanQAvg | Gauges | repDischargeTs | | | Reported average discharge at gauges [m3/s] | | WaterLevelTS | WaterLevel | Gauges | repWaterLevelTs | nonInit,simulateWaterLevels | | Reported water level [m] | | StepsSoilTS | NoSubSteps | 1 | repInternalCom | | mapmaximum | Number of sub-steps needed for soil moisture routine | | StepsWaterUseTS | NoWaterUseExe | 1 | repInternalCom | nonInit,wateruse | | number of loops needed for water use routine | @@ -708,6 +725,8 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | CumIntSealedState | CumInterSealed | mm | repStateMaps | | | | nonInit | Reported cumulative depressions storage [mm] | | DischargeMaps | ChanQAvg | m3/s | repStateMaps | | | | nonInit | Reported discharge [cu m/s] (average over the timesteps) | | ChanQState | ChanQ | m3/s | repStateMaps | | | | nonInit | Reported istantaneous discarge at end of time step | +| PrevCmMCTState | PrevCm0 | - | repStateMaps | | | | nonInit | Reported Courant number at previous step for MCT routing | +| PrevDmMCTState | PrevDm0 | - | repStateMaps | | | | nonInit | Reported Reynolds number at previous step for MCT routing | | LakeLevelState | LakeLevel | m | repStateMaps | | | | nonInit,simulateLakes | Output map(s) with lake level [m] | | ReservoirFillState | ReservoirFill | - | repStateMaps | | | | nonInit,simulateReservoirs | Output map(s) with Reservoir Filling [-] | | CrossSection2State | CrossSection2Area | m | repStateMaps | | | | nonInit,SplitRouting | Cross section area for split routing [m2] | @@ -744,6 +763,8 @@ param| lfuser | IRRIGATION AND WATER ABSTRACTION | CumIntSealedEnd | CumInterSealed | mm | | | repEndMaps | | nonInit | Reported cumulative depressions storage [mm] | | DischargeEnd | ChanQAvg | m3/s | | | repEndMaps | | nonInit | Reported discharge [cu m/s] (average over the timesteps) | | ChanQEnd | ChanQ | m3/s | | | repEndMaps | | nonInit | Reported istantaneous discarge at end of time step | +| PrevCmMCTEnd | PrevCm0 | - | | | repEndMaps | | nonInit | Reported Courant number at previous step for MCT routing | +| PrevDmMCTEnd | PrevDm0 | - | | | repEndMaps | | nonInit | Reported Reynolds number at previous step for MCT routing | | LakeLevelEnd | LakeLevel | m | | | repEndMaps | | nonInit,simulateLakes | Reported lake level | | ReservoirFillEnd | ReservoirFill | m | | | repEndMaps | | nonInit,simulateReservoirs | Reported reservoir filling | | CrossSection2End | CrossSection2Area | m | | | repEndMaps | | nonInit,SplitRouting | Cross section area for split routing [m2] | diff --git a/docs/4_annex_tests/index.md b/docs/4_annex_tests/index.md index 04343343..a0aaed0d 100644 --- a/docs/4_annex_tests/index.md +++ b/docs/4_annex_tests/index.md @@ -785,6 +785,27 @@ Verifies chunking files using NetCDFTimeChunks with values `1`, `10`, `auto` and | test_chunking_24h | 86400 |30/07/2016 06:00 - 01/09/2016 06:00 | compares output chunking files with reference files | | test_chunking_6h | 21600 |30/07/2016 06:00 - 01/09/2016 06:00 | compares output chunking files with reference files | + +### Testing MCT diffusive wave routing + +A set of tests is available to verify the correct functioning of the MCT diffusive wave routing. In these tests all OSLisflood options are switched off and the model runs with core components and river routing. Two sets of tests are available: 1) 'fast' tests that can be run routinely and only take a few minutes; 2) 'slow' tests that need to run before merging new model developments. + +#### Testing warm start for MCT diffusive routing + +Test ensures that a long cold run is equivalent to an initial cold start + repeated warm starts, when MCT diffusive wave routing is used. The test runs OSLisflood continuously for a long period of time and saves all outputs in a reference folder. It then runs OSLisflood on the same period but restarting the model at every step (start and stop). Outputs of the two runs are compared and maps are expected to be identical. +During this test, both 'slow' and 'fast' tests generate the reference dataset dynamically and are designed to work when model developments change the model outputs. + +#### Testing inflow for MCT diffusive routing + +This test verifies the correct functioning of the option inflow, when using MCT diffusive routing. The test runs OSLisflood continuously for a long period of time and saves river discharge time series for a point along the main river (point A) and the point immediatly downstream (point B). It then runs OSLisflood again on the sub-catchment downstream of point B and using the generated river discharge at point A as an inflow at point B. Discharge time series from the two runs at point B are compared, differences should be <0.001 m3/s. +During this test, both 'slow' and 'fast' tests generate the reference dataset dynamically and are designed to work when model developments change the model outputs. + +#### Testing results for MCT diffusive routing + +These tests perform short and long (max 1 year) execution of OSlisflood on the Po test catchments clipped from the full setup (EFAS) and assert that results are within defined tolerances if compared with test oracle. All tests have all switches turned off and run with core OSLisflood components and river routing. Note that the tests will fail if model development changes outputs from any of the core model componets. + + + ## Release test for EFAS and GloFAS At each release, in addition to pass all tests described above, OSLisflood is tested also with full domains of EFAS and GLOFAS.