Divergence aware accumulation.

[dblodgett-usgs]

There are three cases for divergence aware downstream accumulation.

Q. Is "apportion" the write word to use here? There are various usages in the wild that could be considered.

1. No apportionment: where upstream values are passed without being apportioned such that each downstream connection gets the full upstream value and there is special handling where diversions join back to the main flow to avoid double counting. -- this as also been referred to as "total upstream routing"
2. Divergence apportioned: Where upstream values are passed with fractional apportionment such that each downstream connection gets between 0 and 100 percent of the upstream value. This has also been referred to as "divergence routing"
3. Dendritic: Where upstream values are not passed to secondary paths at all -- this is essentially a special case of 2 where no diversion fraction value is provided and 0 is assumed for all divergences.

The accumulation function in hydroloom currently only supports dendritic accumulation and should support all three types.

The function signature: accumulate_downstream(x, var) could be maintained with an additional parameter apportion = NULL/{TRUE/FALSE}. If NULL, dendritic would be used. If TRUE, apportioned would be used. If FALSE, no apportionment would be used.

[dwief-usgs]

@dblodgett-usgs thanks for sharing this issue. A few comments and considerations below.

• Concept of the function/parameter makes sense and would be valuable
• I like that you reference other commonly used terms. I'd suggest expanding that list if your aware of other commonly used terms.
• I'm not strongly tied to any specific terminology but agree we should try to define and try being more consistent. Please share back what you end up with and I'll adopt moving forward.
• I am most familiar with the "also been referred to" terminology (e.g. divergence routing, total upstream routing). Is there reason to not use that? I have not heard apportion used in this context. Is apportion being used elsewhere, or are you looking to create a more descriptive term?
• Your likely already planning on it but it may be helpful to add these to the readme terminology section?