pygetm.rivers module

class pygetm.rivers.GlobalRiver(name: str, x: int | float, y: int | float, coordinate_type: CoordinateType = CoordinateType.IJ, **attrs)

Bases: object

Single river in the global domain.

Parameters:

• name – unique name for this river

• x – x coordinate of river

• y – y coordinate of river

• coordinate_type – coordinate type of x and y (LONLAT spherical, XY for Cartesian coordinates)

• **attrs – additional attributes for this river

locate(locator: Locator)

If this river position is specified by (lon, lat) or (x, y), map it to the nearest non-masked grid cell.

to_local_grid(grid: Grid) → LocalRiver | None

Map river to local subdomain.

Parameters:

grid – local grid

Returns:

local river instance, or None if the river falls outside the local subdomain

class pygetm.rivers.GlobalRiverCollection(nx: int, ny: int, default_coordinate_type: CoordinateType, logger: Logger)

Bases: Mapping[str, GlobalRiver]

Collection of rivers in the global domain.

It acts as a mapping from river names to GlobalRiver instances.

add_by_index(name: str, i: int, j: int, **kwargs) → GlobalRiver

Add a river at a location specified by the indices of a tracer point

Parameters:

• name – river name

• i – global domain index in x-direction (0-based)

• j – global domain index in y-direction (0-based)

• **kwargs – additional keyword arguments passed to add_by_location()

Returns:

river instance

add_by_location(name: str, x: int | float, y: int | float, coordinate_type: CoordinateType | None = None, zl: float | None = None, zu: float | None = None, vertical_position: VerticalPosition = VerticalPosition.DistanceFromSurface, **attrs) → GlobalRiver

Add a river at a location specified by the nearest coordinates

Parameters:

• name – river name

• x – x coordinate of river

• y – y coordinate of river

• coordinate_type – coordinate type of x and y (LONLAT for spherical, XY for Cartesian coordinates, IJ for 0-based indices into the global tracer grid)

• zl – lower limit (deepest point) of river penetration (m; >=0). Defaults to bottom

• zu – upper limit of river penetration (m; >=0). Defaults to surface

• vertical_position – whether depth limits zl and zu are distances from the surface or from the bottom

• **attrs – additional attributes for this river

Returns:

river instance

initialize(grid: Grid) → LocalRiverCollection

Return a collection of only those rivers that fall within the local subdomain.

map_to_grid(locator: Locator)

Map rivers to cell centers. This can only be called on MPI nodes that have the full domain (typically the root node only).

class pygetm.rivers.LocalRiver(grid: Grid, name: str, i: int, j: int, zl: float, zu: float, vertical_position: VerticalPosition, **attrs)

Bases: Mapping[str, RiverTracer]

Single river in the local subdomain.

It acts as a mapping from tracer names to RiverTracer instances, allowing you to access and control the value of each tracer in this river.

class pygetm.rivers.LocalRiverCollection(grid: Grid, rivers: Iterable[LocalRiver], logger: Logger)

Bases: Mapping[str, LocalRiver]

Collection of rivers that fall within the local subdomain.

It acts as a mapping from river names to LocalRiver instances

flag_prescribed_tracers()

get_active_part_of_layers(h: ndarray) → ndarray

For each layer of each river cell, get the part (m) affected by the river

Parameters:

h – layer thicknesses for each river cell (shape: nz x nrivers)

Returns:

nz x nrivers)

Return type:

part of each layer affected by the river (shape

class pygetm.rivers.RiverTracer(grid: Grid, river_name: str, tracer_name: str, value: ndarray, follow: ndarray, **kwargs)

Bases: Array

Single tracer in a single river.

Call pygetm.core.Array.set() on this object to prescribe the tracer value in the river, or set the follow_target_cell attribute to True to take the river’s tracer value from the model cell it flows into.

If you prescribe the tracer value, the follow_target_cell attribute will automatically be set to False.

If you do not prescribe the tracer value and follow_target_cell is False, the tracer value will default to 0.0.

property follow_target_cell: bool

Whether to take the tracer value in the river from the model cell it flows into.

class pygetm.rivers.VerticalPosition(*values)

Bases: Enum

DistanceFromBottom = 2

DistanceFromSurface = 1