model.environment.river_network¶

River-network geometry adapter for ADELM.

Reads a river-network parameter file (a NetCDF prepared offline from a global flow-direction / floodplain dataset) and builds the static geometry container consumed by :func:model.processes.river_routing.

The NetCDF is a flat list of valid river cells indexed by the catchment dimension. Two conventions must be translated here:

  • downstream_id references the downstream cell in global linear-index space (catchment_id = cx*ny + cy), not array position. We remap it to local array positions over the selected subset.

  • River mouths / basin outlets are encoded as self-loops (downstream_id == catchment_id); there are no negative sentinels. These become sink_mask cells whose water leaves the domain. After a subset, any cell whose downstream falls outside the subset also becomes a sink.

When routing is coupled to the land model, the geometry must be built in the same cell order as the ADELM land grid, so that cell i is the same physical cell in both. :func:build_geometry_for_coords does this by matching on an integer grid key over the shared lattice (robust to the file’s internal row/column orientation).

Module Contents¶

Functions¶

load_river_geometry

Build the routing geometry from a parameters.nc (native cell order).

build_geometry_for_coords

Build routing geometry aligned to an explicit ordered list of cell centres.

delineate_upstream

Boolean mask of all cells draining into the seed cells (incl. the seeds).

build_training_domain

Build a routing-calibration training domain from a set of gauges.

flow_accumulate

Accumulate cell_value downstream along the network (incl. self).

API¶

model.environment.river_network.load_river_geometry(parameters_nc, select=None, bbox=None, device='cpu', dtype=torch.float64)¶

Build the routing geometry from a parameters.nc (native cell order).

Parameters:

  • select (np.ndarray, optional) – Boolean mask or integer index over the global catchments to keep.

  • bbox (tuple, optional) – (lon_min, lon_max, lat_min, lat_max) filter on cell centres.

model.environment.river_network.build_geometry_for_coords(parameters_nc, target_lon, target_lat, device='cpu', dtype=torch.float64)¶

Build routing geometry aligned to an explicit ordered list of cell centres.

Used when routing is coupled to the land model: target_lon/target_lat are the coordinates of the ADELM land cells, in land order. The returned geometry has one entry per land cell that is also a river catchment, in the same order, and land_keep_mask marks which land cells were kept (non-catchment land cells — rare at this resolution — are dropped from routing).

Returns:

  • geometry (dict) – As in load_river_geometry(), ordered to match the kept land cells.

  • land_keep_mask (np.ndarray (bool)) – [n_land] mask selecting the land cells that map to a catchment.

model.environment.river_network.delineate_upstream(downstream_idx, seed_mask, max_iter=20000)¶

Boolean mask of all cells draining into the seed cells (incl. the seeds).

Propagates upstream over the downstream-pointer network: a cell joins the basin once its downstream cell is in the basin. Used to build a training domain from a set of gauges (the union of their contributing basins). Sink cells self-loop, so they never pull other cells in spuriously.

Parameters:

  • downstream_idx (torch.LongTensor) – Array-position index of each cell’s downstream cell [n].

  • seed_mask (torch.BoolTensor) – True at the outlet cells whose upstream area is wanted [n].

model.environment.river_network.build_training_domain(parameters_nc, gauge_ids, min_area_km2=1000.0, allocation_path=None, device='cpu', dtype=torch.float64)¶

Build a routing-calibration training domain from a set of gauges.

The domain is the union of the gauges’ upstream basins. Land forcing is later loaded only on these cells, and the gauges are the loss points (their cell’s routed discharge is compared to observed discharge). Gauges whose drainage area is below min_area_km2 are dropped: at 0.1 degree (~100 km2/cell) a basin of only a few cells cannot be meaningfully represented.

Returns:

  • longitude, latitude : [n_dom] cell centres, in the order that defines the domain (use for the land-grid pixel_idx).

  • geometry : routing geometry for the domain (downstream_idx local, sink_mask with gauge outlets as sinks, cell_area_m2, …).

  • gauge_ids : [n_g] gauges that mapped into the domain.

  • gauge_cell : [n_g] domain-local cell index of each gauge (loss points).

  • catchment_id : [n_dom] bookkeeping.

Return type:

dict with

model.environment.river_network.flow_accumulate(downstream_idx, sink_mask, cell_value, max_iter=20000)¶

Accumulate cell_value downstream along the network (incl. self).

Validates topology: accumulating cell_area must reproduce upstream_area.