smash.factory.generate_mesh#

smash.factory.generate_mesh(flwdir_path, bbox=None, x=None, y=None, area=None, code=None, shp_path=None, max_depth=1, epsg=None, area_error_th=None)[source]#

Automatic mesh generation.

Parameters:
flwdir_pathstr

Path to the flow directions file. The flow direction convention is the following:

../../../_images/flwdir_convention.png
bboxlist[float, float, float, float] or None, default None

Bounding box with the following convention, (xmin, xmax, ymin, ymax). The bounding box values must respect the CRS of the flow direction file. If the given bounding box does not overlap the flow direction, the bounding box is padded to the nearest overlapping cell.

Note

If not given, x, y and area must be provided.

xfloat, list[float, …] or None, default None

The x-coordinate(s) of the catchment outlet(s) to mesh. The x value(s) must respect the CRS of the flow directions file. The x size must be equal to y and area size.

yfloat, list[float, …] or None, default None

The y-coordinate(s) of the catchment outlet(s) to mesh. The y value(s) must respect the CRS of the flow directions file. The y size must be equal to x and area size.

areafloat, list[float, …] or None, default None

The area of the catchment(s) to mesh in m². The area size must be equal to x and y size.

codestr, list[str, …] or None, default None

The code of the catchment(s) to mesh. The code size must be equal to x, y and area.

Note

If not given, the default code is:

['_c0', '_c1', ..., '_cn-1'] with \(n\), the number of gauges (i.e. the size of x)

shp_pathstr or None, default None

Path to the shapefile containing the contours of the catchment(s) to mesh. The shapefile must contain a code field to identify each catchment based on the code argument. The shapefile must be in the same projection as the flow direction file. For all the catchments in the shapefile, the contour-based method will be applied instead of the area-based one.

max_depthint, default 1

The maximum depth accepted by the algorithm to find the catchment outlet. A max_depth of 1 means that the algorithm will search among the 2-length combinations in (row - 1, row, row + 1; col - 1, col, col + 1), the coordinates that minimize the relative error between the given catchment area and the modeled catchment area calculated from the flow directions file. This can be generalized to \(n\).

../../../_images/max_depth.png
epsgstr, int or None, default None

The EPSG value of the flow directions file. By default, if the projection is well defined in the flow directions file, it is not necessary to provide the value of the EPSG. On the other hand, if the projection is not well defined in the flow directions file (i.e. in ASCII file), the epsg argument must be provided.

area_error_th: `float` or None, default None

The threshold of the relative error between the modeled area and the observed area beyond which the outlets and the catchment will be excluded from the final mesh. The relative error is computed as follows: \(error=(area_dln - area)/area\). For example, area_error_th=0.2 means that all outlets where the surface error is higher than 20% will be excluded.

Note

If not given, the computation of the error on the area is ignored and all outlets are included in the mesh.

Returns:
meshdict[str, Any]

Model initialization mesh dictionary. The elements are:

xresfloat

X cell size. The unit depends on the projection (meter or degree)

yresfloat

Y cell size. The unit depends on the projection (meter or degree)

xminfloat

X minimum value. The unit depends on the projection (meter or degree)

ymaxfloat

Y maximum value. The unit depends on the projection (meter or degree)

nrowint

Number of rows

ncolint

Number of columns

dxnumpy.ndarray

An array of shape (nrow, ncol) containing X cell size. If the projection unit is in degrees, the value of dx is approximated in meters.

dynumpy.ndarray

An array of shape (nrow, ncol) containing Y cell size. If the projection unit is in degrees, the value of dy is approximated in meters.

flwdirnumpy.ndarray

An array of shape (nrow, ncol) containing flow direction.

flwdstnumpy.ndarray

An array of shape (nrow, ncol) containing flow distance. It corresponds to the distance in meters from each cell to the most downstream gauge. If there are multiple non-nested downstream gauges, the flow distance are computed for each gauge.

flwaccnumpy.ndarray

An array of shape (nrow, ncol) containing flow accumulation. The unit is the square meter.

nparint

Number of partition. A partition delimits a set of independent cells on the drainage network. The first partition represents all the most upstream cells and the last partition the gauge(s). It is possible to loop in parallel over all the cells in the same partition.

ncparnumpy.ndarray

An array of shape (npar,) containing the number of cells per partition.

cscparnumpy.ndarray

An array of shape (npar,) containing the cumulative sum of cells per partition.

cpar_to_rowcolnumpy.ndarray

An array of shape (nrow*ncol, 2) containing the mapping from the sorted partition cells to row, col indices.

flwparnumpy.ndarray

An array of shape (nrow, ncol) containing the flow partitions. Values range from 1 to npar.

nacint

Number of active cells. A domain cell is considered active if it contributes to the discharge at the gauge if gauge coordinates are entered (i.e. x, y) else the whole bouding box is considered active.

active_cellnumpy.ndarray

An array of shape (nrow, ncol) containing a mask of active cells.

  • 0: Inactive cell

  • 1: Active cell

ngint

Number of gauge.

gauge_posnumpy.ndarray

An array of shape (ng, 2) containing the row, col indices of each gauge.

codenumpy.ndarray

An array of shape (ng,) containing the code of each gauge. The code is an alias enabling the user to identify the gauges in the mesh.

areanumpy.ndarray

An array of shape (ng,) containing the real observed draining area for each gauge.

area_dlnnumpy.ndarray

An array of shape (ng,) containing the delineated draining area from the flow direction for each gauge. It is the relative error between area and area_dln which is minimized when trying to find the gauge coordinated on the flow direction file.

Note

The following variables, flwdst, gauge_pos, code, area and area_dln are only returned if gauge coordinates are entered (i.e. x, y) and not just a bounding box (i.e. bbox).

See also

smash.Model

Primary data structure of the hydrological model smash.

smash.factory.detect_sink

Detect the sink cells in a flow direction file.

Examples

>>> from smash.factory import load_dataset, generate_mesh

Retrieve a path to a flow direction file. A pre-processed file is available in the smash package (the path is updated for each user).

>>> flwdir = load_dataset("flwdir")
flwdir

Generate a mesh from gauge coordinates. The following coordinates used are those of the Cance dataset

>>> mesh = generate_mesh(
    flwdir_path=flwdir,
    x=[840_261, 826_553, 828_269],
    y=[6_457_807, 6_467_115, 6_469_198],
    area=[381.7 * 1e6, 107 * 1e6, 25.3 * 1e6],
    code=["V3524010", "V3515010", "V3517010"],
)
>>> mesh.keys()
dict_keys(['xres', 'yres', 'xmin', 'ymax', 'nrow', 'ncol', 'dx', 'dy', 'flwdir',
'flwdst', 'flwacc', 'npar', 'ncpar', 'cscpar', 'cpar_to_rowcol', 'flwpar', 'nac',
'active_cell', 'ng', 'gauge_pos', 'code', 'area', 'area_dln'])

Access a specific value in the mesh dictionary

>>> mesh["xres"], mesh["nac"], mesh["ng"]
(1000.0, 383, 3)

Generate a mesh from a bounding box (xmin, xmax, ymin, ymax). The following bounding box used correspond to the France boundaries

>>> mesh = generate_mesh(
    flwdir_path=flwdir,
    bbox=[100_000, 1_250_000, 6_050_000, 7_125_000],
)
>>> mesh.keys()
dict_keys(['xres', 'yres', 'xmin', 'ymax', 'nrow', 'ncol', 'dx', 'dy', 'flwdir',
'flwacc', 'npar', 'ncpar', 'cscpar', 'cpar_to_rowcol', 'flwpar', 'nac', 'active_cell',
'ng'])

Access a specific value in the mesh dictionary

>>> mesh["xres"], mesh["nac"], mesh["ng"]
(1000.0, 906044, 0)
On this page

This Page