Add default inference of input bindings

Author: VEZY

docs/src/API/API_public.md

@@ -43,6 +43,8 @@ Period conversion detail:
 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 `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.

docs/src/model_execution.md

@@ -25,6 +25,12 @@ the runtime can infer defaults from model traits:
 - `timestep_hint(::Type{<:MyModel})`
 - `meteo_hint(::Type{<:MyModel})`
 
+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,
@@ -39,7 +45,7 @@ For meteo hints:
 Inspection helpers:
 - `resolved_model_specs(mapping)` returns resolved specs after inference/validation.
 - `explain_model_specs(mapping_or_sim)` prints a compact summary (`timestep`,
-  `meteo_bindings`, `meteo_window`) for each model process.
+  `input_bindings`, `meteo_bindings`, `meteo_window`) for each model process.
 
 Policy parameterization:
 - `Integrate()` defaults to `SumReducer()`; you can pass another reducer, e.g. `Integrate(MeanReducer())` or `Integrate(vals -> maximum(vals) - minimum(vals))`.

src/mtg/model_spec_inference.jl

@@ -217,6 +217,102 @@ function _infer_timestep_hints!(model_specs)
     return nothing
 end
 
+function _format_candidate_list(candidates)
+    isempty(candidates) && return "(none)"
+    return join(["$(c.scale)/$(c.process)" for c in candidates], ", ")
+end
+
+function _input_candidates_for_var(model_specs, consumer_scale::String, consumer_process::Symbol, input_var::Symbol)
+    same_scale = NamedTuple[]
+    cross_scale = NamedTuple[]
+
+    for (scale, specs_at_scale) in pairs(model_specs)
+        for (process, spec) in pairs(specs_at_scale)
+            scale == consumer_scale && process == consumer_process && continue
+            input_var in keys(outputs_(model_(spec))) || continue
+            c = (scale=scale, process=process, var=input_var)
+            if scale == consumer_scale
+                push!(same_scale, c)
+            else
+                push!(cross_scale, c)
+            end
+        end
+    end
+
+    return same_scale, cross_scale
+end
+
+function _infer_input_binding_for_var(model_specs, scale::String, process::Symbol, input_var::Symbol)
+    same_scale, cross_scale = _input_candidates_for_var(model_specs, scale, process, input_var)
+
+    if length(same_scale) == 1
+        c = only(same_scale)
+        return (process=c.process, var=c.var, policy=HoldLast())
+    elseif length(same_scale) > 1
+        error(
+            "Ambiguous inferred producer for input `$(input_var)` in process `$(process)` at scale `$(scale)`. ",
+            "Multiple same-scale candidates were found: $(_format_candidate_list(same_scale)). ",
+            "Please provide explicit `InputBindings(...)`."
+        )
+    end
+
+    if length(cross_scale) == 1
+        c = only(cross_scale)
+        return (process=c.process, var=c.var, scale=c.scale, policy=HoldLast())
+    elseif length(cross_scale) > 1
+        by_process = Dict{Symbol,Vector{NamedTuple}}()
+        for c in cross_scale
+            push!(get!(by_process, c.process, NamedTuple[]), c)
+        end
+
+        if length(by_process) == 1
+            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())
+            end
+            # Same process name appears at multiple scales (common in multiscale
+            # mappings). Keep scale unresolved so runtime resolves through parent links.
+            return (process=proc, var=input_var, policy=HoldLast())
+        end
+
+        error(
+            "Ambiguous inferred producer for input `$(input_var)` in process `$(process)` at scale `$(scale)`. ",
+            "Multiple cross-scale candidates were found: $(_format_candidate_list(cross_scale)). ",
+            "Please provide explicit `InputBindings(...)`."
+        )
+    end
+
+    # No producer found. Keep input unresolved so user-provided initialization/forced
+    # values can still drive the model.
+    return nothing
+end
+
+function _infer_input_bindings!(model_specs)
+    for (scale, specs_at_scale) in pairs(model_specs)
+        for (process, spec) in pairs(specs_at_scale)
+            current_bindings = input_bindings(spec)
+            current_bindings isa NamedTuple || continue
+
+            inferred = Pair{Symbol,Any}[]
+            model_inputs = keys(inputs_(model_(spec)))
+
+            for input_var in model_inputs
+                input_var in keys(current_bindings) && continue
+                inferred_binding = _infer_input_binding_for_var(model_specs, scale, process, input_var)
+                isnothing(inferred_binding) && continue
+                push!(inferred, input_var => inferred_binding)
+            end
+
+            isempty(inferred) && continue
+            merged = (; pairs(current_bindings)..., inferred...)
+            specs_at_scale[process] = ModelSpec(spec; input_bindings=merged)
+        end
+    end
+
+    return nothing
+end
+
 function _normalize_meteo_hint(scale::String, process::Symbol, hint)
     isnothing(hint) && return (bindings=nothing, window=nothing)
 
@@ -261,10 +357,13 @@ end
 """
     infer_model_specs_configuration!(model_specs)
 
-Fill missing `ModelSpec` fields from model-level hint traits.
+Fill missing `ModelSpec` fields from inference:
+- auto input bindings from unique same-name producers
+- model-level hint traits (`timestep_hint`, `meteo_hint`)
 Explicit `ModelSpec` user values always take precedence over inferred values.
 """
 function infer_model_specs_configuration!(model_specs)
+    _infer_input_bindings!(model_specs)
     _infer_timestep_hints!(model_specs)
     _infer_meteo_hints!(model_specs)
     return model_specs
@@ -310,6 +409,7 @@ function _model_specs_rows(model_specs)
                 process=process,
                 model=typeof(model_(spec)),
                 timestep=timestep(spec),
+                input_bindings=input_bindings(spec),
                 meteo_bindings=meteo_bindings(spec),
                 meteo_window=meteo_window(spec),
             ))
@@ -329,6 +429,7 @@ Summary fields:
 - `process`
 - `model`
 - `timestep`
+- `input_bindings`
 - `meteo_bindings`
 - `meteo_window`
 """
@@ -344,6 +445,7 @@ function explain_model_specs(target; io::IO=stdout, infer::Bool=true, validate::
 
     for row in rows
         timestep_desc = isnothing(row.timestep) ? "(timespec(model))" : _stringify_compact(row.timestep)
+        input_bindings_desc = (row.input_bindings isa NamedTuple && isempty(keys(row.input_bindings))) ? "(none)" : _stringify_compact(row.input_bindings)
         meteo_bindings_desc = (row.meteo_bindings isa NamedTuple && isempty(keys(row.meteo_bindings))) ? "(none)" : _stringify_compact(row.meteo_bindings)
         meteo_window_desc = isnothing(row.meteo_window) ? "(default rolling)" : _stringify_compact(row.meteo_window)
         println(
@@ -356,6 +458,8 @@ function explain_model_specs(target; io::IO=stdout, infer::Bool=true, validate::
             row.model,
             "]: timestep=",
             timestep_desc,
+            ", input_bindings=",
+            input_bindings_desc,
             ", meteo_bindings=",
             meteo_bindings_desc,
             ", meteo_window=",

test/test-multirate-runtime.jl

@@ -166,6 +166,22 @@ function PlantSimEngine.run!(::MRHourlyFromDailyConsumerModel, models, status, m
     status.YD = status.XD
 end
 
+PlantSimEngine.@process "mrzconsumer" verbose = false
+struct MRZConsumerModel <: AbstractMrzconsumerModel end
+PlantSimEngine.inputs_(::MRZConsumerModel) = (Z=-Inf,)
+PlantSimEngine.outputs_(::MRZConsumerModel) = (ZZ=-Inf,)
+function PlantSimEngine.run!(::MRZConsumerModel, models, status, meteo, constants=nothing, extra=nothing)
+    status.ZZ = status.Z
+end
+
+PlantSimEngine.@process "mrmissinginputconsumer" verbose = false
+struct MRMissingInputConsumerModel <: AbstractMrmissinginputconsumerModel end
+PlantSimEngine.inputs_(::MRMissingInputConsumerModel) = (U=-Inf,)
+PlantSimEngine.outputs_(::MRMissingInputConsumerModel) = (OU=-Inf,)
+function PlantSimEngine.run!(::MRMissingInputConsumerModel, models, status, meteo, constants=nothing, extra=nothing)
+    status.OU = status.U
+end
+
 PlantSimEngine.@process "mrmeteodailyconsumer" verbose = false
 struct MRMeteoDailyConsumerModel <: AbstractMrmeteodailyconsumerModel end
 PlantSimEngine.inputs_(::MRMeteoDailyConsumerModel) = NamedTuple()
@@ -268,6 +284,8 @@ PlantSimEngine.meteo_hint(::Type{<:MRMeteoHintConsumerModel}) = (
     @test input_bindings(specs_leaf[:mrconsumer]).C.var == :S
     @test input_bindings(specs_leaf[:mrconsumer]).C.policy isa HoldLast
     @test output_routing(specs_leaf[:mroverwrite]).C == :stream_only
+    @test input_bindings(specs_leaf[:mrautosamename]).S.process == :mrsource
+    @test input_bindings(specs_leaf[:mrautosamename]).S.var == :S
 
     st_leaf = status(sim_ok)["Leaf"][1]
     # Expectation 1: consumer :C input is remapped from mrsource/:S via mapping-level InputBindings.
@@ -388,6 +406,26 @@ PlantSimEngine.meteo_hint(::Type{<:MRMeteoHintConsumerModel}) = (
     @test st_leaf_cross.XS == 4.0
     @test st_plant_cross.XP == 3.0
 
+    # Expectation 8a: cross-scale producer is inferred automatically when unique.
+    source_counter_3_auto = Ref(0)
+    mapping_cross_auto = Dict(
+        "Leaf" => (
+            ModelSpec(MRCrossSourceModel(source_counter_3_auto)) |> TimeStepModel(1.0),
+        ),
+        "Plant" => (
+            ModelSpec(MRCrossConsumerModel()) |>
+            MultiScaleModel([:XS => ["Leaf"]]) |>
+            TimeStepModel(ClockSpec(2.0, 1.0)),
+        ),
+    )
+    sim_cross_auto = PlantSimEngine.GraphSimulation(mtg, mapping_cross_auto, nsteps=4, check=true, outputs=Dict("Leaf" => (:XS,), "Plant" => (:XP,)))
+    run!(sim_cross_auto, meteo4, multirate=true, executor=SequentialEx())
+    st_plant_cross_auto = status(sim_cross_auto)["Plant"][1]
+    @test st_plant_cross_auto.XP == 3.0
+    spec_cross_auto = PlantSimEngine.get_model_specs(sim_cross_auto)["Plant"][:mrcrossconsumer]
+    @test input_bindings(spec_cross_auto).XS.process == :mrcrosssource
+    @test input_bindings(spec_cross_auto).XS.scale == "Leaf"
+
     # Expectation 8b: scope partitioning isolates producer streams between plants.
     scene2 = Node(MultiScaleTreeGraph.NodeMTG("/", "Scene", 1, 0))
     plant2_a = Node(scene2, MultiScaleTreeGraph.NodeMTG("+", "Plant", 1, 1))
@@ -752,7 +790,28 @@ PlantSimEngine.meteo_hint(::Type{<:MRMeteoHintConsumerModel}) = (
         @test_throws "No period available" run!(sim_meteo_calendar_prev_strict, meteo_calendar, multirate=true, executor=SequentialEx())
     end
 
-    # Expectation 24: invalid mapping-level API configuration fails during GraphSimulation init.
+    # Expectation 24: ambiguous same-name inferred producer is rejected at initialization.
+    mapping_ambiguous_infer = Dict(
+        "Leaf" => (
+            MRConflict1Model(),
+            MRConflict2Model(),
+            MRZConsumerModel(),
+        ),
+    )
+    @test_throws "Ambiguous inferred producer for input `Z`" PlantSimEngine.GraphSimulation(mtg, mapping_ambiguous_infer, nsteps=1, check=true, outputs=Dict("Leaf" => (:ZZ,)))
+
+    # Expectation 25: missing producer remains allowed; model can rely on initialized/forced inputs.
+    mapping_missing_input = Dict(
+        "Leaf" => (
+            MRMissingInputConsumerModel(),
+            Status(U=42.0),
+        ),
+    )
+    sim_missing_input = PlantSimEngine.GraphSimulation(mtg, mapping_missing_input, nsteps=1, check=true, outputs=Dict("Leaf" => (:OU,)))
+    run!(sim_missing_input, meteo, multirate=true, executor=SequentialEx())
+    @test status(sim_missing_input)["Leaf"][1].OU == 42.0
+
+    # Expectation 26: invalid mapping-level API configuration fails during GraphSimulation init.
     mapping_bad_input = Dict(
         "Leaf" => (
             MRSourceModel(),

test/test-multirate-scaffolding.jl

@@ -28,6 +28,7 @@ using Test
     @test explained[1].process == :process1
     @test occursin("Resolved model specs:", explain_txt)
     @test occursin("Leaf/process1", explain_txt)
+    @test occursin("input_bindings=", explain_txt)
 
     spec = ModelSpec(m) |>
            TimeStepModel(24.0) |>