LISFLOOD Hydrological Model

The LISFLOOD settings are configured via an XML file. The configuration is organized into several key sections that define how the model behaves, what variables the user must provide, and what the model produces.

Key configuration sections include:

• lfoptions: Switches used to activate optional modules and specify optional output formats (such as time series or specific map formats).
• lfuser: Variables that are typically defined by the user to control model execution.
• lfbinding: The core model variables used during simulation.
• initial variables: The specific values or maps required to initialize the model, distinguishing between requirements for 'cold start' and 'warm start' during both the prerun and run phases.

The Manning's roughness coefficient for channels can be derived empirically using the grid-cell elevation and its upstream area.

Formula: chanman = 0.025 + 0.015 * min(50 / upstreamArea, 1) + 0.030 * min(elevation / 2000, 1)

By default, LISFLOOD generates .tss (Time Series) output files with a header containing the number of values, value type, settings file path, and creation date.

To produce .tss files that start immediately with the time series data (no header), use the -h or --noheader flag.

LISFLOOD follows an "end of timestep" naming convention for both input (forcings) and output data.

Every timestamp or time step refers to the END of the time interval. For example, a daily accumulated rainfall timestamp of 02/01/2017 06:00 represents the accumulation that occurred between 01/01/2017 06:00 and 02/01/2017 06:00. Similarly, an output timestamp of 02/01/2017 06:00 represents the average discharge over that same period.

LISFLOOD generates two primary types of output files:

1. Time Series: Stored as .tss files, representing data at specific points.
2. Maps: Stored in NetCDF format.

Note that some output files are specific to optional modules (e.g., reservoir simulation). While users can change the file names in the settings, it is generally not recommended.

LISFLOOD settings are configured using XML files. The configuration is primarily organized into two sections within the OS LISFLOOD settings XML:

1. lfoptions: Contains the core model setting options.
2. lfuser: Contains user-defined settings and inputs.

Refer to the specific tables in the documentation to find the exact keys and values required for your simulation setup.

The repository includes black-box tests in the tests/ directory that execute the development version of LISFLOOD using predefined XML settings. These tests compare the model output against a reference dataset (test oracle).

Key characteristics:

• Scope: Uses a test catchment (Po basin) clipped from the EFAS domain with specific Meteo netCDF forcings.
• Sensitivity: These tests will fail if the hydrological model logic changes between the reference version and the version currently under test.
• Activated Modules: Most result tests run with the following modules enabled:
  • SplitRouting
  • simulateReservoirs
  • groundwaterSmooth
  • drainedIrrigation
  • openwaterevapo
  • riceIrrigation
  • indicator

LISFLOOD uses three distinct soil depth layers. The depth values are constrained as follows:

1. Layer 1 (Superficial layer): Assumed constant at 50 mm globally.
2. Layer 2 (Upper layer): Must be ≥ 50 mm. If the calculated value is lower than 50 mm, it is set to 50 mm to account for data uncertainty.
3. Layer 3 (Lower layer): Calculated as the remaining depth after layers 1 and 2 are subtracted from the absolute depth to bedrock.

Total soil depth is determined by the minimum of the 'absolute depth to bedrock' and the 'groundwater table depth'.

LISFLOOD uses the Van Genuchten equation to describe the relationship between soil moisture, suction pressure (water retention curve), and hydraulic conductivity. To implement this, the model requires five specific soil hydraulic parameters.

Note that LISFLOOD differentiates water dynamics based on land cover for the topsoil (the first two layers: surface and middle). For these layers, parameters are assigned separately for forested areas and non-forested (others) areas. The third layer (bottom layer) does not differentiate by land cover type.

The settings.xml file is the primary configuration interface for OS LISFLOOD. It uses a specific XML structure composed of three main functional elements wrapped in a root <lfsettings> tag.

Each element serves a distinct purpose in how parameters and files are linked to the model:

1. <lfoptions>: Controls model switches (on/off).
2. <lfuser>: Defines user-specific variables and paths for easy modification.
3. <lfbinding>: Contains the actual model parameter values and file bindings used by the core code.

<lfsettings>
  <lfoptions>
    <!-- LISFLOOD options (switches) -->
  </lfoptions>
  <lfuser>
    <!-- User's specific parameters and settings -->
  </lfuser>
  <lfbinding>
    <!-- LISFLOOD model general settings -->
  </lfbinding>
</lfsettings>