API reference

SFINCS model class

Initialize

SfincsModel([root, mode, config_fn, ...])

The SFINCS model class (SfincsModel) contains methods to read, write, setup and edit SFINCS models.

Setup components

SfincsModel.setup_config(**cfdict)

Update config with a dictionary

SfincsModel.setup_topobathy(topobathy_fn[, ...])

Setup model grid and interpolate topobathy (dep) data to this grid.

SfincsModel.setup_merge_topobathy(topobathy_fn)

Updates the existing model topobathy data (dep file) with a new topobathy source within the current model extent.

SfincsModel.setup_mask([mask_fn, ...])

Creates mask of active model cells.

SfincsModel.setup_bounds([btype, mask_fn, ...])

Set boundary cells in the model mask.

SfincsModel.setup_river_hydrography([...])

Setup hydrography layers for flow directions ("flwdir") and upstream area ("uparea") which are required to setup the setup_river* model components.

SfincsModel.setup_river_bathymetry([...])

Burn rivers into the model elevation (dep) file.

SfincsModel.setup_river_inflow([...])

Setup river inflow (source) points where a river enters the model domain.

SfincsModel.setup_river_outflow([...])

Setup open boundary cells (mask=3) where a river flows out of the model domain.

SfincsModel.setup_manning_roughness([...])

Setup model manning roughness map (manningfile) from gridded land-use/land-cover map and manning roughness mapping table.

SfincsModel.setup_cn_infiltration([cn_fn, ...])

Setup model potential maximum soil moisture retention map (scsfile) from gridded curve number map.

SfincsModel.setup_gauges(gauges_fn[, overwrite])

Setup model observation point locations.

SfincsModel.setup_structures(structures_fn, ...)

Setup thin dam or weir structures.

SfincsModel.setup_h_forcing([geodataset_fn, ...])

Setup waterlevel boundary point locations (bnd) and time series (bzs).

SfincsModel.setup_q_forcing([geodataset_fn, ...])

Setup discharge boundary point locations (src) and time series (dis).

SfincsModel.setup_q_forcing_from_grid(...[, ...])

Setup discharge boundary location (src) and timeseries (dis) based on a gridded discharge dataset.

SfincsModel.setup_p_forcing([precip_fn])

Setup spatially uniform precipitation forcing (precip).

SfincsModel.setup_p_forcing_from_grid([...])

Setup precipitation forcing from a gridded spatially varying data source.

Plot methods

SfincsModel.plot_basemap([fn_out, variable, ...])

Create basemap plot.

SfincsModel.plot_forcing([fn_out])

Plot model timeseries forcing.

Attributes

SfincsModel.region

Returns geometry of region of the model area of interest.

SfincsModel.mask

Returns model mask map.

SfincsModel.crs

Returns coordinate reference system embedded in staticmaps.

SfincsModel.res

Returns coordinates of staticmaps.

SfincsModel.root

Path to model folder.

SfincsModel.config

Returns parsed model configuration.

SfincsModel.staticmaps

xarray.Dataset representation of all static parameter maps

SfincsModel.staticgeoms

geopandas.GeoDataFrame representation of all model geometries

SfincsModel.forcing

dict of xarray.dataarray representation of all forcing

SfincsModel.states

dict xarray.dataarray representation of all states

SfincsModel.results

dict xarray.dataarray representation of model results

High level methods

SfincsModel.read()

Read the complete model schematization and configuration from file.

SfincsModel.write()

Write the complete model schematization and configuration to file.

SfincsModel.build(region[, res, write, opt])

Single method to build a model from scratch based on settings in opt.

SfincsModel.update([model_out, write, opt])

Single method to update a model based the settings in opt.

SfincsModel.set_root(root[, mode])

Initialized the model root.

Low level methods

SfincsModel.update_spatial_attrs()

Update geospatial config (sfincs.inp) attributes based on staticmaps

SfincsModel.get_spatial_attrs([crs])

Get geospatial config (sfincs.inp) attributes.

SfincsModel.set_forcing_1d(name[, ts, xy])

Set 1D forcing and update staticgoms and config accordingly.

SfincsModel.get_model_time()

Return (tstart, tstop) tuple with parsed model start and end time

General methods

SfincsModel.setup_config(**cfdict)

Update config with a dictionary

SfincsModel.get_config(*args[, fallback, ...])

Get a config value at key(s).

SfincsModel.set_config(*args)

Update the config dictionary at key(s) with values.

SfincsModel.read_config([config_fn])

Parse config from file.

SfincsModel.write_config([rel_path])

Write config to <root/config_fn>

SfincsModel.set_staticmaps(data[, name])

Add data to staticmaps.

SfincsModel.read_staticmaps([crs])

Read SFINCS binary staticmaps and save to staticmaps attribute.

SfincsModel.write_staticmaps()

Write SFINCS staticmaps to binary files including map index file.

SfincsModel.set_staticgeoms(geom, name)

Add geom to staticmaps

SfincsModel.read_staticgeoms()

Read geometry files if and save to staticgeoms attribute.

SfincsModel.write_staticgeoms()

Write staticgeoms to bnd/src/obs xy files and thd/weir structure files.

SfincsModel.set_forcing(data[, name])

Add data to forcing attribute which is a dictionary of xarray.DataArray.

SfincsModel.read_forcing()

Read forcing files and save to forcing attribute.

SfincsModel.write_forcing()

Write forcing to ascii (bzd/dis/precip) and netcdf (netampr) files.

SfincsModel.set_states(data[, name])

Add data to states attribute which is a dictionary of xarray.DataArray.

SfincsModel.read_states([crs])

Read waterlevel state (zsini) from ascii file and save to states attribute.

SfincsModel.write_states([fmt])

Write waterlevel state (zsini) to ascii map file.

SfincsModel.set_results(data[, name, ...])

Add data to results attribute which is a dictionary of xarray.DataArray and/or xarray.Dataset.

SfincsModel.read_results([chunksize, drop, ...])

Read results from sfincs_map.nc and sfincs_his.nc and save to the results attribute.

SFINCS workflows

workflows.merge_topobathy(da1, da2[, ...])

Return merged topobathy data from two datasets.

workflows.get_rivbank_dz(gdf_riv, da_msk, da_hnd)

Return river bank height estimated as from height above nearest drainage (HAND) values adjecent to river cells.

workflows.get_river_bathymetry(ds, flwdir[, ...])

Estimate river bedlevel zb using gradually varying flow (gvf), manning's equation (manning) or a power-law relation (powlaw) rivdph_method.

workflows.burn_river_zb(gdf_riv, da_elv, da_msk)

Burn bedlevels from gdf_riv (column zb) into the DEM da_elv at river cells indicated in da_msk.

workflows.snap_discharge(ds, gdf[, wdw, ...])

Snaps point locations to grid cell with smallest difference in upstream area within wdw around the original location if the local cell does not meet the error criteria.

workflows.river_boundary_points(da_flwdir, ...)

Returns the locations where a river flows in (btype='inflow') or out (btype='outflow') of the region.

workflows.landuse(da, ds_like, fn_map[, ...])

Returns landuse map and related parameter maps.

workflows.cn_to_s(da_cn[, da_mask, nodata])

Convert Curve Numbers to potential maximum soil moisture retention S [inch].

SFINCS low-level methods

Input/Output methods

read_inp(fn)

Read sfincs.inp file and parse to dictionary.

write_inp(fn, conf)

Write sfincs.inp file from dictionary.

read_binary_map(fn, ind, shape[, mv, dtype])

Read binary map.

write_binary_map(fn, data, msk[, dtype])

Write binary map file.

read_binary_map_index(fn_ind)

Read binary map index file.

write_binary_map_index(fn_ind, msk)

Write flat index of binary map file.

read_ascii_map(fn)

Read ascii map

write_ascii_map(fn, data[, fmt])

Write ascii map

read_timeseries(fn, tref)

Read ascii timeseries files such as sfincs.bzs, sfincs.dis and sfincs.precip.

write_timeseries(fn, df, tref[, fmt])

Write pandas.DataFrame to fixed width ascii timeseries files such as sfincs.bzs, sfincs.dis and sfincs.precip.

read_xy(fn[, crs])

Read sfincs xy files and parse to GeoDataFrame.

write_xy(fn, gdf[, fmt])

Write geopandas.GeoDataFrame with Point geometries to point xy files.

read_structures(fn)

Read structure files to list of dictionaries.

write_structures(fn, feats[, stype, fmt])

Write list of structure dictionaries to file

read_sfincs_map_results(fn_map[, hmin, crs, ...])

Read sfincs_map.nc staggered grid netcdf files and parse to two hydromt.RasterDataset objects: one with face and one with edge variables.

read_sfincs_his_results(fn_his[, crs, chunksize])

Read sfincs_his.nc point timeseries netcdf file and parse to hydromt.GeoDataset object.

Utilities

utils.mask_topobathy(da_elv[, gdf_mask, ...])

Returns a boolean mask of valid (non nondata) elevation cells, optionally bounded by several criteria.

utils.mask_bounds(da_msk[, da_elv, ...])

Returns a boolean mask model boundary cells, optionally bounded by several criteria.

utils.get_spatial_attrs(config[, crs, logger])

Returns geospatial attributes shape, crs and transform from config dict.

utils.parse_datetime(dt[, format])

Checks and/or parses datetime from a string, default sfincs datetime string format

utils.gdf2structures(gdf)

Convert GeoDataFrame[LineString] to list of structure dictionaries

utils.structures2gdf(feats[, crs])

Convert list of structure dictionaries to GeoDataFrame[LineString]

Visualization

plots.plot_basemap(staticmaps, staticgeoms)

Create basemap plot.

plots.plot_forcing(forcing, **kwargs)

Plot model timeseries forcing.