### LISFLOOD Settings Template Example

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

An example of a complete LISFLOOD settings file, serving as a template for users to update paths, map names, and table names. It includes settings for a warm start run.

```XML
<?xml version="1.0" encoding="UTF-8"?>
<lisflood>
    <lfuser>
        <!-- User-specific settings go here -->
        <!-- Example: Specify project directory -->
        <ProjectDir>$(ProjectDir)</ProjectDir>
        
        <!-- Example: Time-related specifications -->
        <StartTime>2023-01-01T00:00:00</StartTime>
        <EndTime>2023-01-31T23:59:59</EndTime>
        
        <!-- Example: Parameter options -->
        <MaxIterations>100</MaxIterations>
        
        <!-- Example: Optional model routines -->
        <UseSnowModule>false</UseSnowModule>
        <UseEvapModule>true</UseEvapModule>
        
        <!-- Paths to input maps and tables -->
        <InputMapsDir>maps/</InputMapsDir>
        <InputTablesDir>tables/</InputTablesDir>
        
        <!-- Output directory -->
        <OutputDir>output/</OutputDir>
    </lfuser>
</lisflood>
```

--------------------------------

### Install LISFLOOD Dependencies from Source

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Sets up a conda environment named 'lisflood', installs pcraster, navigates into the cloned repository, and installs project dependencies using pip.

```bash
conda create --name lisflood python=3.7 -c conda-forge
conda activate lisflood
conda install -c conda-forge pcraster
cd lisflood-code
pip install -r requirements.txt
```

--------------------------------

### Clone LISFLOOD Repository

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Clones the master branch of the LISFLOOD code repository from GitHub using Git.

```bash
git clone --single-branch --branch master https://github.com/ec-jrc/lisflood-code.git
```

--------------------------------

### Run LISFLOOD Simulation from Source

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Executes a LISFLOOD simulation using the Python script 'lisf1.py' from the source code, pointing to a specific settings file for a test catchment.

```python
python src/lisf1.py tests/data/<TestCatchmentFolder>/settings/cold.xml
```

--------------------------------

### Run LISFLOOD Unit Tests

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Executes the unit tests for the LISFLOOD model using the pytest framework. Requires pytest, pytest-cov, pytest-mock, and gdal to be installed.

```bash
pytest tests/
```

--------------------------------

### Starting the InstantSearch Instance

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/_includes/search/algolia-search-scripts.html

Initiates the search process by calling the start() method on the InstantSearch instance. This begins the search queries based on the configured widgets and parameters.

```javascript
search.start();
```

--------------------------------

### LISFlood Warm Start Implementation Example

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/4_annex_tests/index.md

Illustrates the Python code used to set up LISFlood simulation options for a warm start test. It shows how to configure parameters like time step (DtSec), output path, and simulation start/end times.

```python
settings_prerun = self.setoptions(self.settings_files['prerun'], opts_to_unset=modules_to_unset,
                                  vars_to_set={'DtSec': dt_sec,
                                               'PathOut': path_out_init,
                                               'StepStart': step_start,
                                               'StepEnd': step_end})

```

--------------------------------

### Run LISFLOOD with Docker (Test Catchment)

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Runs LISFLOOD using a Docker container, mapping a local directory to the container's input volume and specifying the settings file for a test catchment.

```bash
docker run -v /absolute_path/to/my/local/folder/LF_ETRS89_UseCase:/input jrce1/lisflood /input/settings/cold.xml
```

--------------------------------

### Running LISFLOOD from Command Line

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step5_model-initialisation/index.md

Executes the LISFLOOD model by specifying the settings file to be used. This command is executed from a command prompt or console window.

```unix
lisflood settings.xml
```

--------------------------------

### Copy Test Catchment Files with Docker

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Copies test catchment files from the LISFLOOD Docker image to a local directory using mapped volumes.

```bash
docker run -v /absolute_path/to/my/local/folder:/usecases jrce1/lisflood:latest usecases
```

--------------------------------

### LISFLOOD Settings File Reference

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

Provides a reference to a complete example settings file for LISFLOOD, encouraging users to update paths, map names, and table references.

```APIDOC
Reference settings file:
  URL: https://github.com/ec-jrc/lisflood-code/tree/master/src/lisfloodSettings_reference.xml
  Description: A comprehensive example settings file to guide users in preparing their own configuration. Users should update paths, map names, and table references within this template.
```

--------------------------------

### LISFLOOD ReportSteps Configuration Example

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

Illustrates how to configure the 'ReportSteps' parameter to specify at which time steps model state maps should be written. This example shows setting it to specific time steps (10, 20, and 40) using a comma-separated list.

```xml
<textvar name="ReportSteps" value="10,20,40" />
```

--------------------------------

### LISFLOOD Simulation Settings

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/4_annex_settings_and_options/index.md

Controls for LISFLOOD simulation setup and execution, including EnKF activation and initialization procedures.

```APIDOC
Activate EnKF simulation:
  switch: input
  description: Activate EnKF simulation

Run LISFLOOD initialization run:
  switch: input
  description: Run LISFLOOD initialization run

Run LISFLOOD initialization run to compute Lzavin.map and skip completely the routing component:
  switch: input
  description: Run LISFLOOD initialization run to compute Lzavin.map and skip completely the routing component
```

--------------------------------

### Install Requirements from File

Source: https://github.com/ec-jrc/lisflood-code/blob/master/README.md

Installs all project dependencies listed in the 'requirements.txt' file into the active Conda environment. This is typically done after cloning the repository.

```bash
cd lisflood-code
pip install -r requirements.txt
```

--------------------------------

### Install LISFLOOD Model Package

Source: https://github.com/ec-jrc/lisflood-code/blob/master/README.md

Installs the 'lisflood-model' package from PyPI. This command also makes the 'lisflood' executable available in the current environment.

```bash
pip install lisflood-model
```

--------------------------------

### LISFLOOD Initialization Parameters Description

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

Provides descriptions for LISFLOOD initialization parameters, including units and special value interpretations. These parameters set the starting state for hydrological processes.

```text
- WaterDepthInitValue: initial amount of water on the soil surface [mm]

- SnowCoverInitAValue: initial snow cover on the soil surface in elevation zone A [mm]

- SnowCoverInitBValue: initial snow cover on the soil surface in elevation zone B [mm]

- SnowCoverInitCValue: initial snow cover on the soil surface in elevation zone C [mm]

- FrostIndexInitValue: initial value of the frost index [°C/day]

- CumIntInitValue: initial interception storage [mm]

- UZInitValue: initial storage in the upper groundwater zone [mm]

- DSLRInitValue: initial number of days since the last rainfall event [days]

- CumIntSealedInitValue: initial value of the depression storage for the sealed part of a pixel [mm]

- LZInitValue: initial storage in the lower groundwater zone [mm]. Setting InitLisflood to 1 activates a 'steady state' storage calculation.

- TotalCrossSectionAreaInitValue: initial cross-sectional area [m^2] of water in river channels. -9999 sets initial water to half bankfull.

- ThetaInit1Value: initial moisture content [mm^3/mm^3] of the superficial soil layer (1a). -9999 sets initial soil moisture to field capacity.

- ThetaInit2Value: initial moisture content [mm^3/mm^3] of the upper soil layer (1b). -9999 sets initial soil moisture to field capacity.

- ThetaInit3Value: initial moisture content [mm^3/mm^3] of the lower soil layer (2). -9999 sets initial soil moisture to field capacity.

- PrevDischarge: initial discharge from previous run [m^3/s] for lakes, reservoirs and transmission loss. -9999 sets initial discharge to half bankfull.
```

--------------------------------

### Run LISFLOOD Executable

Source: https://github.com/ec-jrc/lisflood-code/blob/master/README.md

Executes the LISFLOOD model from the command line using the installed package. Requires the absolute path to a settings XML file.

```bash
lisflood /absolute_path/to/my/local/folder/LF_ETRS89_UseCase/settings/cold.xml
```

--------------------------------

### LISFLOOD Configuration Example

Source: https://github.com/ec-jrc/lisflood-code/blob/master/tests/data/LF_ETRS89_UseCase/maps/tables/rminq.txt

This snippet demonstrates a potential Python configuration for LISFLOOD, likely setting up parameters or input files. It includes basic variable assignments and comments.

```python
# LISFLOOD Configuration Example

# Define input data paths
input_dem = "/path/to/dem.tif"
input_landuse = "/path/to/landuse.tif"
output_directory = "/path/to/output/"

# Simulation parameters
start_date = "2023-01-01"
end_date = "2023-12-31"

# Model specific settings
resolution = 100  # meters

# Example of a function call (hypothetical)
def run_lisflood_simulation(dem, landuse, output_dir, start, end, res):
    print(f"Running LISFLOOD simulation from {start} to {end}")
    print(f"Using DEM: {dem}, Landuse: {landuse}")
    print(f"Outputting to: {output_dir} at {res}m resolution")
    # ... simulation logic ...
    return True

# Execute the simulation
if __name__ == "__main__":
    success = run_lisflood_simulation(input_dem, input_landuse, output_directory, start_date, end_date, resolution)
    if success:
        print("Simulation completed successfully.")
    else:
        print("Simulation failed.")

```

--------------------------------

### Run LISFLOOD from Conda Environment

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Executes the LISFLOOD model using the 'lisflood' executable installed within an activated conda environment, specifying the path to the settings file.

```bash
lisflood /absolute_path/to/my/local/folder/<TestCatchmentFolder>/settings/cold_day_base.xml
```

--------------------------------

### Create and Activate Conda Environment for LISFLOOD

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Creates a new conda environment named 'lisflood' with Python 3.7 and installs necessary dependencies like pcraster and the lisflood-model package.

```bash
conda create --name lisflood python=3.7 -c conda-forge
conda activate lisflood
conda install -c conda-forge pcraster
pip install lisflood-model
```

--------------------------------

### Pull Docker Image

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step2_installation/index.md

Pulls the latest LISFLOOD Docker image from the Docker Hub repository.

```bash
docker pull jrce1/lisflood
```

--------------------------------

### LISFLOOD Settings for Split Routing Initialization

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step5_model-initialisation/index.md

Configures LISFLOOD settings in Settings.XML for split routing initialization. This includes setting initial states, activating initialization options, enabling reporting maps, and specifying output file names for average percolation and discharge.

```xml
<setoption choice="1" name="InitLisfloodwithoutsplit"/>
<setoption choice="1" name="InitLisflood"/>
<setoption choice="1" name="repEndMaps"/>
<setoption choice="1" name="writeNetcdf"/>
<setoption choice="1" name="SplitRouting"/>
<textvar name="LZAvInflowMap" value="$(PathOut)/lzavin">
<textvar name="AvgDis" value="$(PathOut)/avgdis">
```

--------------------------------

### LISFLOOD Initialization Settings (Kinematic Routing)

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step5_model-initialisation/index.md

Configures LISFLOOD for initialization using kinematic routing without split routing. This involves setting initial states, activating specific initialization options, enabling reporting maps, and specifying the average percolation rate map.

```xml
<setoption choice="1" name="InitLisflood"/>
<setoption choice="1" name="InitLisfloodwithoutsplit"/>
```

```xml
<setoption choice="1" name="repEndMaps"/>
<setoption choice="1"  name="writeNetcdf"/>
```

```xml
<setoption choice="0" name="SplitRouting"/>
```

```xml
<textvar name="LZAvInflowMap" value="$(PathOut)/lzavin">

```

```xml
<setoption choice="0" name="InitLisfloodwithoutsplit"/>
<setoption choice="0" name="InitLisflood"/>
```

--------------------------------

### LISFLOOD Configuration for Initial Conditions

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step5_model-initialisation/index.md

Defines initial conditions for the water balance model, specifying the paths for reported maps of average percolation rate and average discharge. These maps are expected to be in NetCDF format.

```xml
<textvar name="LZAvInflowMap" value="$(PathInit)/lzavin">
<comment>
$(PathInit)/lzavin.map
Reported map of average percolation rate from upper to
lower groundwater zone (reported for end of simulation)
</comment>
</textvar>

<textvar name="AvgDis" value="$(PathInit)/avgdis">
<comment>
$(PathInit)/avgdis.map
CHANNEL split routing in two lines
Average discharge map [m3/s]
</comment>
</textvar>
```

--------------------------------

### Install LISFLOOD Package

Source: https://github.com/ec-jrc/lisflood-code/blob/master/README.md

Installs the LISFLOOD Python package using pip. This command also makes the `lisflood` executable available in the virtual environment.

```bash
pip install lisflood-model
```

--------------------------------

### Install Dependencies with Conda

Source: https://github.com/ec-jrc/lisflood-code/blob/master/README.md

Installs Python 3.7 and essential scientific packages (pcraster, gdal) into a new Conda environment named 'lisflood'. This is a prerequisite for running the LISFLOOD model.

```bash
conda create --name lisflood python=3.7 -c conda-forge
conda activate lisflood
conda install -c conda-forge pcraster gdal
```

--------------------------------

### InstantSearch.js Initialization with Algolia

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/_includes/search/algolia-search-scripts.html

Initializes InstantSearch.js with Algolia credentials and search parameters. This includes setting the application ID, API key, index name, and restricting searchable attributes.

```javascript
const search = instantsearch({
  appId: '{{ site.algolia.application_id }}',
  apiKey: '{{ site.algolia.search_only_api_key }}',
  indexName: '{{ site.algolia.index_name }}',
  searchParameters: {
    restrictSearchableAttributes: [
      'title',
      'content'
    ]
  }
});
```

--------------------------------

### LISFLOOD Execute: Initial Cold Run

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/4_annex_tests/index.md

Sets up and executes an initial cold start for the LISFLOOD simulation. This involves configuring simulation parameters like start and end times, input file paths, and output directories.

```python
settings_coldstart = self.setoptions(self.settings_files['cold'], 
                                     opts_to_unset=modules_to_unset,
                                     vars_to_set={'StepStart': step_start,
                                                  'StepEnd': step_start,
                                                  'LZAvInflowMap': lzavin_path,
                                                  'PathOut': path_out,
                                                  'AvgDis': avgdis_path,
                                                  'DtSec': dt_sec})
# ** execute
lisfloodexe(settings_coldstart)
```

--------------------------------

### LISFLOOD Options Configuration

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

Demonstrates how to configure LISFLOOD model options using the 'lfoptions' and 'setoption' elements within the settings file. Options are typically binary switches (1 for on, 0 for off) and may require additional configuration in the settings file.

```xml
<lfoptions>
<setoption choice="1" name="inflow" />
</lfoptions>
```

--------------------------------

### Groundwater Parameter Descriptions

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/3_step3_preparing-setting-file/index.md

Provides a textual explanation of the groundwater parameters used in LISFLOOD, including their units and typical usage recommendations.

```text
UpperZoneTimeConstant ($T_{uz}$): Time constant for the upper groundwater zone [days]
LowerZoneTimeConstant ($T_{lz}$): Time constant for the lower groundwater zone [days]
GwPercValue ($GW_{perc}$): Maximum rate of percolation from upper to lower groundwater zone [mm/day]
GwLoss ($f_{loss}$): Maximum rate of percolation from the lower groundwater zone (groundwater loss) [mm/day]. A value of 0 (closed lower boundary) is recommended.
```

--------------------------------

### LISFLOOD Execute: Subsequent Warm Runs

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/4_annex_tests/index.md

Executes subsequent warm start simulations for LISFLOOD, using the output from the previous run as initial conditions. This loop iterates through simulation days, updating start and end times and specifying the path for initial conditions.

```python
# warm run (2. single step warm start/stop with initial conditions from previous run)
prev_settings = settings_coldstart
warm_step_start = prev_settings.step_end_dt + timedelta(seconds=dt_sec)
warm_step_end = warm_step_start
timestep_init = prev_settings.step_end_dt.strftime('%d/%m/%Y %H:%M')
maskinfo = MaskInfo.instance()
nc_comparator = NetCDFComparator(maskinfo.info.mask)
tss_comparator = TSSComparator(array_equal=True)
while warm_step_start <= step_end_dt:
    path_init = prev_settings.output_dir

    settings_warmstart = self.setoptions(
                            self.settings_files['warm'], 
                            opts_to_unset=modules_to_unset,
                            vars_to_set={
                                'StepStart': warm_step_start.strftime('%d/%m/%Y %H:%M'),
                                'StepEnd': warm_step_end.strftime('%d/%m/%Y %H:%M'),
                                'LZAvInflowMap': lzavin_path,
                                'PathOut': path_out,
                                'PathInit': path_init,
                                'timestepInit': timestep_init,
                                'AvgDis': avgdis_path,
                                'ReportSteps': report_steps,
                                'DtSec': dt_sec}
                        )
    # ** execute
    lisfloodexe(settings_warmstart)
```

--------------------------------

### LISFlood Warm Start Tests

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/4_annex_tests/index.md

Tests designed to verify the equivalence between a long cold run and a series of warm starts. These tests ensure that restarting the simulation at intermediate steps produces consistent results compared to a continuous run. Both daily and 6-hour time steps are considered.

```python
import unittest

class TestWarmStart(unittest.TestCase):

    def test_warmstart_daily(self):
        # Test case for daily warm start
        # Expected: nc diffs are within tolerances, TSSs identical
        pass

    def test_warmstart_6h(self):
        # Test case for 6-hour warm start
        # Expected: nc diffs are within tolerances, TSSs identical
        pass

```

--------------------------------

### Excerpt Handling

Source: https://github.com/ec-jrc/lisflood-code/blob/master/docs/_includes/seo.html

Appends the page excerpt to the metadata if it exists, providing a brief summary for search engines and social previews.

```Liquid
{% if page.excerpt %}
  {%- comment -%}
    Excerpt processing logic here
  {%- endcomment -%}
{%- endif -%}
```