Add helpers for debugging model specs and meteo specs

Author: VEZY

docs/src/API/API_public.md

@@ -26,6 +26,8 @@ For mapping-level multi-rate configuration, combine:
 - `ScopeModel(...)`
 - `timestep_hint(::Type{<:AbstractModel})` (optional trait)
 - `meteo_hint(::Type{<:AbstractModel})` (optional trait)
+- `resolved_model_specs(mapping)` (utility)
+- `explain_model_specs(mapping_or_sim)` (utility)
 - `OutputRequest(...)` in `tracked_outputs` for resampled exports
 
 `TimeStepModel(...)` accepts:

docs/src/model_execution.md

@@ -36,6 +36,11 @@ For meteo hints:
   and `window` matches `MeteoWindow(...)`.
 - Explicit `MeteoBindings(...)` / `MeteoWindow(...)` always take precedence.
 
+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.
+
 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())`.

src/PlantSimEngine.jl

@@ -125,6 +125,7 @@ export OutputCache, HoldLastCache, InterpolateCache, IntegrateCache, AggregateCa
 export TemporalState
 export OutputRequest, collect_outputs
 export ModelList, MultiScaleModel, ModelSpec, TimeStepModel, InputBindings, MeteoBindings, MeteoWindow, OutputRouting, ScopeModel
+export resolved_model_specs, explain_model_specs
 export RMSE, NRMSE, EF, dr
 export Status, TimeStepTable, status
 export init_status!

src/mtg/model_spec_inference.jl

@@ -269,3 +269,98 @@ function infer_model_specs_configuration!(model_specs)
     _infer_meteo_hints!(model_specs)
     return model_specs
 end
+
+"""
+    resolved_model_specs(mapping; infer=true, validate=true)
+    resolved_model_specs(sim::GraphSimulation)
+
+Return process-indexed `ModelSpec` dictionaries as used by runtime:
+`Dict{String, Dict{Symbol, ModelSpec}}`.
+
+For a mapping, this parses model declarations and optionally applies inference
+(`timestep_hint`, `meteo_hint`) and validation.
+For a `GraphSimulation`, this returns the already resolved model specs used by the simulation.
+"""
+function resolved_model_specs(mapping::AbstractDict; infer::Bool=true, validate::Bool=true)
+    model_specs = Dict{String,Dict{Symbol,ModelSpec}}()
+    for (scale, declarations) in pairs(mapping)
+        model_specs[string(scale)] = parse_model_specs(declarations)
+    end
+
+    infer && infer_model_specs_configuration!(model_specs)
+    validate && validate_model_specs_configuration(model_specs)
+    return model_specs
+end
+
+resolved_model_specs(sim::GraphSimulation; infer::Bool=true, validate::Bool=true) = get_model_specs(sim)
+
+function _stringify_compact(x; maxlen::Int=120)
+    s = sprint(show, x)
+    return ncodeunits(s) <= maxlen ? s : string(first(s, maxlen - 3), "...")
+end
+
+function _model_specs_rows(model_specs)
+    rows = NamedTuple[]
+    for scale in sort!(collect(keys(model_specs)))
+        specs_at_scale = model_specs[scale]
+        for process in sort!(collect(keys(specs_at_scale)); by=string)
+            spec = specs_at_scale[process]
+            push!(rows, (
+                scale=scale,
+                process=process,
+                model=typeof(model_(spec)),
+                timestep=timestep(spec),
+                meteo_bindings=meteo_bindings(spec),
+                meteo_window=meteo_window(spec),
+            ))
+        end
+    end
+    return rows
+end
+
+"""
+    explain_model_specs(target; io=stdout, infer=true, validate=true)
+
+Print a compact per-model summary of resolved runtime configuration and return it
+as a vector of named tuples.
+
+Summary fields:
+- `scale`
+- `process`
+- `model`
+- `timestep`
+- `meteo_bindings`
+- `meteo_window`
+"""
+function explain_model_specs(target; io::IO=stdout, infer::Bool=true, validate::Bool=true)
+    specs = target isa GraphSimulation ? resolved_model_specs(target) : resolved_model_specs(target; infer=infer, validate=validate)
+    rows = _model_specs_rows(specs)
+
+    println(io, "Resolved model specs:")
+    if isempty(rows)
+        println(io, "  (no model specs)")
+        return rows
+    end
+
+    for row in rows
+        timestep_desc = isnothing(row.timestep) ? "(timespec(model))" : _stringify_compact(row.timestep)
+        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(
+            io,
+            "  - ",
+            row.scale,
+            "/",
+            row.process,
+            " [",
+            row.model,
+            "]: timestep=",
+            timestep_desc,
+            ", meteo_bindings=",
+            meteo_bindings_desc,
+            ", meteo_window=",
+            meteo_window_desc
+        )
+    end
+    return rows
+end

test/test-multirate-runtime.jl

@@ -599,6 +599,12 @@ PlantSimEngine.meteo_hint(::Type{<:MRMeteoHintConsumerModel}) = (
     @test status(sim_timestep_hints)["Leaf"][1].XB == 3.0
     @test status(sim_timestep_hints)["Leaf"][1].XF == 4.0
 
+    io_hints = IOBuffer()
+    explained_hints = PlantSimEngine.explain_model_specs(sim_timestep_hints; io=io_hints)
+    explain_hints_txt = String(take!(io_hints))
+    @test any(r -> r.process == :mrrangehinta && Dates.value(Dates.Second(r.timestep)) == 10800, explained_hints)
+    @test occursin("Leaf/mrrangehinta", explain_hints_txt)
+
     if _HAS_METEO_SAMPLER_API
         # Expectation 18: meteo is sampled at model clock using default weather aggregation.
         mapping_meteo_default = Dict(

test/test-multirate-scaffolding.jl

@@ -16,6 +16,19 @@ using Test
     @test output_routing(ModelSpec(m)) == NamedTuple()
     @test model_scope(ModelSpec(m)) == :global
 
+    mapping = Dict("Leaf" => (m,))
+    resolved_specs = resolved_model_specs(mapping)
+    @test haskey(resolved_specs, "Leaf")
+    @test haskey(resolved_specs["Leaf"], :process1)
+
+    io = IOBuffer()
+    explained = explain_model_specs(mapping; io=io)
+    explain_txt = String(take!(io))
+    @test length(explained) == 1
+    @test explained[1].process == :process1
+    @test occursin("Resolved model specs:", explain_txt)
+    @test occursin("Leaf/process1", explain_txt)
+
     spec = ModelSpec(m) |>
            TimeStepModel(24.0) |>
            InputBindings(; var1=(process=:process1, var=:var3)) |>