gwsource.metrics#

Result containers and the per-cell metrics derived from the solved fractions.

Backward (capture) outputs per destination group g:
- fraction_through F: fraction of the water passing through the cell that reaches g.
- volume_through: F x O (gross) or F x T (net), volume rate of that water [L3/T].
- flux_through: volume_through / cell plan area [L/T] (None without areas).
- volume_from: F x (source terms of the cell) (gross) or F x max(s, 0) (net): water that enters
  the model in this cell and reaches g [L3/T].
- volume_from_by_term: volume_from split by package (gross only): F x (that package's source
  flow in the cell), e.g. recharge, river leakage, storage release.
- fraction_from_cell_input: F on cells that have source terms (net mode: net source cells),
  NaN elsewhere: the fraction of the water entering the model in the cell that reaches g
  (2013 definition, Black & Foley 2013).
- fraction_from_total: volume_from / sum(volume_from): the cell's share of all model inflow that
  reaches g; sums to 1 (later definition, Black, Foley & Witterick 2021).
- flux_from: volume_from / cell plan area.
- destination_inflow: water entering the destination: sum of |q| of the group's sink terms
  (gross) or the water reaching the destination cells with each passage counted once (net):
  sum_D T_d - sum_{D->D} q - sum_{D->not D} q f_j, which equals the net volume from. For a single
  destination cell that no water leaves and reaches again it is that cell's throughflow T. In net
  accounting it depends on the solved fractions, not on the budget alone (gwsource.assemble).
- destination_throughflow (net only, empty in gross): sum of the destination cells' throughflow
  T. For a group of several cells it counts water passing between them more than once.
- absorbing: (cells, groups) mask of the strong-sink cells that absorb in each group's solve
  (TraceConfig.strong_sinks; net mode leaves out the group's own fixed cells), None without
  strong sinks. The closure check needs it (gwsource.diagnostics).

Forward (fate) outputs per source group g:
- source_fraction G: fraction of the water in the cell that came from g (dilution ratio C/C0).
- volume_through: G x I (gross) or G x T (net).
- volume_to: G x (sink terms of the cell) (gross) or G x max(-s, 0) (net).
- volume_to_by_term: volume_to split by package (gross only).
- source_inflow: sum of the group's source terms (gross) or the water leaving the source cells
  with each passage counted once (net): sum_S T_s - sum_{S->S} q - sum_{not S->S} q g_j, which
  equals the net volume to. For a single source cell that no water leaves and comes back to it is
  that cell's throughflow T. In net accounting it depends on the solved fractions.
- source_throughflow (net only, empty in gross): sum of the source cells' throughflow T. For a
  group of several cells it counts water passing between them more than once.

Gross results also keep the factorised system matrix (factor; not picklable) so that the travel
times of gwsource.traveltime reuse it.
class gwsource.metrics.BackwardResult(accounting, selections, fraction_through, volume_through, volume_from, volume_from_by_term, fraction_from_cell_input, fraction_from_total, flux_through, flux_from, destination_inflow, destination_throughflow=<factory>, solver_used=<factory>, cycles=<factory>, closed_loops=<factory>, factor=None, absorbing=None)[source]#

Bases: object

Per-group backward-tracing outputs; every array has one value per cell.
Parameters:
property groups: list[str]#
Group names.
class gwsource.metrics.ForwardResult(accounting, selections, source_fraction, volume_through, volume_to, volume_to_by_term, source_inflow, source_throughflow=<factory>, solver_used=<factory>, cycles=<factory>, closed_loops=<factory>, factor=None)[source]#

Bases: object

Per-group forward-tracing outputs; every array has one value per cell.
Parameters:
property groups: list[str]#
Group names.
gwsource.metrics.per_cell_by_package(step, sign)[source]#
Return {package name: per-cell |q| of its terms with the given sign}, if it has any.
Parameters:
Return type:

dict[str, ndarray]

gwsource.metrics.divide_by_area(values, area)[source]#
Return each array divided by the cell area, or None if there are no areas.
Parameters:
Return type:

dict | None

gwsource.metrics.share_of_total(values)[source]#
Return values / sum(values), or zeros if the sum is zero.
Parameters:

values (ndarray)

Return type:

ndarray

gwsource.metrics.backward_metrics(step, selections, fraction, through, source, source_by_package, destination_inflow, accounting)[source]#
Return backward outputs from fractions (cells, groups) and the per-cell flows they weight.

through and source may be (cells,) or (cells, groups) (net mode varies them by group).
Parameters:
Return type:

BackwardResult

gwsource.metrics.forward_metrics(step, selections, fraction, through, sink, sink_by_package, source_inflow, accounting)[source]#
Return forward outputs from fractions (cells, groups) and the per-cell flows they weight.
Parameters:
Return type:

ForwardResult