Update model_execution.md

document new multi-rate option

Author: VEZY

docs/src/model_execution.md

@@ -8,3 +8,63 @@
 2. Then, models that have a dependency on other models are run. The first ones are the ones that depend on an independent model. Then the ones that are children of the second ones, and then their children ... until no children are found anymore. There are two types of children models (*i.e.* dependencies): hard and soft dependencies:
    1. Hard dependencies are always run before soft dependencies. A hard dependency is a model that is directly called by another model. It is declared as such by its parent that lists its hard-dependencies as `dep`. See [this example](https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/3d91bb053ddbd087d38dcffcedd33a9db35a0fcc/examples/dummy.jl#L39) that shows `Process2Model` defining a hard dependency on any model that simulates `process1`.
    2. Soft dependencies are then run sequentially. A model has a soft dependency on another model if one or more of its inputs is computed by another model. If a soft dependency has several parent nodes (*e.g.* two different models compute two inputs of the model), it is run only if all its parent nodes have been run already. In practice, when we visit a node that has one of its parent that did not run already, we stop the visit of this branch. The node will eventually be visited from the branch of the last parent that was run.
+
+## Multi-rate model configuration (experimental)
+
+For multiscale simulations, model usage is configured in the mapping through `ModelSpec` transforms:
+
+- `TimeStepModel(...)`: sets model execution clock.
+- `InputBindings(...)`: sets producer, source variable, optional source scale, and policy for each consumer input.
+- `OutputRouting(...)`: sets whether an output is canonical (`:canonical`) or stream-only (`:stream_only`).
+
+Typical pipeline form:
+
+```julia
+ModelSpec(MyModel()) |>
+TimeStepModel(ClockSpec(24.0, 1.0)) |>
+InputBindings(; x=(process=:producer, var=:y, policy=HoldLast())) |>
+OutputRouting(; z=:stream_only)
+```
+
+### Hold-last coupling (default policy)
+
+```julia
+mapping = Dict(
+    "Leaf" => (
+        ModelSpec(LeafSourceModel()) |> TimeStepModel(1.0),
+        ModelSpec(LeafConsumerModel()) |>
+        TimeStepModel(ClockSpec(2.0, 1.0)) |>
+        InputBindings(; C=(process=:leafsource, var=:S)),
+    ),
+)
+```
+
+### Daily integration from hourly stream
+
+```julia
+mapping = Dict(
+    "Leaf" => (
+        ModelSpec(HourlyAssimModel()) |> TimeStepModel(1.0),
+    ),
+    "Plant" => (
+        ModelSpec(DailyCarbonOfferModel()) |>
+        TimeStepModel(ClockSpec(24.0, 1.0)) |>
+        InputBindings(; A=(process=:hourlyassim, var=:A, scale="Leaf", policy=Integrate())),
+    ),
+)
+```
+
+### Interpolate slow producer to fast consumer
+
+```julia
+mapping = Dict(
+    "Leaf" => (
+        ModelSpec(SlowSourceModel()) |> TimeStepModel(ClockSpec(2.0, 1.0)),
+        ModelSpec(FastConsumerModel()) |>
+        TimeStepModel(1.0) |>
+        InputBindings(; X=(process=:slowsource, var=:X, policy=Interpolate())),
+    ),
+)
+```
+
+When `multirate=true` is passed to `run!`, the runtime resolves inputs from producer temporal streams according to these policies.