Chain multiple reservoir segments sequentially

ok_segment() links two reservoir segments in series, passing the outflow water quality of an upstream segment as the inflow to the next downstream segment. This reflects the longitudinal zonation common in Oklahoma reservoirs - riverine, transitional, and lacustrine segments each behave differently and should be modelled separately when data support it.

The function takes a completed upstream segment result (through at least ok_inlake()) and returns a new okBATHTUB object at the "load" step, pre-populated with the upstream outflow concentrations as the downstream inflow inputs. The downstream segment can then be run through the full pipeline normally.

Usage

ok_segment(
  upstream,
  segment_label = "downstream",
  coefficients = NULL,
  ecoregion = NULL
)

Arguments

upstream: An okBATHTUB object that has been run through at least ok_inlake(). The in-lake TP, TN, and inflow volume from this result become the downstream segment's inflow.
segment_label: Character. Label for the downstream segment. Default "downstream".
coefficients: Coefficient set for the downstream segment. Defaults to the same coefficient set used in the upstream segment. Can be overridden to apply different ecoregion coefficients to different segments.
ecoregion: Character. EPA Level III ecoregion for the downstream segment. If NULL, inherits from the upstream segment.

Value

An okBATHTUB object at pipeline step "load", ready to pipe into ok_hydraulics() for the downstream segment.

Mass balance at the segment boundary

The outflow TP concentration from the upstream segment becomes the inflow TP concentration for the downstream segment: $$C_{in,down} = C_{lake,up} = C_{in,up} \times (1 - R_{up})$$

Inflow volume is passed through unchanged under the steady-state assumption. If the downstream segment has a different surface area or morphometry, supply those via ok_hydraulics() after this call.

Examples

# Two-segment reservoir: riverine -> lacustrine
riverine <- ok_load(
  inflow_m3yr   = 45e6,
  tp_inflow_ugl = 150,
  tn_inflow_ugl = 2200,
  segment_label = "riverine"
) |>
ok_hydraulics(surface_area_ha = 280, mean_depth_m = 3.1) |>
ok_retention() |>
ok_inlake()

lacustrine <- ok_segment(riverine, segment_label = "lacustrine") |>
  ok_hydraulics(surface_area_ha = 610, mean_depth_m = 5.8) |>
  ok_retention() |>
  ok_inlake() |>
  ok_tsi()

summary(lacustrine)
#> ========================================
#>   okBATHTUB Water Quality Summary
#> ========================================
#> 
#>   Segment      : lacustrine
#>   Coefficients : walker
#>   Pipeline     : tsi
#> 
#>   -- Hydraulics --
#>   Inflow           : 4.500e+07 m3/yr
#>   Surface area     : 610.0 ha
#>   Mean depth       : 5.80 m
#>   Residence time   : 0.786 yr
#>   Areal water load : 7.38 m/yr
#> 
#>   -- Nutrient Retention --
#>   TP retention     : 0.577  (walker_model1)
#>   TN retention     : 0.519  (walker_model1)
#> 
#>   -- In-Lake Predictions --
#>   TP               : 28.6 ug/L
#>   TN               : 603.4 ug/L
#>   Chlorophyll-a    : 9.44 ug/L
#>   Secchi depth     : 1.43 m
#> 
#>   -- Carlson Trophic State Index --
#>   TSI(TP)          : 52.5
#>   TSI(Chl-a)       : 52.6
#>   TSI(Secchi)      : 54.9
#>   TSI(mean)        : 53.3  (n = 3 components)
#>   Trophic state    : Eutrophic
#> 
#> ========================================