Skip to main content

flow_paths

flow_paths

Routes of flow links through Junctions, and changes to them that only change the layout.

A Junction only merges or splits flow, so the flow links from a node through Junctions up to the next non-Junction nodes form the route of that node. Ribasim replaces each pair of links into and out of a Junction by a direct link, see simplify_graph! in the Ribasim core. Moving or adding Junctions on a route therefore changes how links are drawn, not how water flows, as long as each node keeps exchanging water with the same non-Junction nodes.

Classes

Name Description
Routes The routes of the flow links of a model, as they are when the Routes are made.

Routes

flow_paths.Routes(model)

The routes of the flow links of a model, as they are when the Routes are made.

Methods

Name Description
ends The first non-Junction nodes downstream of a flow link, or upstream if upstream, through Junctions.
links_at The flow links into node_id if upstream, else out of it.
next_node The node a flow link comes from if upstream, else goes to.
paths The route of node_id downstream, or upstream if upstream: the path from node_id to each of its links.
ends
flow_paths.Routes.ends(link_id, upstream=False)

The first non-Junction nodes downstream of a flow link, or upstream if upstream, through Junctions.

next_node
flow_paths.Routes.next_node(link_id, upstream)

The node a flow link comes from if upstream, else goes to.

paths
flow_paths.Routes.paths(node_id, upstream=False)

The route of node_id downstream, or upstream if upstream: the path from node_id to each of its links.

Only links whose own route in the other direction ends at node_id alone are part of it, so for a Basin these are the links that only carry water out of that Basin, or upstream, only into it.

Functions

Name Description
attach_to_tree Attach points to the tree of routes from start, each with a straight line from the nearest point of the tree.
branch_from_route Let the link from basin_id into node_id branch off the route from basin_id towards towards_id.
geometry_along The line from the start of a route path, see Routes.paths, to distance along its last link.
junction_tree The Junctions that only pass flow out of basin_id, or into it if upstream, and the nodes they reach.
merge_inflows Replace the flow links from basin_id to node_ids by a link to a new Junction, with straight links on.
merge_outflows Connect node_ids with straight links to the first Junction downstream that all of their routes pass.
place_on_link Move node_id onto the point of link_id nearest to it, with its link with basin_id along their route.
prune_junction Remove a Junction without inflow or outflow, or merge the two links of a Junction that only passes flow on.
rebuild_junction_trees Route the flow links of Basins along the waterways, with their Junctions where the routes split.
rebuild_junction_trees_along_top10nl Rebuild the Junctions of Basins along the Top10NL water lines and a main route, see rebuild_junction_trees.
remove_flow_link Remove a flow link, and prune the Junctions at its ends, see prune_junction.
simplified_links The flow links between non-Junction nodes that Ribasim makes of the flow links, through Junctions.
split_distance The distance along geometry of the point nearest to point, at least margin from its ends if possible.
split_link Split a flow link at distance along it with a Junction: node_id moved there, or else a new one.
tree_links The links of the tree of routes that all start at the same point, with a Junction where they split.

attach_to_tree

flow_paths.attach_to_tree(routes, start, points)

Attach points to the tree of routes from start, each with a straight line from the nearest point of the tree.

The points nearest to the tree are attached first, such that the others can branch off their lines. Where a line branches off a segment, a point is inserted in all routes along that segment, such that they share it.

Parameters

Name Type Description Default
routes dict[int, list[Coord]] per key, the coordinates of a route from start required
start Coord the start of the routes, from which the first point is attached if there are no routes required
points dict[int, Coord] per key, a point to attach required

Returns

Name Type Description
dict[int, list[Coord]] the routes, with a route to each point

branch_from_route

flow_paths.branch_from_route(model, node_id, basin_id, towards_id, margin=1.0)

Let the link from basin_id into node_id branch off the route from basin_id towards towards_id.

The branch starts at a Junction at the point of that route nearest to node_id, or at the existing Junction if that point is within margin of one, and runs straight to node_id. Returns the node id of that Junction.

geometry_along

flow_paths.geometry_along(model, path, distance, upstream)

The line from the start of a route path, see Routes.paths, to distance along its last link.

junction_tree

flow_paths.junction_tree(routes, basin_id, upstream=False, fixed=())

The Junctions that only pass flow out of basin_id, or into it if upstream, and the nodes they reach.

Junctions in fixed, and Junctions that also pass flow of other nodes, are not part of the tree but reached by it.

Returns

Name Type Description
tuple[set[int], list[int], dict[int, int]] the Junctions of the tree, the links between basin_id and them, and per node reached, its link

merge_inflows

flow_paths.merge_inflows(model, basin_id, node_ids)

Replace the flow links from basin_id to node_ids by a link to a new Junction, with straight links on.

The Junction is at the centroid of node_ids, see place_on_link to move it. Returns its node id.

merge_outflows

flow_paths.merge_outflows(model, node_ids)

Connect node_ids with straight links to the first Junction downstream that all of their routes pass.

The Junctions they passed before are pruned. Returns the node id of the Junction.

prune_junction

flow_paths.prune_junction(model, junction_id)

Remove a Junction without inflow or outflow, or merge the two links of a Junction that only passes flow on.

Neighboring Junctions are pruned in turn. A Junction with other links, such as observation links, is kept.

rebuild_junction_trees

flow_paths.rebuild_junction_trees(model, basin_ids, waterways, tolerance=10.0)

Route the flow links of Basins along the waterways, with their Junctions where the routes split.

The Junctions of a Basin are removed if they only pass the flow out of, or into, that Basin, see junction_tree, except observed Junctions and RWZI Junctions. The links to the nodes they reach are routed from the Basin node along the shortest paths of one network, see ribasim_nl.network_snapping.route_basin_links, such that the routes out of and into a Basin share their common parts, and new Junctions are added where they split. Nodes far from the waterways branch off straight from the nearest point of these routes, see attach_to_tree, also over open water, where routes over the water surface would run in parallel. Each node keeps exchanging water with the same nodes, which is asserted, and the links to the nodes reached keep their link ids. Nodes are not moved and links are not offset, see ribasim_nl.layout.tidy_layout.

Parameters

Name Type Description Default
model Model Ribasim model required
basin_ids typing.Iterable[int] Basins to rebuild the Junctions of required
waterways gpd.GeoDataFrame waterways with a boolean “main-route” column, see ribasim_nl.network_snapping.snap_to_network required
tolerance float buffer around the basin area within which waterways are used, defaults to 10.0 10.0

Returns

Name Type Description
tuple[list[int], list[int]] the ids of the links and of the Junctions that are new or changed

rebuild_junction_trees_along_top10nl

flow_paths.rebuild_junction_trees_along_top10nl(
    model,
    basin_ids,
    top10nl_path,
    main_route,
    tolerance=250.0,
)

Rebuild the Junctions of Basins along the Top10NL water lines and a main route, see rebuild_junction_trees.

This is used for the hws model and again after coupling, such that its Basins keep their routes. Its connector nodes are often outside the area of their Basin, so waterways up to tolerance around it are used.

split_distance

flow_paths.split_distance(geometry, point, margin=1.0)

The distance along geometry of the point nearest to point, at least margin from its ends if possible.