gwsource.transient#

Transient snapshots: trace selected time steps one by one and keep streaming statistics.

Each selected time step is treated as an independent steady state: storage release is a source
term and storage gain a sink term, as the budget file reports them. The grid and budget files
are opened once (mf6io.StepReader) and every step is read, traced and folded into running
statistics before the next is read, so memory does not grow with the number of steps (unless
keep_series=True).

Groups are re-selected on every step, because the term list (and the bound number of a named
boundary) can change between stress periods. Pass either a dict {group: select() keyword
arguments}, e.g. {"wel": {"package": "WEL"}, "east": {"boundnames": ["well_east"]}}, or a
function step -> {group: Selection}.

Statistics per group and per requested output, cell by cell (TransientConfig):
- min, max: over the steps.
- mean: weighted mean. weighting="time" (default) weights each step by its length DELT, so the
  mean is the time average over the analysed steps; weighting="equal" gives every step weight 1.
- asn: always / sometimes / never above the threshold: 1 if value > threshold in every step,
  0 if in none, 0.5 otherwise (on test_output).
- probability_in_range: weighted share of steps with low <= value <= high (on test_output),
  with the same weights as the mean.
- exceedance_count: number of steps with value > threshold (on test_output; not weighted).
NaN values (e.g. fraction_from_cell_input where a cell has no inflow term in a step) are left
out cell by cell: means and probabilities are then over the steps where the value is defined,
and a cell defined in no step gets NaN.

Travel time (optional): with TransientConfig.porosity set, every step also gets the Eulerian
mean travel time (backward) or mean age (forward) of gwsource.traveltime, computed on that
step's flows and water volume as a snapshot (as if the step's flow field were steady). Its
per-cell outputs ("mean_time", "weighted_time", and backward "mean_time_to_exit_cell") can then
be named in outputs like any other, and each group's mean transit time (sum V F / Q) is logged
per step in TransientResult.group_mean_transit_time.
class gwsource.transient.TransientConfig(steps='all', outputs=None, weighting='time', threshold=None, value_range=None, test_output=None, keep_series=False, porosity=None, fraction_threshold=1e-10)[source]#

Bases: object

Options of a transient (snapshot) run.

steps: "all", a list of 0-based stress periods (every saved step in them), or a list of
    0-based (kstp, kper) pairs.
outputs: per-group outputs to summarise (default fraction_through backward, source_fraction
    forward). Any per-cell output of BackwardResult/ForwardResult can be named.
weighting: "time" (default; weights = step length) or "equal" (weight 1 per step), used by
    the mean and probability_in_range.
threshold: threshold of asn and exceedance_count (value > threshold counts), or None.
value_range: (low, high) of probability_in_range (inclusive), or None.
test_output: output the threshold and range apply to (default: the first of outputs).
keep_series: also keep every step's outputs in memory (for export with a time dimension).
porosity: scalar or per-cell porosity; if set, travel times are computed on every step and
    their outputs ("mean_time", "weighted_time", "mean_time_to_exit_cell") can be named.
fraction_threshold: travel times are NaN where the fraction is at or below this.
Parameters:
class gwsource.transient.RunningStats(minimum, maximum, weighted_sum, weight_total, n_valid, n_exceed, weight_in_range)[source]#

Bases: object

Streaming accumulators of one output of one group (all arrays per cell).
Parameters:
class gwsource.transient.TransientResult(mode, config, trace_config, groups, outputs, test_output, steps, totim, weights, stats, group_inflow, solver_used, n_cycles, n_closed_loops, template, series=None, group_mean_transit_time=None, notes=<factory>)[source]#

Bases: object

Statistics over time steps: stats[statistic][output][group] -> per-cell array.

steps, totim and weights describe the analysed steps in order; group_inflow[group] holds,
per step, the group's destination inflow (backward) or source inflow (forward); in net
accounting that counts each passage into (out of) the group once (gwsource.metrics). series
(keep_series=True) holds series[output][group] -> (n_steps, n_cells).
Parameters:
gwsource.transient.select_steps(available, steps)[source]#
Return the saved (kstp, kper) to analyse: all, those in listed periods, or listed pairs.
Parameters:
Return type:

list[tuple[int, int]]

gwsource.transient.resolve_groups(step, spec)[source]#
Return the groups of one step from a dict of select() arguments or a function.
Parameters:
Return type:

dict[str, Selection]

gwsource.transient.new_stats(n)[source]#
Return empty accumulators for n cells.
Parameters:

n (int)

Return type:

RunningStats

gwsource.transient.update_stats(stats, values, weight, threshold, value_range)[source]#
Fold one step's per-cell values (NaN = undefined) into the accumulators.
Parameters:
Return type:

None

gwsource.transient.finish_stats(stats, threshold, value_range)[source]#
Return the statistics of one output and group from its accumulators.
Parameters:
Return type:

dict[str, ndarray]

gwsource.transient.step_weight(reader, kstpkper, weighting)[source]#
Return a step's weight: its length DELT (time weighting) or 1 (equal weighting).
Parameters:
Return type:

float

class gwsource.transient.StepLog(weights=<factory>, totim=<factory>, solvers=<factory>, n_cycles=<factory>, n_closed=<factory>, inflow=<factory>, transit=<factory>)[source]#

Bases: object

Per-step records of a transient run, in step order.
Parameters:
gwsource.transient.trace_transient(reader, groups, mode='backward', config=None, trace_config=None)[source]#
Trace every selected time step and return streaming statistics over the steps.
Parameters:
Return type:

TransientResult