Make difference between Integrate and Aggregate more clear

Author: VEZY

docs/src/API/API_public.md

@@ -108,6 +108,8 @@ MeteoBindings(
 ### Parameterized window reducers
 
 `Integrate()` defaults to `SumReducer()`; `Aggregate()` defaults to `MeanReducer()`.
+With the same reducer, they are runtime-equivalent.
+Use `Integrate` for accumulation semantics and `Aggregate` for summary-statistics semantics.
 
 ```julia
 ModelSpec(DailyModel()) |>

docs/src/model_execution.md

@@ -50,6 +50,8 @@ Inspection helpers:
 Policy parameterization:
 - `Integrate()` defaults to `SumReducer()`; you can pass another reducer, e.g. `Integrate(MeanReducer())` or `Integrate(vals -> maximum(vals) - minimum(vals))`.
 - `Aggregate()` defaults to `MeanReducer()`; you can pass reducers such as `Aggregate(MaxReducer())`.
+- Difference between `Integrate` and `Aggregate`: with the same reducer they are runtime-equivalent.
+  In practice, only defaults and naming intent differ (`Integrate` for accumulation, `Aggregate` for summary statistics).
 - `Interpolate()` defaults to `mode=:linear, extrapolation=:linear`; use `Interpolate(; mode=:hold, extrapolation=:hold)` for hold behavior.
 - The same reducer objects are reused by meteo sampling (`MeteoBindings`) and by windowed policies (`Integrate`, `Aggregate`).
 

src/time/multirate.jl

@@ -98,6 +98,12 @@ Interpolate(; mode::Symbol=:linear, extrapolation::Symbol=:linear) = Interpolate
 Windowed policy for consumers running at coarser clocks.
 Values in the consumer window are reduced with `reducer`.
 
+Intended meaning: integrate/accumulate quantities over a window (for example
+hourly flux to daily total). Default reducer is `SumReducer()`.
+
+Important: `Integrate(r)` and `Aggregate(r)` are runtime-equivalent when they
+use the same reducer `r`; they only differ by default reducer and naming intent.
+
 Built-in reducers can be shared with meteo sampling from `PlantMeteo`:
 `SumReducer()`, `MeanReducer()`, `MaxReducer()`, `MinReducer()`, `FirstReducer()`,
 `LastReducer()`.
@@ -118,6 +124,12 @@ end
 Windowed aggregation policy for consumers running at coarser clocks.
 Values in the consumer window are reduced with `reducer`.
 
+Intended meaning: summarize window values as a statistic (for example mean/max).
+Default reducer is `MeanReducer()`.
+
+Important: `Aggregate(r)` and `Integrate(r)` are runtime-equivalent when they
+use the same reducer `r`; they only differ by default reducer and naming intent.
+
 Built-in reducers can be shared with meteo sampling from `PlantMeteo`:
 `SumReducer()`, `MeanReducer()`, `MaxReducer()`, `MinReducer()`, `FirstReducer()`,
 `LastReducer()`.

src/time/runtime/output_export.jl

@@ -19,6 +19,8 @@ resampled temporal streams while simulation is running.
 - `policy::SchedulePolicy=HoldLast()`: resampling policy applied at export time.
   Common values are `HoldLast()`, `Integrate(...)`, `Aggregate(...)`,
   `Interpolate(...)`.
+  `Integrate` and `Aggregate` are runtime-equivalent with the same reducer;
+  they differ by default reducer (`SumReducer` vs `MeanReducer`) and intent.
 - `clock=nothing`: export clock. When `nothing`, export is evaluated at each
   simulation step (`ClockSpec(1.0, 0.0)`). Accepted explicit values are the same
   as model timestep specs (`Real`, `ClockSpec`, or fixed `Dates.Period`).

test/test-multirate-scaffolding.jl

@@ -58,4 +58,14 @@ using Test
     ts.caches[key] = HoldLastCache(1.0, 42.0)
     @test ts.caches[key] isa HoldLastCache
     @test ts.caches[key].v == 42.0
+
+    vals = [1.0, 2.0, 3.0]
+    @test Integrate().reducer isa SumReducer
+    @test Aggregate().reducer isa MeanReducer
+    @test PlantSimEngine._window_reduce(vals, Integrate()) == 6.0
+    @test PlantSimEngine._window_reduce(vals, Aggregate()) == 2.0
+    @test PlantSimEngine._window_reduce(vals, Integrate(MeanReducer())) ==
+          PlantSimEngine._window_reduce(vals, Aggregate(MeanReducer()))
+    @test PlantSimEngine._window_reduce(vals, Integrate(SumReducer())) ==
+          PlantSimEngine._window_reduce(vals, Aggregate(SumReducer()))
 end