Add a way to tell that meteo window is using past window (rolling window) or calendar (possibly using values future to the current step)

Author: VEZY

docs/src/API/API_public.md

@@ -21,6 +21,7 @@ For mapping-level multi-rate configuration, combine:
 - `TimeStepModel(...)`
 - `InputBindings(...)`
 - `MeteoBindings(...)`
+- `MeteoWindow(...)`
 - `OutputRouting(...)`
 - `ScopeModel(...)`
 - `OutputRequest(...)` in `tracked_outputs` for resampled exports
@@ -76,13 +77,22 @@ InputBindings(; x=(process=:producer, var=:x))
 ```julia
 ModelSpec(DailyModel()) |>
 TimeStepModel(ClockSpec(24.0, 1.0)) |>
+MeteoWindow(CalendarWindow(:day; anchor=:current_period, week_start=1, completeness=:strict)) |>
 MeteoBindings(
     T=MeanWeighted(),                     # default source is :T
     Ri_SW_f=RadiationEnergy(),            # integrate W m-2 to MJ m-2 over the model window
     custom_peak=(source=:custom_var, reducer=MaxReducer()),
 )
 ```
 
+`MeteoWindow(...)` options:
+- `RollingWindow()` (default): trailing rolling window driven by `dt`.
+- `CalendarWindow(period; anchor, week_start, completeness)` with:
+: `period` in `:day`, `:week`, `:month`
+: `anchor` in `:current_period`, `:previous_complete_period`
+: `week_start` in `1:7` (1 = Monday)
+: `completeness` in `:allow_partial`, `:strict`
+
 ### Parameterized window reducers
 
 `Integrate()` defaults to `SumReducer()`; `Aggregate()` defaults to `MeanReducer()`.

docs/src/model_execution.md

@@ -16,6 +16,7 @@ For multiscale simulations, model usage is configured in the mapping through `Mo
 - `TimeStepModel(...)`: sets model execution clock.
 - `InputBindings(...)`: sets producer, source variable, optional source scale, and policy for each consumer input.
 - `MeteoBindings(...)`: sets weather aggregation rules at the model clock for meteo variables.
+- `MeteoWindow(...)`: sets weather row selection strategy (`RollingWindow()` or `CalendarWindow(...)`).
 - `OutputRouting(...)`: sets whether an output is canonical (`:canonical`) or stream-only (`:stream_only`).
 - `ScopeModel(...)`: partitions producer streams by scope (`:global`, `:plant`, `:scene`, `:self`) for multi-entity simulations.
 
@@ -43,11 +44,25 @@ Typical pipeline form:
 ```julia
 ModelSpec(MyModel()) |>
 TimeStepModel(ClockSpec(24.0, 1.0)) |>
+MeteoWindow(CalendarWindow(:day; anchor=:current_period, week_start=1, completeness=:strict)) |>
 MeteoBindings(; T=MeanWeighted()) |>
 InputBindings(; x=(process=:producer, var=:y, policy=HoldLast())) |>
 OutputRouting(; z=:stream_only)
 ```
 
+### Calendar-aligned meteo windows
+
+`MeteoWindow(...)` controls how rows are selected before reducers are applied:
+- `RollingWindow()` (default): trailing window based on `dt` (for example "last 24 steps").
+- `CalendarWindow(period; anchor, week_start, completeness)`:
+: `period` in `:day`, `:week`, `:month`
+: `anchor` in `:current_period`, `:previous_complete_period`
+: `week_start` in `1:7` (1 = Monday)
+: `completeness` in `:allow_partial`, `:strict`
+
+`CalendarWindow(:day; anchor=:current_period, ...)` guarantees that a model running inside a day sees
+aggregates over that civil day (including later timesteps from that day when available).
+
 ### Hold-last coupling (default policy)
 
 ```julia

src/PlantSimEngine.jl

@@ -123,15 +123,15 @@ export AbstractTimeReducer, MeanWeighted, MeanReducer, SumReducer, MinReducer, M
 export OutputCache, HoldLastCache, InterpolateCache, IntegrateCache, AggregateCache
 export TemporalState
 export OutputRequest, collect_outputs
-export ModelList, MultiScaleModel, ModelSpec, TimeStepModel, InputBindings, MeteoBindings, OutputRouting, ScopeModel
+export ModelList, MultiScaleModel, ModelSpec, TimeStepModel, InputBindings, MeteoBindings, MeteoWindow, OutputRouting, ScopeModel
 export RMSE, NRMSE, EF, dr
 export Status, TimeStepTable, status
 export init_status!
 export add_organ!
 export @process, process
 export to_initialize, is_initialized, init_variables, dep
 export inputs, outputs, variables, convert_outputs
-export timespec, output_policy, input_bindings, meteo_bindings, output_routing, model_scope
+export timespec, output_policy, input_bindings, meteo_bindings, meteo_window, output_routing, model_scope
 export run!
 export fit
 

src/mtg/ModelSpec.jl

@@ -1,18 +1,19 @@
 """
-    ModelSpec(model; multiscale=nothing, timestep=nothing, input_bindings=NamedTuple(), meteo_bindings=NamedTuple(), output_routing=NamedTuple(), scope=:global)
+    ModelSpec(model; multiscale=nothing, timestep=nothing, input_bindings=NamedTuple(), meteo_bindings=NamedTuple(), meteo_window=nothing, output_routing=NamedTuple(), scope=:global)
 
 User-side model configuration wrapper for mapping/model list composition.
 
 `ModelSpec` keeps model implementation and scenario-specific usage metadata in one place.
 This allows modelers to publish reusable models while users decide how models are coupled in
 their simulation setup.
 """
-struct ModelSpec{M,MS,TS,IB,MB,OR,SC}
+struct ModelSpec{M,MS,TS,IB,MB,MW,OR,SC}
     model::M
     multiscale::MS
     timestep::TS
     input_bindings::IB
     meteo_bindings::MB
+    meteo_window::MW
     output_routing::OR
     scope::SC
 end
@@ -29,6 +30,7 @@ function ModelSpec(
     timestep=nothing,
     input_bindings=NamedTuple(),
     meteo_bindings=NamedTuple(),
+    meteo_window=nothing,
     output_routing=NamedTuple(),
     scope=:global
 )
@@ -43,14 +45,16 @@ function ModelSpec(
     normalized_multiscale = _normalize_multiscale_mapping(base_model, base_multiscale)
     normalized_input_bindings = _normalize_input_bindings(input_bindings)
     normalized_meteo_bindings = _normalize_meteo_bindings(meteo_bindings)
+    normalized_meteo_window = _normalize_meteo_window(meteo_window)
     normalized_output_routing = _normalize_output_routing(output_routing)
     normalized_scope = _normalize_scope_selector(scope)
-    return ModelSpec{typeof(base_model),typeof(normalized_multiscale),typeof(timestep),typeof(normalized_input_bindings),typeof(normalized_meteo_bindings),typeof(normalized_output_routing),typeof(normalized_scope)}(
+    return ModelSpec{typeof(base_model),typeof(normalized_multiscale),typeof(timestep),typeof(normalized_input_bindings),typeof(normalized_meteo_bindings),typeof(normalized_meteo_window),typeof(normalized_output_routing),typeof(normalized_scope)}(
         base_model,
         normalized_multiscale,
         timestep,
         normalized_input_bindings,
         normalized_meteo_bindings,
+        normalized_meteo_window,
         normalized_output_routing,
         normalized_scope
     )
@@ -63,10 +67,11 @@ function ModelSpec(
     timestep=spec.timestep,
     input_bindings=spec.input_bindings,
     meteo_bindings=spec.meteo_bindings,
+    meteo_window=spec.meteo_window,
     output_routing=spec.output_routing,
     scope=spec.scope
 )
-    ModelSpec(model; multiscale=multiscale, timestep=timestep, input_bindings=input_bindings, meteo_bindings=meteo_bindings, output_routing=output_routing, scope=scope)
+    ModelSpec(model; multiscale=multiscale, timestep=timestep, input_bindings=input_bindings, meteo_bindings=meteo_bindings, meteo_window=meteo_window, output_routing=output_routing, scope=scope)
 end
 
 as_model_spec(spec::ModelSpec) = spec
@@ -113,6 +118,16 @@ function with_meteo_bindings(model_or_spec, bindings)
     return ModelSpec(spec; meteo_bindings=_normalize_meteo_bindings(bindings))
 end
 
+"""
+    with_meteo_window(model_or_spec, window)
+
+Return a `ModelSpec` with explicit weather-window selection strategy.
+"""
+function with_meteo_window(model_or_spec, window)
+    spec = as_model_spec(model_or_spec)
+    return ModelSpec(spec; meteo_window=_normalize_meteo_window(window))
+end
+
 """
     with_output_routing(model_or_spec, routing)
 
@@ -184,6 +199,25 @@ end
 
 _normalize_meteo_bindings(bindings) = bindings
 
+function _normalize_meteo_window(window)
+    if isnothing(window)
+        return nothing
+    elseif window isa DataType
+        window <: PlantMeteo.AbstractSamplingWindow || error(
+            "Unsupported MeteoWindow type `$(window)`. ",
+            "Use a PlantMeteo sampling-window type/instance."
+        )
+        return window()
+    elseif window isa PlantMeteo.AbstractSamplingWindow
+        return window
+    end
+
+    error(
+        "Unsupported MeteoWindow value `$(window)` of type `$(typeof(window))`. ",
+        "Use a PlantMeteo sampling-window type/instance."
+    )
+end
+
 function _normalize_output_routing(routing::NamedTuple)
     normalized = Pair{Symbol,Symbol}[]
     for (k, v) in pairs(routing)
@@ -243,6 +277,14 @@ Each value can be:
 MeteoBindings(bindings) = x -> with_meteo_bindings(x, bindings)
 MeteoBindings(; kwargs...) = MeteoBindings((; kwargs...))
 
+"""
+    MeteoWindow(window)
+
+Pipe-style transform that sets the weather window-selection strategy on a model/spec.
+Use `PlantMeteo.RollingWindow()` (default) or `PlantMeteo.CalendarWindow(...)`.
+"""
+MeteoWindow(window) = x -> with_meteo_window(x, window)
+
 """
     OutputRouting(routing)
     OutputRouting(; kwargs...)

src/mtg/model_spec_validation.jl

@@ -1,6 +1,9 @@
 const _INPUT_BINDING_FIELDS = (:process, :var, :scale, :policy)
 const _MODEL_SCOPE_SELECTORS = (:global, :plant, :scene, :self)
 const _METEO_BINDING_FIELDS = (:source, :reducer)
+const _CALENDAR_PERIODS = (:day, :week, :month)
+const _CALENDAR_ANCHORS = (:current_period, :previous_complete_period)
+const _CALENDAR_COMPLETENESS = (:allow_partial, :strict)
 
 function _validate_window_reducer(scale::String, process::Symbol, input_var::Symbol, policy_name::Symbol, reducer)
     if reducer isa DataType
@@ -375,6 +378,36 @@ function _validate_meteo_bindings_for_spec(scale::String, process::Symbol, spec:
     return nothing
 end
 
+function _validate_meteo_window_for_spec(scale::String, process::Symbol, spec::ModelSpec)
+    window = meteo_window(spec)
+    isnothing(window) && return nothing
+
+    window isa PlantMeteo.AbstractSamplingWindow || error(
+        "MeteoWindow for process `$(process)` at scale `$(scale)` must be a PlantMeteo sampling-window instance, got `$(typeof(window))`."
+    )
+
+    if window isa PlantMeteo.CalendarWindow
+        window.period in _CALENDAR_PERIODS || error(
+            "Invalid CalendarWindow period `$(window.period)` for process `$(process)` at scale `$(scale)`. ",
+            "Allowed values are $(_CALENDAR_PERIODS)."
+        )
+        window.anchor in _CALENDAR_ANCHORS || error(
+            "Invalid CalendarWindow anchor `$(window.anchor)` for process `$(process)` at scale `$(scale)`. ",
+            "Allowed values are $(_CALENDAR_ANCHORS)."
+        )
+        1 <= window.week_start <= 7 || error(
+            "Invalid CalendarWindow week_start `$(window.week_start)` for process `$(process)` at scale `$(scale)`. ",
+            "Allowed values are integers in 1:7."
+        )
+        window.completeness in _CALENDAR_COMPLETENESS || error(
+            "Invalid CalendarWindow completeness `$(window.completeness)` for process `$(process)` at scale `$(scale)`. ",
+            "Allowed values are $(_CALENDAR_COMPLETENESS)."
+        )
+    end
+
+    return nothing
+end
+
 """
     validate_model_specs_configuration(model_specs)
 
@@ -393,6 +426,7 @@ function validate_model_specs_configuration(model_specs)
             _validate_scope_spec(scale, process, spec)
             _validate_input_bindings_for_spec(scale, process, spec, model_specs, known_processes)
             _validate_meteo_bindings_for_spec(scale, process, spec)
+            _validate_meteo_window_for_spec(scale, process, spec)
             _validate_output_routing_for_spec(scale, process, spec)
         end
     end

src/processes/models_inputs_outputs.jl

@@ -110,6 +110,14 @@ Each value can be:
 """
 meteo_bindings(spec::ModelSpec) = spec.meteo_bindings
 
+"""
+    meteo_window(spec::ModelSpec)
+
+Optional weather window-selection strategy used by multi-rate MTG runtime.
+Defaults to `nothing` (runtime falls back to `PlantMeteo.RollingWindow()` behavior).
+"""
+meteo_window(spec::ModelSpec) = spec.meteo_window
+
 """
     inputs(mapping::Dict{String,T})
 

src/time/runtime/meteo_sampling.jl

@@ -10,7 +10,32 @@ function _prepare_meteo_sampler(meteo)
     return PlantMeteo.prepare_weather_sampler(meteo)
 end
 
-_meteo_sampling_spec(clock::ClockSpec) = PlantMeteo.MeteoSamplingSpec(float(clock.dt), float(clock.phase))
+function _runtime_meteo_window(window)
+    if isnothing(window)
+        return nothing
+    elseif window isa PlantMeteo.AbstractSamplingWindow
+        return window
+    elseif window isa DataType
+        window <: PlantMeteo.AbstractSamplingWindow || error(
+            "Unsupported MeteoWindow type `$(window)`. ",
+            "Use a PlantMeteo sampling-window type/instance."
+        )
+        return window()
+    end
+
+    error(
+        "Unsupported MeteoWindow value `$(window)` of type `$(typeof(window))`. ",
+        "Use a PlantMeteo sampling-window type/instance."
+    )
+end
+
+function _meteo_sampling_spec(clock::ClockSpec, model_spec)
+    window = _runtime_meteo_window(meteo_window(model_spec))
+    if isnothing(window)
+        return PlantMeteo.MeteoSamplingSpec(float(clock.dt), float(clock.phase))
+    end
+    return PlantMeteo.MeteoSamplingSpec(float(clock.dt), float(clock.phase); window=window)
+end
 
 function _normalize_meteo_reducer(reducer)
     if reducer isa DataType
@@ -67,22 +92,25 @@ function _sample_meteo_for_model(
     model_spec
 )
     transforms = _meteo_transforms_for_model(model_spec)
+    window = _runtime_meteo_window(meteo_window(model_spec))
 
     isnothing(meteo_sampler) && begin
-        if !isnothing(transforms)
+        if !isnothing(transforms) || !isnothing(window)
             @warn string(
-                "MeteoBindings were provided but weather sampler API is unavailable or meteo is not TimeStepTable{Atmosphere}. ",
+                "MeteoBindings or MeteoWindow were provided but weather sampler API is unavailable or meteo is not TimeStepTable{Atmosphere}. ",
                 "Falling back to raw meteo rows."
             ) maxlog = 1
         end
         return meteo
     end
 
     # Fast-path: default 1:1 weather step with no custom transforms.
-    if float(model_clock.dt) <= 1.0 && isnothing(transforms)
+    if float(model_clock.dt) <= 1.0 &&
+       isnothing(transforms) &&
+       (isnothing(window) || window isa PlantMeteo.RollingWindow)
         return meteo
     end
 
-    spec = _meteo_sampling_spec(model_clock)
+    spec = _meteo_sampling_spec(model_clock, model_spec)
     return PlantMeteo.sample_weather(meteo_sampler, i; spec=spec, transforms=transforms)
 end