API#

SFINCS Model class#

The hydromt_sfincs.SfincsModel class is the main entry point to read, write, build, and update SFINCS models using HydroMT. It uses the functionalities provided by the reusable components defined in the hydromt_sfincs.components module.

SfincsModel([root, mode, write_gis, data_libs])

SFINCS model class.

Methods#

`SfincsModel.read`()	Read SfincsModel from disk.
`SfincsModel.write`()	Write SfincsModel to disk.
`SfincsModel.build`(*[, write])	Single method to build a model from scratch based on settings in steps.
`SfincsModel.update`(*[, model_out, write, ...])	Single method to update a model based the settings in steps.

Plot methods#

`SfincsModel.plot_basemap`([fn_out, variable, ...])	Create basemap plot.
`SfincsModel.plot_forcing`([fn_out, forcings])	Plot model timeseries forcing.

Attributes#

`SfincsModel.root`	Model root
`SfincsModel.crs`	Returns the model crs
`SfincsModel.region`	Returns the geometry of the active model cells.
`SfincsModel.bbox`	Returns the bounding box in WGS 84 of the model grid.

Components#

The hydromt_sfincs.components module defines reusable data container classes that represent configuration, grid, geometries, boundary conditions, outputs, and other model data.

Configuration#

`components.config.SfincsConfig`(model)	" Class to read and write SFINCS configuration files (sfincs.inp).
`components.config.SfincsConfig.data`	Return the Pydantic SfincsConfigVariables object.
`components.config.SfincsConfig.read`()	Read a text file with the sfincs configuration from the root folder and populate the SfincsConfigVariables.
`components.config.SfincsConfig.write`([...])	Write the SfincsConfigVariables to a text file in the root folder of the model.
`components.config.SfincsConfig.update`([...])	Update attributes using a dictionary or keyword arguments.
`components.config.SfincsConfig.update_grid_from_config`()	Update the grid properties from the configuration.
`components.config.SfincsConfig.get`(key[, ...])	Get the value for a specific key with validation check.
`components.config.SfincsConfig.set`(key, value)	Set a value for a specific key with validation using Pydantic's model_validate.
`components.config.SfincsConfig.get_set_file_variable`(key)	Return the absolute file path for a given 'key'.
`components.config.SfincsConfigVariables`	Create a new model by parsing and validating input data from keyword arguments.

Grid#

`components.grid.SfincsGrid`(model)	Regular grid component of the SfincsModel class.
`components.grid.SfincsGrid.data`	Model static gridded data as xarray.Dataset.
`components.grid.SfincsGrid.read`([data_vars])	Read SFINCS binary grid files and save to data attribute.
`components.grid.SfincsGrid.write`([data_vars])	Write SFINCS grid to binary files including map index file.
`components.grid.SfincsGrid.create`(x0, y0, ...)	Create a regular grid for the SfincsModel.
`components.grid.SfincsGrid.create_from_region`(region)	Create a regular grid for the SfincsModel based on a region.
`components.grid.SfincsElevation`(model)	SFINCS Elevation Component.
`components.grid.SfincsElevation.create`(...)	Interpolate topobathy (dep) data to the model grid.
`components.grid.SfincsMask`(model)	SFINCS Mask Component.
`components.grid.SfincsMask.create_active`([...])	Create an integer mask with inactive (mask=0) and active (mask=1) cells, optionally bounded by several criteria.
`components.grid.SfincsMask.create_boundary`([...])	Set boundary cells in the model mask.
`components.grid.SfincsRoughness`(model)	SFINCS Roughness Component.
`components.grid.SfincsRoughness.create`([...])	Setup model manning roughness map (manningfile) from gridded manning data or a combinataion of gridded land-use/land-cover map and manning roughness mapping table.
`components.grid.SfincsInfiltration`(model)	SFINCS Infiltration Component.
`components.grid.SfincsInfiltration.create_constant`([...])	Create spatially varying constant infiltration rate (qinffile).
`components.grid.SfincsInfiltration.create_cn`(cn)	Create model potential maximum soil moisture retention map (scsfile) from gridded curve number map.
`components.grid.SfincsInfiltration.create_cn_with_recovery`(...)	Create model the Soil Conservation Service (SCS) Curve Number (CN) files for SFINCS including recovery term based on the soil saturation
`components.grid.SfincsInitialConditions`(model)	SFINCS Initial Conditions Component.
`components.grid.SfincsInitialConditions.create`(ini)	Setup spatially varying initial water level (inifile).
`components.grid.SfincsStorageVolume`(model)	SFINCS Storage Volume Component.
`components.grid.SfincsStorageVolume.create`(...)	Create storage volume.
`components.grid.SfincsSubgridTable`(model[, ...])	SFINCS Subgrid Table Component.
`components.grid.SfincsSubgridTable.data`	Model static gridded data as xarray.Dataset.
`components.grid.SfincsSubgridTable.read`([...])	Load subgrid table from file for a regular grid with given mask.
`components.grid.SfincsSubgridTable.write`([...])	Write subgrid table to file for a regular grid with given mask.
`components.grid.SfincsSubgridTable.create`(...)	Create method for subgrid tables based on a list of elevation and Manning's roughness datasets.

Geometries#

`components.geometries.SfincsObservationPoints`(model)	SFINCS Observation Points Component.
`components.geometries.SfincsObservationPoints.data`	Observation point data, returned as a GeoDataFrame.
`components.geometries.SfincsObservationPoints.read`([...])	Read SFINCS observation points (.obs) file.
`components.geometries.SfincsObservationPoints.write`([...])	Write SFINCS observation points (.obs) file, and set obsfile in config (if it was not already set)
`components.geometries.SfincsObservationPoints.create`(...)	Create model observation point locations.
`components.geometries.SfincsCrossSections`(model)	SFINCS Cross-Sections Component.
`components.geometries.SfincsCrossSections.data`	Cross-section lines data, returned as a GeoDataFrame.
`components.geometries.SfincsCrossSections.read`([...])	Read ascii SFINCS cross-sections (.crs) file.
`components.geometries.SfincsCrossSections.write`([...])	Write ascii SFINCS cross-sections (.crs) file, and set crsfile in config (if it was not already set).
`components.geometries.SfincsCrossSections.create`(...)	Create model cross-sections (old name: setup_observation_lines)
`components.geometries.SfincsThinDams`(model)	SFINCS thin dams geometry component.
`components.geometries.SfincsThinDams.data`	Thin dam data, returned as a GeoDataFrame.
`components.geometries.SfincsThinDams.read`([...])	Read SFINCS thin dams (.thd) file.
`components.geometries.SfincsThinDams.write`([...])	Write SFINCS thin dams (.thd) file, and set thdfile in config (if it was not already set)
`components.geometries.SfincsThinDams.create`(...)	Create model thin dams (old name: setup_structures).
`components.geometries.SfincsWeirs`(model)	SFINCS weir geometry component.
`components.geometries.SfincsWeirs.data`	Weirs lines data, returned as a GeoDataFrame.
`components.geometries.SfincsWeirs.read`([...])	Read SFINCS weir (.weir) file.
`components.geometries.SfincsWeirs.write`([...])	Write SFINCS weir (.weir) file, and set weirfile in config (if it was not already set).
`components.geometries.SfincsWeirs.create`(...)	Create model weir lines (old name: setup_structures).
`components.geometries.SfincsDrainageStructures`(model)	SFINCS drainage structures component.
`components.geometries.SfincsDrainageStructures.data`	Drainage structures data, returns geopandas.GeoDataFrame
`components.geometries.SfincsDrainageStructures.read`([...])	Read SFINCS drainage structures (.drn) file.
`components.geometries.SfincsDrainageStructures.write`([...])	Write SFINCS drainage structures (.drn) file, and make sure drnfile is in config (if it was not already set).
`components.geometries.SfincsDrainageStructures.create`(...)	Create drainage structures such as pumps, culverts, or valves (old name: setup_drainage_structures).

Forcing#

`components.forcing.SfincsWaterLevel`(model)	Water level boundary component for SFINCS models.
`components.forcing.SfincsWaterLevel.data`	Get the internal xarray dataset/dataarray containing point timeseries and geometry information.
`components.forcing.SfincsWaterLevel.read`([...])	Read SFINCS boundary conditions (.bnd, .bzs, .bca files) or netcdf file.
`components.forcing.SfincsWaterLevel.write`([...])	Write SFINCS boundary conditions (.bnd, .bzs, .bca files) or netcdf file.
`components.forcing.SfincsWaterLevel.create`([...])	Setup waterlevel forcing.
`components.forcing.SfincsWaterLevel.create_timeseries`([...])	Applies time series boundary conditions for each point Create numpy datetime64 array for time series with python datetime.datetime objects
`components.forcing.SfincsWaterLevel.create_timeseries_from_astro`([...])	Generates boundary time series file from astronomical components
`components.forcing.SfincsWaterLevel.create_boundary_points_from_mask`([...])	Get boundary points from mask in quadtree grid.
`components.forcing.SfincsDischargePoints`(model)	Discharge point component for SFINCS models.
`components.forcing.SfincsDischargePoints.data`	Get the internal xarray dataset/dataarray containing point timeseries and geometry information.
`components.forcing.SfincsDischargePoints.read`([...])	Read SFINCS discharge points (.dis, .src files) or netcdf file.
`components.forcing.SfincsDischargePoints.write`([...])	Write SFINCS discharges (.src, .dis files) or netcdf file.
`components.forcing.SfincsDischargePoints.create`([...])	Setup discharge forcing.
`components.forcing.SfincsDischargePoints.create_timeseries`([...])	Applies time series discharges for each point Create numpy datetime64 array for time series with python datetime.datetime objects
`components.forcing.SfincsPrecipitation`(model)	SFINCS precipitation forcing.
`components.forcing.SfincsPrecipitation.data`	Meteo data.
`components.forcing.SfincsPrecipitation.read`([...])	Read precipitation data from file.
`components.forcing.SfincsPrecipitation.write`([...])	Write meteo data to file.
`components.forcing.SfincsPrecipitation.create`(precip)	Setup precipitation forcing from a gridded spatially varying data source.
`components.forcing.SfincsPrecipitation.create_uniform`([...])	Setup spatially uniform precipitation forcing (precip).
`components.forcing.SfincsPressure`(model)
`components.forcing.SfincsPressure.data`	Meteo data.
`components.forcing.SfincsPressure.read`([...])	Read meteo data from file.
`components.forcing.SfincsPressure.write`([...])	Write meteo data to file.
`components.forcing.SfincsPressure.create`(press)	Setup pressure forcing from a gridded spatially varying data source.
`components.forcing.SfincsWind`(model)
`components.forcing.SfincsWind.data`	Meteo data.
`components.forcing.SfincsWind.read`([filename])	Read meteo data from file.
`components.forcing.SfincsWind.write`([...])	Write meteo data to file.
`components.forcing.SfincsWind.create`(wind[, ...])	Setup wind forcing from a gridded spatially varying data source.
`components.forcing.SfincsWind.create_uniform`([...])	Setup spatially uniform wind forcing (wind).
`components.forcing.SfincsRivers`(model)	This class contains functions to create and manage river inflow/outflow points in the SFINCS model.
`components.forcing.SfincsRivers.data`	River geometry data.
`components.forcing.SfincsRivers.read`()	Read the file(s) into the component.
`components.forcing.SfincsRivers.write`()	Write the river inflow data to a gis-file.
`components.forcing.SfincsRivers.create_river_inflow`([...])	Setup discharge (src) points where a river enters the model domain.

Output#

components.output.SfincsOutput(model)

SFINCS model output component.

SFINCS workflows#

`workflows.merge_multi_dataarrays`(da_list[, ...])	Merge a list of data arrays by reprojecting these to a common destination grid and combine valid values.
`workflows.merge_dataarrays`(da1, da2[, ...])	Return merged data from two data arrays.
`workflows.burn_river_rect`(da_elv, gdf_riv[, ...])	Burn rivers with a rectangular cross profile into a DEM.
`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_source_points`(gdf_riv, gdf_mask)	Returns the locations where a river flows in (inflow=True) or out (inflow=False) of the model gdf_mask.
`workflows.river_centerline_from_hydrography`(...)	Returns the centerline of rivers based on a flow direction raster data (da_flwdir).
`workflows.landuse`	Landuse related workflows for SFINCS.
`workflows.cn_to_s`(da_cn[, da_mask, nodata])	Convert Curve Numbers to potential maximum soil moisture retention S [inch].
`workflows.create_topobathy_tiles`(root, ...)	Create webmercator topobathy tiles for a given region.

SFINCS low-level methods#

Input/Output methods#

`utils.read_binary_map`(fn, ind, shape[, mv, ...])	Read binary map.
`utils.write_binary_map`(fn, data, msk[, dtype])	Write binary map file.
`utils.read_binary_map_index`(fn_ind)	Read binary map index file.
`utils.write_binary_map_index`(fn_ind, msk)	Write flat index of binary map file.
`utils.read_ascii_map`(fn)	Read ascii map
`utils.write_ascii_map`(fn, data[, fmt])	Write ascii map
`utils.read_timeseries`(fn, tref)	Read ascii timeseries files such as sfincs.bzs, sfincs.dis and sfincs.precip.
`utils.write_timeseries`(fn, df, tref[, fmt])	Write pandas.DataFrame to fixed width ascii timeseries files such as sfincs.bzs, sfincs.dis and sfincs.precip.
`utils.read_xy`(fn[, crs])	Read sfincs xy files and parse to GeoDataFrame.
`utils.write_xy`(path, gdf[, fmt])	Write geopandas.GeoDataFrame with Point geometries to point xy files.
`utils.read_xyn`(fn[, crs])
`utils.write_xyn`([fn, gdf, fmt])
`utils.read_geoms`(fn)	Read structure files to list of dictionaries.
`utils.write_geoms`(fn, feats[, stype, fmt, fmt_z])	Write list of structure dictionaries to file
`utils.read_drn`(fn[, crs])	Read drainage structure files to geodataframe.
`utils.write_drn`(fn, gdf_drainage[, fmt])	Write structure files from list of dictionaries.
`utils.read_sfincs_map_results`(fn_map, ds_like)	Read sfincs_map.nc staggered grid netcdf files and parse to two hydromt.RasterDataset objects: one with face and one with edge variables.
`utils.read_sfincs_his_results`(fn_his[, crs, ...])	Read sfincs_his.nc point timeseries netcdf file and parse to hydromt.GeoDataset object.

Utilities#

`utils.parse_datetime`(dt[, format])	Checks and/or parses datetime from a string, default sfincs datetime string format
`utils.gdf2linestring`(gdf)	Convert GeoDataFrame[LineString] to list of structure dictionaries
`utils.linestring2gdf`(feats[, crs])	Convert list of structure dictionaries to GeoDataFrame[LineString]
`utils.gdf2polygon`(gdf)	Convert GeoDataFrame[Polygon] to list of structure dictionaries
`utils.polygon2gdf`(feats[, crs, zmin, zmax])	Convert list of structure dictionaries to GeoDataFrame[Polygon]
`utils.get_bounds_vector`(da_msk)	Get bounds of vectorized mask as GeoDataFrame.
`utils.mask2gdf`(da_mask[, option])	Convert a boolean mask to a GeoDataFrame of polygons.
`utils.rotated_grid`(pol, res[, dec_origin, ...])	Returns the origin (x0, y0), shape (mmax, nmax) and rotation of the rotated grid fitted to the minimum rotated rectangle around the area of interest (pol).

Visualization#

`plots.plot_basemap`(ds, geoms[, variable, ...])	Create basemap plot.
`plots.plot_forcing`(forcing, **kwargs)	Plot model timeseries forcing.
`utils.downscale_floodmap`(zsmax, dep[, ...])	Create a downscaled floodmap for (model) region.
`workflows.downscale_floodmap_webmercator`(...)	Create a downscaled floodmap for (model) region in webmercator tile format