duration is now mandatory in the meteo + Added runtime source resolution (explicit ModelSpec.timestep > non-default timespec > meteo base step)

Author: VEZY

docs/src/API/API_public.md

@@ -41,14 +41,21 @@ Period conversion detail:
   so execution times are `t = 1, 25, 49, ...`.
 
 Trait-based inference detail:
-- If `TimeStepModel(...)` is omitted, `timestep_hint(::Type{<:Model})` may provide:
-: fixed period (`Dates.Day(1)`) or required range (`(Dates.Minute(1), Dates.Hour(4))`).
+- If `TimeStepModel(...)` is omitted, runtime resolves timestep from:
+: `timespec(model)` when non-default, otherwise meteo `duration`.
+- `timestep_hint(::Type{<:Model})` is then interpreted as:
+: `required` = hard compatibility constraint, `preferred` = informational only.
 - If `InputBindings(...)` is omitted, same-name sources are inferred automatically from
 : unique producers (same scale first, then cross-scale). Ambiguous cases require explicit bindings.
 - If `MeteoBindings(...)` / `MeteoWindow(...)` are omitted, `meteo_hint(::Type{<:Model})`
 : may provide `(; bindings=..., window=...)`.
 - Explicit mapping-level configuration always overrides hints.
 
+Compatibility checks:
+- Meteo `duration` is mandatory when meteo is provided.
+- For models with meteo-derived timestep, runtime enforces `timestep_hint.required`.
+- `timestep_hint.preferred` never sets runtime timestep by itself.
+
 Scope selection detail:
 - `ScopeModel(:global)` is the default and shares streams across the whole simulation.
 - `ScopeModel(:plant)` isolates streams within each plant subtree.

docs/src/model_execution.md

@@ -20,21 +20,23 @@ For multiscale simulations, model usage is configured in the mapping through `Mo
 - `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.
 
-If users do not provide `TimeStepModel(...)`, `MeteoBindings(...)`, or `MeteoWindow(...)`,
+If users do not provide `MeteoBindings(...)` or `MeteoWindow(...)`,
 the runtime can infer defaults from model traits:
 - `timestep_hint(::Type{<:MyModel})`
 - `meteo_hint(::Type{<:MyModel})`
 
+For timestep specifically, runtime is meteo-first (see decision flow below): `timestep_hint`
+is used for compatibility validation (and user guidance), not to auto-assign model clocks.
+
 If users do not provide `InputBindings(...)`, runtime infers same-name bindings:
 - first from a unique producer at the same scale;
 - otherwise from a unique producer at another scale;
 - if no producer exists, input stays unresolved (so initialization/forced values can be used);
 - if multiple producers are possible, runtime errors and asks for explicit `InputBindings(...)`.
 
 For timestep hints:
-- `Dates.FixedPeriod` sets a fixed inferred timestep, e.g. `Dates.Day(1)`.
-- `(min_period, max_period)` sets a required range. For models with only range hints,
-  runtime computes a consensus (default: finest feasible period in the intersection).
+- `timestep_hint.required` is a hard compatibility constraint when runtime uses meteo-derived timestep.
+- `timestep_hint.preferred` is informational only (it does not set runtime timestep by itself).
 - Explicit `TimeStepModel(...)` always takes precedence.
 
 For meteo hints:
@@ -57,6 +59,33 @@ Policy parameterization:
 (for example `Dates.Hour(1)`, `Dates.Day(1)`). Fixed periods are converted internally using
 the meteo base timestep duration.
 
+### Timestep decision flow
+
+When meteo is provided, `duration` is mandatory for each row (or the simulation errors).
+
+Runtime picks each model effective clock with this order:
+
+1. If `ModelSpec` has `TimeStepModel(...)`, use it.
+2. Else if `timespec(model)` is non-default, use it.
+3. Else use meteo base timestep (`duration`) for that model.
+
+Then runtime applies constraints:
+
+1. If the model clock is meteo-derived (rule 3), `timestep_hint.required` is validated:
+   - fixed required period: meteo timestep must match exactly;
+   - required range: meteo timestep must be inside the range.
+2. `timestep_hint.preferred` never overrides the clock when timestep is unset.
+3. Meteo aggregation/integration is applied only when effective model timestep is coarser than meteo timestep.
+
+Practical consequences:
+
+- Unset `TimeStepModel` + required includes meteo + preferred is coarser:
+  model still runs at meteo timestep.
+- Explicit coarser `TimeStepModel(Dates.Hour(2))` with hourly meteo:
+  model runs every 2 hours and receives aggregated meteo over that window.
+- Unset `TimeStepModel` + required excludes meteo:
+  runtime errors with an actionable compatibility message.
+
 Developer note on period conversion:
 - Runtime time is indexed on a 1-based timeline (`t = 1, 2, 3, ...`).
 - `TimeStepModel(Dates.Day(1))` is converted to a clock step count using:

docs/src/multirate/multirate_tutorial.md

@@ -7,6 +7,107 @@ This tutorial builds one MTG simulation that mixes three model rates:
 
 It runs for one week and exports clean series at each rate.
 
+## Decision flow quick examples
+
+### Unset model timestep uses meteo cadence (preferred is informational)
+
+```@example multirate_timestep_flow
+using PlantSimEngine
+using PlantMeteo
+using MultiScaleTreeGraph
+using DataFrames
+using Dates
+
+mtg = Node(NodeMTG("/", "Scene", 1, 0))
+plant = Node(mtg, NodeMTG("+", "Plant", 1, 1))
+internode = Node(plant, NodeMTG("/", "Internode", 1, 2))
+Node(internode, NodeMTG("+", "Leaf", 1, 2))
+
+PlantSimEngine.@process "tutorialmeteodriven" verbose=false
+struct TutorialMeteoDrivenModel <: AbstractTutorialmeteodrivenModel
+    n::Base.RefValue{Int}
+end
+PlantSimEngine.inputs_(::TutorialMeteoDrivenModel) = NamedTuple()
+PlantSimEngine.outputs_(::TutorialMeteoDrivenModel) = (count=-Inf,)
+function PlantSimEngine.run!(m::TutorialMeteoDrivenModel, models, status, meteo, constants=nothing, extra=nothing)
+    m.n[] += 1
+    status.count = float(m.n[])
+end
+PlantSimEngine.timestep_hint(::Type{<:TutorialMeteoDrivenModel}) = (; required=(Minute(30), Hour(2)), preferred=Hour(1))
+
+mapping = ModelMapping("Leaf" => (ModelSpec(TutorialMeteoDrivenModel(Ref(0))),))
+meteo_30min = Weather([
+    Atmosphere(date=DateTime(2025, 6, 12, 12, 0, 0), duration=Minute(30), T=20.0, Wind=1.0, Rh=0.6),
+    Atmosphere(date=DateTime(2025, 6, 12, 12, 30, 0), duration=Minute(30), T=21.0, Wind=1.0, Rh=0.6),
+    Atmosphere(date=DateTime(2025, 6, 12, 13, 0, 0), duration=Minute(30), T=22.0, Wind=1.0, Rh=0.6),
+])
+
+out_meteo_driven = run!(
+    mtg,
+    mapping,
+    meteo_30min;
+    executor=SequentialEx(),
+    tracked_outputs=Dict("Leaf" => (:count,)),
+)
+out_meteo_driven_df = PlantSimEngine.convert_outputs(out_meteo_driven, DataFrame)
+out_meteo_driven_df["Leaf"][end, :count]
+```
+
+The last value is `3.0`, showing the model ran on all three 30-minute meteo rows, even though `preferred=Hour(1)`.
+
+### Explicit coarse `TimeStepModel` triggers integration/aggregation
+
+```@example multirate_timestep_flow
+PlantSimEngine.@process "tutorialhalfhoursource" verbose=false
+struct TutorialHalfHourSourceModel <: AbstractTutorialhalfhoursourceModel
+    n::Base.RefValue{Int}
+end
+PlantSimEngine.inputs_(::TutorialHalfHourSourceModel) = NamedTuple()
+PlantSimEngine.outputs_(::TutorialHalfHourSourceModel) = (A=-Inf,)
+function PlantSimEngine.run!(m::TutorialHalfHourSourceModel, models, status, meteo, constants=nothing, extra=nothing)
+    m.n[] += 1
+    status.A = 1.0 # umol m-2 s-1
+end
+
+PlantSimEngine.@process "tutorialhourlyintegrator" verbose=false
+struct TutorialHourlyIntegratorModel <: AbstractTutorialhourlyintegratorModel end
+PlantSimEngine.inputs_(::TutorialHourlyIntegratorModel) = (A=-Inf,)
+PlantSimEngine.outputs_(::TutorialHourlyIntegratorModel) = (A_hourly=-Inf, T_hourly=-Inf,)
+function PlantSimEngine.run!(::TutorialHourlyIntegratorModel, models, status, meteo, constants=nothing, extra=nothing)
+    status.A_hourly = status.A
+    status.T_hourly = meteo.T
+end
+
+mapping_coarse = ModelMapping(
+    "Leaf" => (
+        ModelSpec(TutorialHalfHourSourceModel(Ref(0))),
+        ModelSpec(TutorialHourlyIntegratorModel()) |>
+        TimeStepModel(Hour(1)) |>
+        InputBindings(; A=(process=:tutorialhalfhoursource, var=:A, policy=Integrate(vals -> sum(vals) * 1800.0))) |>
+        MeteoBindings(; T=MeanWeighted()),
+    ),
+)
+
+meteo_30min_4 = Weather([
+    Atmosphere(date=DateTime(2025, 6, 12, 12, 0, 0), duration=Minute(30), T=20.0, Wind=1.0, Rh=0.6),
+    Atmosphere(date=DateTime(2025, 6, 12, 12, 30, 0), duration=Minute(30), T=22.0, Wind=1.0, Rh=0.6),
+    Atmosphere(date=DateTime(2025, 6, 12, 13, 0, 0), duration=Minute(30), T=24.0, Wind=1.0, Rh=0.6),
+    Atmosphere(date=DateTime(2025, 6, 12, 13, 30, 0), duration=Minute(30), T=26.0, Wind=1.0, Rh=0.6),
+])
+
+out_coarse = run!(
+    mtg,
+    mapping_coarse,
+    meteo_30min_4;
+    executor=SequentialEx(),
+    tracked_outputs=Dict("Leaf" => (:A_hourly, :T_hourly)),
+)
+out_coarse_df = PlantSimEngine.convert_outputs(out_coarse, DataFrame)
+(out_coarse_df["Leaf"][end, :A_hourly], out_coarse_df["Leaf"][end, :T_hourly])
+```
+
+The final tuple is `(3600.0, 23.0)`: hourly integrated assimilation (`1.0 * 1800 s * 2`) and hourly mean temperature over the coarse window.
+
 ## 1. Setup and example data
 
 We reuse package example assets:
@@ -133,16 +234,9 @@ mapping = ModelMapping(
 
 ## 4. Run and export hourly/daily/weekly series
 
-Use `GraphSimulation` directly so weather sampling (`MeteoBindings`) is active on the `TimeStepTable` meteo input.
+Run directly from `mtg + mapping` and request exported series.
 
 ```@example multirate_tutorial
-sim = PlantSimEngine.GraphSimulation(
-    mtg,
-    mapping,
-    nsteps=PlantSimEngine.get_nsteps(meteo_hourly),
-    check=true,
-)
-
 req_leaf_hourly = OutputRequest("Leaf", :leaf_assim_h;
     name=:leaf_assim_hourly,
     process=leaf_proc,
@@ -171,7 +265,8 @@ req_plant_weekly = OutputRequest("Plant", :plant_assim_w;
 )
 
 out_status, exported = run!(
-    sim,
+    mtg,
+    mapping,
     meteo_hourly;
     multirate=true,
     executor=SequentialEx(),

docs/src/troubleshooting_and_testing/implicit_contracts.md

@@ -18,6 +18,27 @@ Many models are considered to be steady-state over that timeframe, but not all :
 !!! Note
     Implicitely, this means any vector variables given as input to the simulation must be consistent with the number of weather timesteps. Providing one weather value but a larger vector variable is an exception : the weather data is replicated over each timestep. (This may be subject to change in the future when support for different timesteps in a single simulation is implemented)
 
+## Why does my model skip half-hour rows?
+
+If your meteo has 30-minute rows but a model appears to run hourly, check timestep resolution order:
+
+1. If model has explicit `TimeStepModel(...)`, it is used.
+2. Else if model `timespec(model)` is non-default, it is used.
+3. Else model uses meteo `duration`.
+
+Then compatibility rules apply:
+
+1. `timestep_hint.required` is enforced for meteo-derived clocks.
+2. `timestep_hint.preferred` is informational only.
+3. Meteo aggregation/integration happens only for models with coarser effective clocks.
+
+Common cause:
+- model has explicit hourly `TimeStepModel(...)`, so 30-minute rows are intentionally aggregated to hourly runs.
+
+Quick diagnostics:
+- Run `explain_model_specs(mapping_or_sim)` to see, per process, whether runtime clock comes from explicit `ModelSpec`, model `timespec`, or meteo base step.
+- Ensure meteo `duration` is present and valid on every row (mandatory when meteo is provided).
+
 ## Weather data must be interpolated prior to simulation
 
 If your weather data isn't adjusted to conform to a regular timestep, you will need to adjust it to fit that constraint. PlantSimEngine does no interpolation prior to simulation and expects regular weather timesteps.
@@ -72,4 +93,4 @@ This order of simulation depends on the way the models link together. If you rep
 
 When iterating and slowly making a simulation more physiologically realistic and complex, it is therefore fully possible that the order in which two models are run is flipped by a user change. 
 
-This design choice implementation -a concession made for ease of use and flexibility when developing a simulation- means that until your set of models is fully stabilized and you know which variables are `PreviousTimestep` and what order models run in, as you expand and change the set you might see differences of execution of one timestep for some models. It isn't a conceptual problem as most models are steady-state, and simulation order is stable for a given set of models, but it does mean PlantSimEngine will be less conveient for some types of simulation.
+This design choice implementation -a concession made for ease of use and flexibility when developing a simulation- means that until your set of models is fully stabilized and you know which variables are `PreviousTimestep` and what order models run in, as you expand and change the set you might see differences of execution of one timestep for some models. It isn't a conceptual problem as most models are steady-state, and simulation order is stable for a given set of models, but it does mean PlantSimEngine will be less conveient for some types of simulation.