Add PlantSimEngine.output_policy trait

Author: VEZY

docs/make.jl

@@ -42,6 +42,7 @@ makedocs(;
             "Implementing a model : additional notes" => "./step_by_step/implement_a_model_additional.md",
         ],
         "Execution" => "model_execution.md",
+        "Model traits" => "model_traits.md",
         "Working with data" => [
             "Reducing DoF" => "./working_with_data/reducing_dof.md",
             "Fitting" => "./working_with_data/fitting.md",

docs/src/API/API_public.md

@@ -24,6 +24,8 @@ For mapping-level multi-rate configuration, combine:
 - `MeteoWindow(...)`
 - `OutputRouting(...)`
 - `ScopeModel(...)`
+- `timespec(::Type{<:AbstractModel})` (optional trait)
+- `output_policy(::Type{<:AbstractModel})` (optional trait)
 - `timestep_hint(::Type{<:AbstractModel})` (optional trait)
 - `meteo_hint(::Type{<:AbstractModel})` (optional trait)
 - `resolved_model_specs(mapping)` (utility)
@@ -47,6 +49,8 @@ Trait-based inference detail:
 : `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.
+- For inferred bindings, policy defaults to producer `output_policy` when defined, otherwise `HoldLast()`.
+- Explicit `InputBindings(..., policy=...)` always overrides trait defaults.
 - If `MeteoBindings(...)` / `MeteoWindow(...)` are omitted, `meteo_hint(::Type{<:Model})`
 : may provide `(; bindings=..., window=...)`.
 - Explicit mapping-level configuration always overrides hints.

docs/src/model_execution.md

@@ -20,8 +20,12 @@ 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.
 
+For a compact overview of all model traits and precedence rules, see [Model traits](model_traits.md).
+
 If users do not provide `MeteoBindings(...)` or `MeteoWindow(...)`,
 the runtime can infer defaults from model traits:
+- `timespec(::Type{<:MyModel})`
+- `output_policy(::Type{<:MyModel})`
 - `timestep_hint(::Type{<:MyModel})`
 - `meteo_hint(::Type{<:MyModel})`
 
@@ -34,6 +38,12 @@ If users do not provide `InputBindings(...)`, runtime infers same-name bindings:
 - 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 inferred bindings, default policy is resolved as:
+- producer `output_policy` for the source output when defined;
+- otherwise `HoldLast()`.
+
+Explicit mapping policies still have priority (`InputBindings(..., policy=...)`).
+
 For timestep hints:
 - `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).

docs/src/model_traits.md

@@ -0,0 +1,141 @@
+# Model traits
+
+This page centralizes the model-level traits that can be defined in `PlantSimEngine`.
+It complements:
+
+- [Model execution](model_execution.md) for runtime behavior,
+- [Parallelization](step_by_step/parallelization.md) for execution over objects/time-steps.
+
+## Trait inventory for models
+
+### `timespec(::Type{<:MyModel})`
+
+Defines the default execution clock of a model.
+
+Default:
+
+```julia
+PlantSimEngine.timespec(::Type{<:AbstractModel}) = ClockSpec(1.0, 0.0)
+```
+
+Use it when your model has a natural native clock (for example daily by default).
+
+### `output_policy(::Type{<:MyModel})`
+
+Defines per-output default schedule policy for produced streams.
+
+Default:
+
+```julia
+PlantSimEngine.output_policy(::Type{<:AbstractModel}) = NamedTuple()
+```
+
+Behavior:
+
+- unspecified outputs fall back to `HoldLast()`;
+- used by runtime when resolving cross-clock reads;
+- used as default policy for inferred `InputBindings(...)` when users do not provide explicit bindings.
+
+Example:
+
+```julia
+PlantSimEngine.output_policy(::Type{<:MyModel}) = (
+    carbon_assimilation=Integrate(),
+    leaf_temperature=Aggregate(MeanReducer()),
+)
+```
+
+### `timestep_hint(::Type{<:MyModel})`
+
+Optional compatibility hint when `TimeStepModel(...)` is not provided.
+
+Default:
+
+```julia
+PlantSimEngine.timestep_hint(::Type{<:AbstractModel}) = nothing
+```
+
+Supported forms include:
+
+- fixed period: `Dates.Hour(1)`;
+- range: `(Dates.Minute(30), Dates.Hour(2))`;
+- named tuple: `(; required=..., preferred=...)`.
+
+`required` is enforced when runtime uses meteo-derived timestep.  
+`preferred` is informational only.
+
+### `meteo_hint(::Type{<:MyModel})`
+
+Optional inference trait for weather sampling configuration.
+
+Default:
+
+```julia
+PlantSimEngine.meteo_hint(::Type{<:AbstractModel}) = nothing
+```
+
+Expected value:
+
+```julia
+(; bindings=..., window=...)
+```
+
+Where:
+
+- `bindings` is compatible with `MeteoBindings(...)`,
+- `window` is compatible with `MeteoWindow(...)`.
+
+### `TimeStepDependencyTrait(::Type{<:MyModel})`
+### `ObjectDependencyTrait(::Type{<:MyModel})`
+
+Parallelization traits (single-scale runtime):
+
+- `TimeStepDependencyTrait`: depends or not on other timesteps;
+- `ObjectDependencyTrait`: depends or not on other objects.
+
+Defaults are conservative (`dependent`) and can be overridden when safe.
+
+## Precedence rules
+
+Runtime precedence is intentionally explicit:
+
+1. Input policy:
+   explicit `InputBindings(..., policy=...)` > inferred from producer `output_policy` > `HoldLast()`.
+1. Timestep:
+   `TimeStepModel(...)` > `timespec(model)` when non-default > meteo base step.
+1. Meteo sampling:
+   explicit `MeteoBindings(...)`/`MeteoWindow(...)` > `meteo_hint(...)` > runtime defaults.
+
+## Is everything documented?
+
+For model-level traits, the documented set is now:
+
+- `timespec`,
+- `output_policy`,
+- `timestep_hint`,
+- `meteo_hint`,
+- `TimeStepDependencyTrait`,
+- `ObjectDependencyTrait`.
+
+Outside model traits, `PlantSimEngine` also exposes data-format traits such as `DataFormat` for input containers (see [Input types](working_with_data/inputs.md)).
+
+## Naming conventions and API consistency
+
+Current API uses two naming styles on purpose:
+
+- snake_case for trait/query functions (`timespec`, `output_policy`, `timestep_hint`, `meteo_hint`);
+- CamelCase for `ModelSpec` pipeline transforms (`TimeStepModel`, `InputBindings`, `MeteoBindings`, `MeteoWindow`, `OutputRouting`, `ScopeModel`).
+
+This distinction reflects role:
+
+- snake_case: "what the model declares";
+- CamelCase: "what the mapping config applies".
+
+For future unification, a non-breaking path would be:
+
+1. keep existing names as stable API,
+1. avoid plain snake_case aliases that would collide with existing getter names
+   (`input_bindings`, `meteo_bindings`, `output_routing`, `model_scope`),
+1. if needed, add explicit config-oriented aliases with distinct names
+   (for example `*_config` forms) and keep current constructors,
+1. evaluate deprecations only after one full release cycle and user feedback.

docs/src/step_by_step/parallelization.md

@@ -12,6 +12,7 @@ That means that you can provide any compatible executor to the `executor` argume
 ### Parallel traits
 
 `PlantSimEngine.jl` uses [Holy traits](https://invenia.github.io/blog/2019/11/06/julialang-features-part-2/) to define if a model can be run in parallel.
+See also [Model traits](../model_traits.md) for a full inventory of model-level traits.
 
 !!! note
     A model is executable in parallel over time-steps if it does not uses or set values from other time-steps, and over objects if it does not uses or set values from other objects.

src/mtg/model_spec_inference.jl

@@ -357,6 +357,17 @@ function _input_candidates_for_var(
     return same_scale, cross_scale
 end
 
+function _default_policy_for_inferred_binding(model_specs, source_scale::String, source_process::Symbol, source_var::Symbol)
+    source_spec = model_specs[source_scale][source_process]
+    source_model = model_(source_spec)
+    source_output_policy = output_policy(source_model)
+    source_var in keys(source_output_policy) || return HoldLast()
+    return _as_schedule_policy(
+        source_output_policy[source_var];
+        context="output_policy for inferred binding from `$(source_scale)/$(source_process).$(source_var)`"
+    )
+end
+
 function _infer_input_binding_for_var(
     model_specs,
     scale::String,
@@ -376,7 +387,8 @@ function _infer_input_binding_for_var(
 
     if length(same_scale) == 1
         c = only(same_scale)
-        return (process=c.process, var=c.var, policy=HoldLast())
+        policy = _default_policy_for_inferred_binding(model_specs, c.scale, c.process, c.var)
+        return (process=c.process, var=c.var, policy=policy)
     elseif length(same_scale) > 1
         error(
             "Ambiguous inferred producer for input `$(input_var)` in process `$(process)` at scale `$(scale)`. ",
@@ -387,7 +399,8 @@ function _infer_input_binding_for_var(
 
     if length(cross_scale) == 1
         c = only(cross_scale)
-        return (process=c.process, var=c.var, scale=c.scale, policy=HoldLast())
+        policy = _default_policy_for_inferred_binding(model_specs, c.scale, c.process, c.var)
+        return (process=c.process, var=c.var, scale=c.scale, policy=policy)
     elseif length(cross_scale) > 1
         by_process = Dict{Symbol,Vector{NamedTuple}}()
         for c in cross_scale
@@ -398,7 +411,9 @@ function _infer_input_binding_for_var(
             proc = only(keys(by_process))
             scales = unique(c.scale for c in by_process[proc])
             if length(scales) == 1
-                return (process=proc, var=input_var, scale=only(scales), policy=HoldLast())
+                src_scale = only(scales)
+                policy = _default_policy_for_inferred_binding(model_specs, src_scale, proc, input_var)
+                return (process=proc, var=input_var, scale=src_scale, policy=policy)
             end
             # Same process name appears at multiple scales (common in multiscale
             # mappings). Keep scale unresolved so runtime resolves through parent links.
@@ -505,6 +520,7 @@ end
 
 Fill missing `ModelSpec` fields from inference:
 - auto input bindings from unique same-name producers
+  (including default policy from producer `output_policy`)
 - model-level hint traits (`timestep_hint`, `meteo_hint`)
 Explicit `ModelSpec` user values always take precedence over inferred values.
 """

src/processes/models_inputs_outputs.jl

@@ -51,6 +51,10 @@ timespec(::Type{<:AbstractModel}) = ClockSpec(1.0, 0.0)
 
 Per-output scheduling policy for a model. Default is empty, meaning all outputs
 fallback to hold-last behaviour.
+
+When multi-rate input bindings are inferred automatically, this trait also
+provides the default cross-clock policy (`HoldLast`, `Integrate`, `Aggregate`,
+or `Interpolate`) for each producer output.
 """
 output_policy(model::AbstractModel) = output_policy(typeof(model))
 output_policy(::Type{<:AbstractModel}) = NamedTuple()

src/time/multirate.jl

@@ -65,6 +65,31 @@ Use the latest available producer value.
 """
 struct HoldLast <: SchedulePolicy end
 
+function _as_schedule_policy(policy; context::AbstractString="schedule policy")
+    if policy isa DataType
+        policy <: SchedulePolicy || error(
+            "Unsupported $(context) type `$(policy)`. ",
+            "Expected a `SchedulePolicy` type or instance."
+        )
+        return try
+            policy()
+        catch
+            error(
+                "Unsupported $(context) type `$(policy)`: ",
+                "this policy type cannot be instantiated without arguments. ",
+                "Provide a policy instance instead."
+            )
+        end
+    elseif policy isa SchedulePolicy
+        return policy
+    end
+
+    error(
+        "Unsupported $(context) value `$(policy)` of type `$(typeof(policy))`. ",
+        "Expected a `SchedulePolicy` type or instance."
+    )
+end
+
 const _INTERPOLATE_MODES = (:linear, :hold)
 
 """

src/time/runtime/input_resolution.jl

@@ -400,12 +400,14 @@ function resolve_inputs_from_temporal_state!(sim::GraphSimulation, node::SoftDep
         source_process = nothing
         source_var = input_var
         policy = HoldLast()
+        policy_is_explicit = false
 
         if !isnothing(binding) && !isnothing(binding.process)
             source_process = binding.process
             source_var = isnothing(binding.var) ? input_var : binding.var
             source_scale = isnothing(binding.scale) ? _source_scale_for_process(node, source_process) : binding.scale
             policy = binding.policy
+            policy_is_explicit = true
         else
             candidates = _candidate_producers(node, input_var)
             if length(candidates) == 1
@@ -421,6 +423,9 @@ function resolve_inputs_from_temporal_state!(sim::GraphSimulation, node::SoftDep
             end
         end
         source_model_spec = _model_spec_for_process(sim, source_scale, source_process)
+        if !policy_is_explicit
+            policy = _policy_for_output(model_(source_model_spec), source_var)
+        end
 
         if policy isa HoldLast
             _resolve_input_holdlast(sim, node, st, consumer_scope, source_model_spec, input_var, source_scale, source_process, source_var, t)

src/time/runtime/publishers.jl

@@ -5,7 +5,8 @@ Return the per-output schedule policy for `var`, defaulting to `HoldLast()`.
 """
 function _policy_for_output(model, var::Symbol)
     pol = output_policy(model)
-    var in keys(pol) ? pol[var] : HoldLast()
+    var in keys(pol) || return HoldLast()
+    return _as_schedule_policy(pol[var]; context="output_policy for output `$(var)` in model `$(typeof(model))`")
 end
 
 """