Development over time

fill_sequence(tstruct, weather_events, time_slack=0.0, infiltration=nothing, verbose=false)

Compute the sequence of events that describes how water on the terrain evolves over time.

For a given set of weather events, and a given terrain with associated trap structure, determine the sequence of events that describes how the flow and accumulation of water on the terrain changes over time.

Returns a Vector{SpillEvent} that expresses the discrete points in time when different traps fills/empties, and the resulting changes on the surface flow patterns.

Arguments

• tstruct::TrapStructure{Real}: trap structure object describing the terrain traps
• weather_events::Vector{WeatherEvent}: Vector of weather events describing changes in weather over time
• time_slack::Real: tolerance for when to merge events that are close to each other in time. Should be set to zero or a small number. @@ NB: Support for this currently unimplemented.
• infiltration::Union{Matrix{Real}, Nothing}: grid of same shape as the terrain, giving the infiltration rate at each gridcell.
• verbose::Bool: if true, dump progress information during computation

See also TrapStructure, WeatherEvent, SpillEvent

WeatherEvent

A struct representing a weather event, i.e. a change of weather.

Fields

• timestamp::Float64: Start time point of the weather event

• rain_rate::Union{Matrix{Float64}, Float64}: Rain rate set by the event. It can be given either as a single floating-point number that represents a uniform rate across the terrain, or a matrix of floating-point number for individual rain rates per grid cell.

The unit of rain rate is given in topographical grid height unit per time unit. E.g., if the topography is presented in a height unit of meters, and time is counted in hours, then the specified rate value will be interpreted as meters per hour.

See also fill_sequence, which takes a Vector{WeatherEvent} as one of its inputs.

Structure used when estimating when a SpillEvent will occur, i.e. when a given non-filled trap will completely fill up, or a given filled trap will start emptying.

The structure provides an upper and lower bound for when this event should happen.

Structure specifying that a trap will contain an amount volume of water at timepoint time.

Structure specifying an incremental update in the quantity of something. It is used in several different settings. It contain an index (to refer to a specific element to be updated) and a corresponding value (the value to update).

struct SpillEvent

A struct representing a "spill event", i.e. a moment in time when a trap changes its fill status. A trap can either transitory or filled, and the spill event refers to the moment in time when the trap passes from one to the other.

Fields

• timestamp::Float64: the time when the event occurs

• amount::Union{Vector{FilledAmount}, Vector{IncrementalUpdate{FilledAmount}}}: amount of water in the traps. Can be presented as a vector with one entry per trap, or as a vector of incremental updates to certain traps (as compared to the last registered SpillEvent).

• filled::Union{Vector{Bool}, Vector{IncrementalUpdate{Bool}}}: the traps that are filled when the event occurs. Can be presented as a vector with one (boolean) value per trap, or as an incremental update representing the change since last registered SpillEvent.

• inflow::Union{Vector{Float64}, Vector{IncrementalUpdate{Float64}}}: water inflow to each trap, presented either as a vector with the individual values of each and every trap, or as a set of incremental updates representing the change since the last registered SpillEvent. Inflow is a combination of direct presipitation, runoff from the trap's watershed or spillover from upstream overflowing traps.

• rain_rate::Union{Matrix{Float64}, Float64, Nothing}: if this event consisted of a weather change, it will be represented here, either as a single floating point value (considered constant over the grid), or as a grid with individual values for each cell.

• runoff::Union{Matrix{Float64}, Vector{IncrementalUpdate{Float64}}}: matrix keeping track of current overland flow and infiltration rate for each gridcell. Positive values represent overland flow, negative values infiltration. Can be presented either as a matrix with values for each and every grid cell, or as a set of incremental changes compared with last SpillEvent.

amount_at(seq, end_ix=-1)

Given a sequence of chronological SpillEvents seq, determine the FilledAmount for each trap at the end of the sequence (end_ix=-1), or at an earlier event (end_ix ∈ [1:length(seq)]).

This function computes its result by running through the sequence and accumulating differences until it has identified the correct entry for all traps.

Note that the returned FilledAmount for each trap does not necessarily correspond to the timestamp of the corresponding FillEvent, but may represent a value computed for an earlier point in time. The RateInfo for that trap should however have remained constant since the last time the value was computed, so it should be relatively straightforward to compute the present value if needed.

filled_at(seq, end_ix=-1)

Given a sequence of chronological SpillEvents seq, determine which traps are filled at the end of the sequence (end_ix=-1), or at an earlier event (end_ix ∈ [1:length(seq)]).

This function computes its result by running through the sequence and accumulating differences until it has identified the correct entry for all traps.

inflow_at(seq, end_ix=-1)

Given a sequence of chronological SpillEvents seq, determine the rate of water flowing into a trap (from its watershed, from upstream, or directly from precipitation) at the end of the sequence (end_ix=-1), or at an earlier event (end_ix ∈ [1:length(seq)]).

This function computes its result by running through the sequence and accumulating differences until it has identified the correct entry for all traps.

rainrate\_at(seq, end_ix=-1)

Given a sequence of chronological SpillEvents seq, determine the rain rate in effect at the end of the sequence (end_ix=-1), or at an earlier event (end_ix ∈ [1:length(seq)]).

This function computes its result by running through the sequence and identifying the latest rainrate that went into effect before the sequence entry specified by end_ix.

runoff_at(seq, end_ix=-1)

Given a sequence of chronological SpillEvents seq, determine the runoff across each point of the terrain (i.e. each gridcell) at the end of the sequence (end_ix=-1), or at an earlier event (end_ix ∈ [1:length(seq)]).

Positive values represent infiltration excess flow (runoff), whereas negative values represent remaining infiltration capacity.

This function computes its result by running through the sequence and accumulating differences until it has identified the correct entry for all traps.

mutable struct SpillGraph

A struct representing a tree-like spillgraph. It specifies how water flow from one (filled) trap to the next. When a trap is filled, it may spill into its downstream trap, or into its parent trap (depending on whether it shares a parent with its downstream trap, and the downstream trap is filled).

The spill graph is recorded as a set of edges, stored in the Dict edges, so that if trap 'i' spills into trap 'j', then edges[i] = k.

Default constructor for SpillGraph creates an empty spillgraph.

compute_complete_spillgraph(tstruct, full_traps)

Compute the complete spillgraph, given a trapping structure and a (sub)set of filled traps.

Returns an object of type SpillGraph.

The full_traps vector must be consistent, i.e. no filled trap can have non-filled subtraps.

Arguments

• tstruct::TrapStructure{T<:Real}: trapping structure
• full_traps::Vector{Bool}: a vector with one entry per trap, specifying if that trap has been completely filled or not.

See also TrapStructure, update_spillgraph!.

get_graph(spill_graph)

Converts the SpillGraph spill_graph into a Graphs.SimpleDiGraph from the Graphs package (https://juliagraphs.org).

update_spillgraph!(spillgraph, fill_changes, tstruct)

Update an existing spillgraph after there have been changes in which traps are filled or not.

The argument spillgraph will be modified.

Arguments

• spillgraph::SpillGraph: the spillgraph to be updated
• fill_changes::Vector{IncrementalUpdate{Bool}}: changes in the fill status of one or more traps, presented as a vector of incremental updates
• tstruct::TrapStructure{T<:Real}: the TrapStructure representing the trapping structure of the terrain the spill graph is associated with

See also IncrementalUpdate, SpillGraph and compute_complete_spillgraph.

RateInfo

A mutable struct representing rates of water (inflow, infiltration) associated with the terrain and its traps.

The fields of this struct should in general not be accessed directly, but through the set of associated methods, listed below.

Fields

• runoff::Matrix{Float64}: net overland flow or remaining infiltration capacity, one value per gridcell in the terrain grid.

• Smax::Vector{Float64}: maximum remaining infiltration within trap footprint, one value per trap.

• Smin::Vector{Float64}: minimum infiltration within trap footprint, one value per trap. (Only nonzero for traps with subtraps, and then equals the sum of Smax for its subtraps).

• trap_inflow::Vector{Float64}: total inflow to each trap.

• stored_runoff_values::Dict{Int,Float64}: if values have changed and save_active is set to true, this field stores the original runoff values for those that were later modified.

• stored_Smin_values::Dict{Int,Float64}: if values have changed and save_active is set to true, this field stores the original Sminvalues for those that were later modified.

• stored_Smax_values::Dict{Int,Float64}: if values have changed and save_active is set to true, this field stores the original Smax values for those that were later modified.

• stored_inflow_values::Dict{Int,Float64}: if values have changed and save_active is set to true, this field stores the original Smax values for those that were later modified.

• save_active::Bool: flag specifying if the initial state should be preseved.

Associated methods for access

• getrunoff
• getsmin
• getsmax
• getinflow
• setrunoff!
• setsmin!
• setsmax!
• setinflow!
• setsavepoint!
• disablesavepoint!
• getsavedrunoff
• getsavedsmin
• getsavedsmax
• getsavedinflow
• getrunoffupdates
• getinflowupdates

Constructor

RateInfo(runoff, Smax, Smin, trap_inflow)

Creates a new RateInfo object with the provided parameters.

A copy of a RateInfo object is always a deep copy.

Disable the current savepoint. Saved state will no longer be maintained.

Get the current inflow value for the trap with index 'ix'.

Get a vector with the inflow updates that have occured since the last savepoint was set.

Get the current runoff value for the gridcell with linear index 'ix'.

Get a vector with the runoff updates that have occured since last savepoint was set.

Get the saved inflow value for the trap with index 'ix'.

Get the saved runoff value for the gridcell with linear index 'ix'.

Get the saved Smax value for the trap with index 'ix'.

Get the saved Smin value for the trap with index 'ix'.

Get the current Smax value for the trap with index 'ix'.

Get the current Smin value for the trap with index 'ix'.

Set the current inflow value for the trap with index 'ix'.

Set the current runoff value for the gridcell with linear index 'ix'.

Set the savepoint here. (State at this point will be remembered, even in the face of later updates, until the savepoint is reset or disabled).

Set the current Smax value for the trap with index 'ix'.

Set the current Smin value for the trap with index 'ix'.

will modify rateinfo

compute_flow(spillgraph, precipitation, infiltration, tstruct, verbose=false)

For a given spillgraph, precipitation and infiltration rates, compute the runoff and trap inflows, in the form of a RateInfo object.

Arguments

• spillgraph::SpillGraph: the current spillgraph, i.e. a tree graph representing which traps spill into which
• precipitation::Union{Real, Matrix{<:Real}}: specifies the precipitation rate. Can be given either as a single scalar, or cell-wise in the form of a Matrix
• infiltration::Union{Real, Matrix{<:Real}}: specifies the infiltration rate. Can be given either as a single scalar, or cell-wise in the form of a Matrix
• tstruct::TrapStructure{<:Real}: object representing the trap sturcture
• verbose::Bool: if true, dump progress information during computation

See also SpillGraph, TrapStructure.