Network

Parameters:

Build a Network from the network_file of a Configs object, its k and x routed exactly as given.

Check that k and x are in expected, valid ranges. np.isfinite checks for NaN and inf

The blocks of rivers each job routes, packed for threads jobs by streams.assign_blocks. They are derived once per thread count and cached, so repeated simulations over this network never rebuild them.

Each block is a contiguous range of rows read from the upstreamCount column, so nothing is reordered: the forcing, the state, and the routed discharge stay in network file order from end to end. The best blocks depend on the thread count, so they are rebuilt for each one. On one thread, the main stem is the whole region.

Parameters:

Returns:

The inclusive range of routing time steps over which every Muskingum coefficient of each river is non-negative, (2*k*x, 2*k*(1-x)), the steps at which its routing is valid. Outside it the scheme is still stable and conserves mass, but its discharge can go negative.

Per-river masks of the two ways a river's coefficients go negative at dt, one step for every river or one per river, for the whole river or, with layout, for any of its sub-reaches at its own step, dt over its subcycles.

Returns:

The equal sub-reaches of each river at dt, one step for every river or one per river: the fewest sub-reaches, laid out as conditioning lays out equal ones, whose coefficients are all non-negative at dt, which is what use_subreaches routes for rivers too long for their step. An equal sub-reach of travel time k/N has a non-negative c1 when k/N <= dt + (1-2x)*k, and a sub-reach whose x is 0 has one at any step, so the count is ceil(k / (dt + (1-2x)*k)): 2 for every river too long at x = 0.2, and never more than ceil(1/(1-2x)). No split into fewer sub-reaches of any travel times is valid at dt.

The shortest sub-reach has a non-negative c3 when dt <= 2*k_N*(1 - x_N). A river too short for dt cannot meet it, since its sub-reaches are shorter still, and for x <= 3/8 every river too long for dt does. A river whose sub-reaches do not is kept as one reach and reported as unresolvable, and conditioning splits it into unequal sub-reaches that take subcycles of their own instead, where it uses subcycles too.

Returns:

The subcycles of each river at dt, one step for every river or one per river: the fewest equal steps a river is routed in within each step of dt, overriding dt with the shorter routing step dt / subcycles of its own. Configs(dt_routing='auto') identifies each river's own valid step with them, dt_runoff / subcycles, and use_subcycles gives them to rivers too short for a dt_routing in seconds. The count is ceil(dt/(2*k*(1-x))): the smallest that brings the river's own step under the upper bound 2*k*(1-x). A river that is not too short takes 1.

Its own step can also fall under the lower bound 2*k*x, when the window is narrower than one whole count of subcycles; such a river keeps one step and is reported as unresolvable. For x <= 1/3 the window always holds one.

Returns:

How each river is routed at dt, one step for every river or one per river, as the use_subreaches and use_subcycles of a Configs route it: a river too long for dt is split into its equal sub_reaches with use_subreaches, and a river too short for it is routed in its subcycles, equal steps of its own, with use_subcycles. Without them a river is routed whole at dt. With both, a river neither makes valid, which only a river with x > 1/3 can be, is split into the fewest sub-reaches of unequal travel times that each take subcycles of their own and keep the river's diffusion, those of splitting.fewest_sub_reaches, and is kept whole if no split into at most the 256 sub-reaches the kernels route one river as is valid. stabilize writes this layout as rows.

Returns:

Raise ValueError unless the routing kernels can route this network as sub_reaches sub-reaches per river, as from conditioning: no more rivers, sub-reaches, sub-reaches of one river, or inflow rivers of one river than river_route/kernels/c/checks.c allows. Routing checks it before any runoff is read, so a network the kernels would refuse is refused while it is prepared, with the river that breaks the limit named. A river with an x near 1/2 is split into the most sub-reaches; see the routing algorithm docs for holding x lower.

Parameters:

Report rivers with a negative Muskingum coefficient at dt and take the configured action. With layout a river is checked as its sub-reaches, each at its own step.

Every coefficient is non-negative when 2*k*x <= dt <= 2*k*(1-x). Outside that window the scheme is still stable and still conserves mass, since c1+c2+c3 == 1 holds for negative coefficients too, but its discharge can dip below zero ahead of a rise (c1 < 0) or alternate from step to step and go negative (c3 < 0). The kernels write negative discharge as routed.

Parameters:

Raise ValueError for rivers with an x above MAX_STABILIZED_X, which routing with use_subreaches or use_subcycles, and stabilize, refuse. A river needs up to ceil(1/(1-2x)) sub-reaches, 50 at x = 0.49, and many more above it, and at x = 1/2 its coefficients are all non-negative only at a step equal to its travel time, so that it can be impossible to stabilize.

Stabilize this network in place: every river that conditioning splits at dt is replaced by its sub-reaches in series, whose coefficients are all non-negative at dt or in the subcycles of it each takes, which routing with use_subcycles gives each row. The original river keeps its id and becomes the outlet sub-reach, and the added sub-reaches are injected directly upstream of it with synthetic True and ids counting down from -1,000,000. Deleting the synthetic rows gives back the original row order. A network is stabilized once: to stabilize it at another dt, build a new Network from the original network file.

The sub-reaches are those of conditioning, which is what use_subreaches and use_subcycles route inside the kernel, so they keep each river's mean travel time k and its travel time variance k**2 * (1 - 2x). A river they cannot make non-negative is kept whole. Rivers left with a negative coefficient are not reported here: invalid_mask finds them, and routing reports them as invalid_coefficients says.

Parameters:

Returns:

Raises:

Stabilize this network for dt and write it as a network table with the synthetic column.

Parameters:

Returns:

Write the network table, with every column in its dtype of NETWORK_DTYPES, to a parquet file.

Parameters:

Returns: