smash.factory.generate_mesh#

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

Automatic mesh generation.

Parameters:

flwdir_pathstr: Path to the flow directions file. The flow direction convention is the following:
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 filled in.
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. In case of bouding box meshing, the code argument is not used.

Note

If not given, the default code is:

['_c0', '_c1', ..., '_cn-1'] with \(n\), the number of gauges (i.e. the size of x)
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\).
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 filled in.

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 degree, the value of dx is approximated in meter.

dynumpy.ndarray

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

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 meter 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.

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)