Update existing Sfincs model with boundary conditions and forcing

This notebook demonstrates how to update an existing SFINCS model with gauges, boundary conditions and forcing such as precipitation. The notebook does not contain the SFINCS code or executables to run the model with.

We will perform the following: * append an existing schematization that only contains static schematization layers * introduce gridded precipitation only * introduce gridded precipitation, water level boundaries and observation gauge point locations * write the new models to new model folders

This notebook demonstrates the update functionalities on a test model delivered with the hydromt_sfincs plugin.

First let us check if HydroMT has the Sfincs plugin available. The result of the code block below should be hydroMT model plugins: sfincs (vx.x.x) where x.x.x denotes the current version (e.g. 0.1.0). If Sfincs seems missing, ensure it is installed by typing pip install hydromt_sfincs on a command line.

[1]:
!hydromt --models
hydroMT model plugins: sfincs (v0.2.2.dev0)

Add precipitation forcing to an existing model

Rather than rebuilding a model from scratch, we can add or update components to an existing model. You may want to update several things at the same time. This may be useful, for instance when you are considering model intercomparisons, with different parameter sets or underlying static maps, or comparing the impact of different forcing datasets.

This is possible by preparing a configuration file that includes every components and settings that you want to do during your update.

The ini-file contains the model setup configuration and determines which components are updated and in which sequence and sets optional arguments for each component. This configuration is passed to hydromt using -i <path_to_ini_file>.

Each header as shown between [...] (e.g. [setup_p_forcing_from_grid]) corresponds with a model component which are explained in the docs(model_components).

Let’s open the example configuration file sfincs_update_precip.ini from the model repository [examples folder] and have a look at the settings.

[2]:
fn_ini = "sfincs_update_precip.ini"
with open(fn_ini, "r") as f:
    txt = f.read()
print(txt)
[setup_config]
tref = 20100201 000000
tstart = 20100201 000000
tstop = 20100210 000000

[setup_p_forcing_from_grid]
precip_fn = era5_hourly         # gridded precipitation data ['precip']
dst_res = None                  # output resolution (m)
aggregate = False               # if True return the aggregated mean as spatially uniform precip

Two components are to be updated: * [setup_config]: This section directly overwrites parts of the .inp configuration file. You can extend this with any settings of the .inp file. The time settings need to be altered. We have made sure that the time coverage is available in the precipitation sample dataset. * [setup_p_forcing_from_grid]: Here, we identify which dataset, available in our data catalog is to be used as forcing. The dataset era5_hourly has to be represented in the data_catalog.yml. Please check your $USER_HOME/.hydromt_data folder to see if it is indeed present. If it is, then you can continue below to add the forcing.

We need the update command of hydromt to update the model with this .ini file. Let’s get an overview of the options.

[3]:
!hydromt update --help
Usage: hydromt update [OPTIONS] MODEL MODEL_ROOT

  Update a specific component of a model. Set an output directory to copy the
  edited model to a new folder, otherwise maps are overwritten.

  Example usage:
  --------------

  Update (overwrite) landuse-landcover maps in a wflow model
  hydromt update wflow /path/to/model_root -c setup_lulcmaps --opt source_name=vito

  Update reservoir maps based on default settings in a wflow model and write to new directory
  hydromt update wflow /path/to/model_root -o /path/to/model_out -c setup_reservoirs

Options:
  -o, --model-out DIRECTORY  Output model folder. Maps in MODEL_ROOT are
                             overwritten if left empty.
  -c, --components TEXT      Model components from ini file to run
  --opt TEXT                 Component specific keyword arguments, see the
                             setup_<component> method of the specific model
                             for more information about the arguments.
  -i, --config PATH          Path to hydroMT configuration file, for the model
                             specific implementation.
  -d, --data PATH            File path to yml data sources file. See
                             documentation for required yml file format.
  --dd, --deltares-data      Parse default deltares data yml from
                             https://github.com/DirkEilander/hydromt-
                             artifacts/releases
  -q, --quiet                Decrease verbosity.
  -v, --verbose              Increase verbosity.
  --help                     Show this message and exit.

Update sfincs precipitation

Now we will add the precipitation and write the model to a new folder

[4]:
!hydromt update sfincs ./sfincs_coastal -o ./sfincs_coastal_precip -i sfincs_update_precip.ini -v
2022-07-01 15:23:22,083 - update - log - INFO - HydroMT version: 0.4.5
2022-07-01 15:23:22,083 - update - main - INFO - Updating sfincs model at /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal (r).
2022-07-01 15:23:22,083 - update - main - INFO - Output dir: /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_precip
2022-07-01 15:23:22,083 - update - main - INFO - User settings:
2022-07-01 15:23:22,087 - update - model_api - INFO - Initializing sfincs model from hydromt_sfincs (v0.2.2.dev0).
2022-07-01 15:23:22,182 - update - sfincs - INFO - Model read
2022-07-01 15:23:22,187 - update - model_api - INFO - setup_p_forcing_from_grid.precip_fn: era5_hourly
2022-07-01 15:23:22,187 - update - model_api - INFO - setup_p_forcing_from_grid.dst_res: None
2022-07-01 15:23:22,187 - update - model_api - INFO - setup_p_forcing_from_grid.aggregate: False
2022-07-01 15:23:22,190 - update - data_adapter - INFO - Adding sample data v0.0.6 from artifacts
2022-07-01 15:23:22,263 - update - data_adapter - INFO - DataCatalog: Getting era5_hourly RasterDataset netcdf data from /home/runner/.hydromt_data/data/v0.0.6/era5_hourly.nc
2022-07-01 15:23:22,440 - update - sfincs - INFO - Writing model data to /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_precip
2022-07-01 15:23:22,480 - update - sfincs - INFO - Write raster file(s) for staticmaps to 'gis' subfolder
2022-07-01 15:23:22,522 - update - sfincs - INFO - Write forcing files
2022-07-01 15:23:22,558 - update - sfincs - INFO - Write vector file(s) for forcing.bzs to 'gis' subfolder
2022-07-01 15:23:22,594 - update - model_api - INFO - Writing model config to /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_precip/sfincs.inp

The example above means the following: run hydromt with:

  • update sfincs: i.e. update a sfincs model

  • ./venice_sfincs: original model folder

  • -o ./venice_sfincs_precip: output updated model folder

  • -i sfincs_update_precip.ini: setup configuration file containing the components to update and their different options

  • v: give some extra verbosity (2 * v) to display feedback on screen. Now debug messages are provided.

Let’s inspect the new model folder

[5]:
!ls ./sfincs_coastal
hydromt.log  sfincs.bzs  sfincs.ind  sfincs.man  sfincs.precip
sfincs.bnd   sfincs.dep  sfincs.inp  sfincs.msk  sfincs.scs

We now have a precip.nc file with the precipitation. The .inp file now also contains a reference to this dataset.

Inspect forcing data

The forcing data will also be available for analysis and plotting within hydromt. The plot_forcing method plots the area averaged precipitation. If you are familiar with xarray and matplotlib, it is straighforward to make some other plots as well.

[6]:
%matplotlib inline
from hydromt_sfincs import SfincsModel
import matplotlib.pyplot as plt

Below, we first plot the area averaged time series

[7]:
mod = SfincsModel(root="sfincs_coastal_precip", mode="r")
mod.forcing.pop("bzs", None)  # let's focus on precip for now
_ = mod.plot_forcing()
../_images/_examples_update_model_18_0.png

We can also manipulate the forcing and make spatial plots with xarray logic. Below we plot the time accumulated rainfall over the entire period.

[8]:
# precipitation forcing is in the key "netampr"
precip_sum = mod.forcing["netampr"].sum(dim="time")
precip_sum.attrs.update(unit="mm")
_ = precip_sum.plot()
../_images/_examples_update_model_20_0.png

We have another .ini file that also includes water level boundaries from the Global Tide and Surge Model, and also includes several measurement locations (setup_gauges). Below we print the contents of this .ini file and the gauges file.

[9]:
fn_ini = "sfincs_update_forcing.ini"
with open(fn_ini, "r") as f:
    txt = f.read()
print(txt)
[setup_config]
tref = 20100201 000000
tstart = 20100201 000000
tstop = 20100210 000000

[setup_gauges]
gauges_fn = data/venice_gauges.csv   # gauges point locations
crs = 4326

[setup_h_forcing]
geodataset_fn = gtsmv3_eu_era5     # waterlevel point timeseries dataset
timeseries_fn = None            # timeseries data at waterlevel gauges
mdt_fn = dtu10mdt_egm96         # mean dynamic topography ['mdt']
buffer = 0                      # buffer around model region to select gauges

[setup_p_forcing_from_grid]
precip_fn = era5_hourly         # gridded precipitation data ['precip']
dst_res = None                  # output resolution (m)
aggregate = False               # if True return the aggregated mean as spatially uniform precip

[10]:
# content of gauges
import pandas as pd

fn_gauges = "data/venice_gauges.csv"
df = pd.read_csv(fn_gauges)
df
[10]:
ID Name x y
0 1001 Venice1 12.513886 45.508725
1 1002 Venice2 12.443603 45.495637
2 1003 Venice3 12.347785 45.423504
3 1004 Venice4 12.312603 45.443641

You can see a few things: * the water level forcing configured under setup_h_forcing refers to a dataset from the catalog. Check the .yml of the catalog (see folder $USER_HOME/.hydromt_data for further details) * the file venice_gauges.csv has a very simple setup with latitude/longitude coordinate pairs

Now let’s build another version of the model that includes these new inputs

[11]:
!hydromt update sfincs ./sfincs_coastal -o ./sfincs_coastal_forcing -i sfincs_update_forcing.ini -v
2022-07-01 15:23:30,017 - update - log - INFO - HydroMT version: 0.4.5
2022-07-01 15:23:30,017 - update - main - INFO - Updating sfincs model at /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal (r).
2022-07-01 15:23:30,017 - update - main - INFO - Output dir: /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_forcing
2022-07-01 15:23:30,017 - update - main - INFO - User settings:
2022-07-01 15:23:30,023 - update - model_api - INFO - Initializing sfincs model from hydromt_sfincs (v0.2.2.dev0).
2022-07-01 15:23:30,121 - update - sfincs - INFO - Model read
2022-07-01 15:23:30,126 - update - model_api - INFO - setup_gauges.gauges_fn: /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/data/venice_gauges.csv
2022-07-01 15:23:30,126 - update - model_api - INFO - setup_gauges.overwrite: False
2022-07-01 15:23:30,126 - update - data_adapter - INFO - Adding sample data v0.0.6 from artifacts
2022-07-01 15:23:30,209 - update - data_adapter - INFO - DataCatalog: Getting venice_gauges GeoDataFrame csv data from /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/data/venice_gauges.csv
2022-07-01 15:23:30,210 - update - data_adapter - INFO - GeoDataFrame: Read csv data and clip to geom (epsg:32633) [268650.000, 5018550.000, 332400.000, 5059350.000].
2022-07-01 15:23:30,226 - update - sfincs - INFO - obs set based on /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/data/venice_gauges.csv
2022-07-01 15:23:30,226 - update - model_api - INFO - setup_h_forcing.geodataset_fn: gtsmv3_eu_era5
2022-07-01 15:23:30,226 - update - model_api - INFO - setup_h_forcing.timeseries_fn: None
2022-07-01 15:23:30,226 - update - model_api - INFO - setup_h_forcing.offset_fn: None
2022-07-01 15:23:30,226 - update - model_api - INFO - setup_h_forcing.buffer: 0
2022-07-01 15:23:30,237 - update - data_adapter - INFO - DataCatalog: Getting gtsmv3_eu_era5 GeoDataset netcdf data from /home/runner/.hydromt_data/data/v0.0.6/gtsmv3_eu_era5.nc
2022-07-01 15:23:30,238 - update - data_adapter - INFO - GeoDataset: Read netcdf data and clip to geom (epsg:32633) [288900.000, 5018550.000, 332400.000, 5049900.000].
2022-07-01 15:23:30,301 - update - model_api - WARNING - Replacing forcing: bzs
2022-07-01 15:23:30,301 - update - model_api - INFO - setup_p_forcing_from_grid.precip_fn: era5_hourly
2022-07-01 15:23:30,302 - update - model_api - INFO - setup_p_forcing_from_grid.dst_res: None
2022-07-01 15:23:30,302 - update - model_api - INFO - setup_p_forcing_from_grid.aggregate: False
2022-07-01 15:23:30,306 - update - data_adapter - INFO - DataCatalog: Getting era5_hourly RasterDataset netcdf data from /home/runner/.hydromt_data/data/v0.0.6/era5_hourly.nc
2022-07-01 15:23:30,481 - update - sfincs - INFO - Writing model data to /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_forcing
2022-07-01 15:23:30,521 - update - sfincs - INFO - Write raster file(s) for staticmaps to 'gis' subfolder
2022-07-01 15:23:30,564 - update - sfincs - INFO - Write staticgeom files
2022-07-01 15:23:30,565 - update - sfincs - INFO - Write vector file(s) for staticgeoms to 'gis' subfolder
2022-07-01 15:23:30,598 - update - sfincs - INFO - Write forcing files
2022-07-01 15:23:30,641 - update - sfincs - INFO - Write vector file(s) for forcing.bzs to 'gis' subfolder
2022-07-01 15:23:30,654 - update - model_api - INFO - Writing model config to /home/runner/work/hydromt_sfincs/hydromt_sfincs/docs/_examples/sfincs_coastal_forcing/sfincs.inp

We can now again inspect the model

[12]:
# define the model's configuration file
root = r"./sfincs_coastal_forcing"

# read the model with hydromt sfincs methods
mod = SfincsModel(root=root, mode="r")
mod.read()
_ = mod.plot_basemap(figsize=(13, 7))
../_images/_examples_update_model_27_0.png

We also updated the tidal boundary conditions from gtsm. Below we also inspect these:

[13]:
_ = mod.plot_forcing()
../_images/_examples_update_model_29_0.png