diff --git a/README.md b/README.md index 31fbd5bcf..0a2d5cc39 100644 --- a/README.md +++ b/README.md @@ -42,18 +42,24 @@ model-scale simulations. ## Installation -In Julia package mode: - -```julia -add PlantSimEngine -``` - -Then: +The examples on this development branch use `CompositeModel`. Registered +releases through 0.14.1 use the previous mapping API; use their matching +[stable documentation](https://VirtualPlantLab.github.io/PlantSimEngine.jl/stable). +To run the examples below, install the development version in a project: ```julia +using Pkg +Pkg.activate("my_simulation") +Pkg.add(["PlantMeteo", "DataFrames"]) +Pkg.add(url="https://github.com/VirtualPlantLab/PlantSimEngine.jl", rev="main") using PlantSimEngine ``` +When following a pull-request preview, use its branch or commit instead of +`"main"`. Keep `Project.toml` and `Manifest.toml` with your experiment to record +the package revisions. The [installation guide](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/prerequisites/installing_plantsimengine.html) +also installs the plotting tools used by the tutorials. + ## Quickstart This example runs three existing toy models on one model object: @@ -62,12 +68,19 @@ This example runs three existing toy models on one model object: 2. `ToyLAIModel` consumes cumulative thermal time and computes LAI. 3. `Beer` consumes LAI and meteorology to compute absorbed PAR. +Run the full weather year to see canopy growth and senescence. The bundled +file contains daily radiation totals in MJ m⁻² d⁻¹ under historical `_f` +column names; convert them to mean fluxes in W m⁻² for `Beer` when reading. + ```julia using PlantSimEngine, PlantMeteo, Dates, DataFrames using PlantSimEngine.Examples meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); + joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), + :Ri_SW_f => (x -> x .* 1e6 ./ 86_400) => :Ri_SW_f, + :Ri_PAR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_PAR_f, + :Ri_NIR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_NIR_f; duration=Dates.Day, ) @@ -78,7 +91,7 @@ model = CompositeModel( environment=meteo_day, ) -sim = run!(model; steps=30, outputs=:all) +sim = run!(model; steps=length(meteo_day), outputs=:all) out = collect_outputs(sim; sink=DataFrame) first(out, 6) ``` @@ -208,11 +221,11 @@ Diagnostics.explain_execution_plan(model) - [Stable documentation](https://VirtualPlantLab.github.io/PlantSimEngine.jl/stable) - [Development documentation](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev) -- [CompositeModel/object quickstart](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/composite_model/quickstart/) -- [Implement a model](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/journeys/modelers/basic_model/) -- [AI agent skill](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/agent_skill/) -- [CompositeModel/object migration guide](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/migration_composite_model/) -- [Public API reference](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/API/API_public/) +- [Run and couple models](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/journeys/users/one_object.html) +- [Implement a model](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/journeys/modelers/basic_model.html) +- [AI agent skill](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/agent_skill.html) +- [CompositeModel/object migration guide](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/migration_composite_model.html) +- [Public API reference](https://VirtualPlantLab.github.io/PlantSimEngine.jl/dev/API/API_public.html) ## Projects That Use PlantSimEngine diff --git a/docs/Project.toml b/docs/Project.toml index 41aedce0e..e7a9dc1ee 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,8 +1,19 @@ [deps] +Bonito = "824d6782-a2ef-11e9-3a09-e5662e0c26f8" CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b" CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0" DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589" MultiScaleTreeGraph = "dd4a991b-8a45-4075-bede-262ee62d5583" PlantMeteo = "4630fe09-e0fb-4da5-a846-781cb73437b6" PlantSimEngine = "9a576370-710b-4269-adf9-4f603a9c6423" + +[compat] +Bonito = "5.2" +Documenter = "1.11" +LiveServer = "1" +julia = "1.11" + +[sources] +PlantSimEngine = {path = ".."} diff --git a/docs/bonito_rendering.jl b/docs/bonito_rendering.jl new file mode 100644 index 000000000..8175167c5 --- /dev/null +++ b/docs/bonito_rendering.jl @@ -0,0 +1,21 @@ +module BonitoRendering + +using Bonito, Documenter + +const Writer = Base.get_extension(Bonito, :BonitoDocumenterExt) +isnothing(Writer) && error("Bonito's Documenter extension must be loaded") + +# Documenter wraps @eval Markdown results in a MarkdownAST.Document node. +# Bonito 5.2 falls back to plain text for that root, dropping code blocks, +# tables and their formatting. Dispatch its children through the normal writer. +# Leave an upstream implementation in place when Bonito adds this method. +const document_method = which( + Writer.domify, (Writer.DCtx, Writer.MA.Node, Writer.MA.Document), +) +if last(Base.unwrap_unionall(document_method.sig).parameters) === Any + function Writer.domify(ctx::Writer.DCtx, node::Writer.MA.Node, ::Writer.MA.Document) + return Writer.domify_children(ctx, node) + end +end + +end diff --git a/docs/branding.md b/docs/branding.md new file mode 100644 index 000000000..8c27e89f1 --- /dev/null +++ b/docs/branding.md @@ -0,0 +1,14 @@ +# PlantSimEngine logo + +The logo combines a branching plant with three connection points. The leaves and roots represent the soil–plant–atmosphere systems modeled with PlantSimEngine; the connected nodes represent reusable processes and their coupling. The plant is deliberately species-neutral. + +The transparent PNG in `src/assets/logo.png` is used for the documentation header, landing page, and favicon. It was generated with Codex's built-in image-generation tool on 2026-09-06. It is a raster original, not an SVG. Keep the original alpha channel when preparing other sizes. + +## Generation prompt + +Use case: logo-design. +Asset type: Primary standalone logo mark for PlantSimEngine.jl, an open-source Julia scientific framework for coupling modular process models to simulate plants, their growth, and exchanges with soil and atmosphere. +Create ONE finished, distinctive professional symbol, on a genuinely transparent background with an alpha channel. No lettering. +Concept: a living branching plant that is also a small connected model graph. A clean upright gently curved central stem, three to four botanical leaf shapes on branches at different heights, an understated small branching root base, and exactly three restrained circular connection nodes integrated into the stem/branch junctions. The branching stem itself provides the graph edges; avoid a separate network floating around the plant. Convey modularity, exchange and growth. Species-neutral, not palm-specific. +Style: exceptionally clear flat vector-like brand mark, elegant scientific identity, generous negative space, coherent moderately bold smooth strokes, crisp geometric curves, a recognizable silhouette at 32 pixels. A slight botanical asymmetry makes it alive. Leaves should look organic and distinct, with no internal vein detail. Compact roughly circular/rounded-triangular composition, not a tall skinny sprout. Palette limited to deep teal #156F64, fresh green #64AF66 and a small warm gold #DEA748 accent on one node. Colors should read on both white and dark navy backgrounds. +Composition: icon alone centered on a square 1024x1024 transparent canvas; icon fills about 80 percent of frame with balanced clear margin. No text, no wordmark, no surrounding circle/badge, no gear, no literal motor, no circuit-board clutter, no gradients, no shadows, no 3D, no mockup, no decorative background, no watermark. Deliver the actual logo asset, not a presentation sheet. diff --git a/docs/check_static_export.jl b/docs/check_static_export.jl new file mode 100644 index 000000000..d0db9fd42 --- /dev/null +++ b/docs/check_static_export.jl @@ -0,0 +1,124 @@ +""" +Finish and validate the Bonito documentation export. + +Bonito 5.2 emits site-root-relative URLs even for nested Markdown pages. Give +each page an explicit site base, keep fragment links on their original page, +and adapt the theme's outline lookup. This also fixes asset URLs serialized +inside Bonito applications, which cannot be repaired by rewriting HTML alone. +""" +function finish_static_export(build_dir=joinpath(@__DIR__, "build")) + source_dir = joinpath(@__DIR__, "src") + pages = [ + replace(relpath(joinpath(root, file), source_dir), r"\.md$" => ".html") + for (root, _, files) in walkdir(source_dir) for file in files + if endswith(file, ".md") + ] + + # Preserve Bonito's scroll-aware outline after qualifying fragment links. + scripts = [ + joinpath(root, file) + for (root, _, files) in walkdir(joinpath(build_dir, "bonito")) for file in files + if occursin(r"^docs\d+\.js$", file) + ] + length(scripts) == 1 || error("Expected one Bonito documentation theme script") + script = only(scripts) + javascript = read(script, String) + old_lookup = "a.getAttribute(\"href\").slice(1)" + count(old_lookup, javascript) == 1 || error( + "Bonito's outline code changed; review the nested-page export adjustment", + ) + old_version_link = "return '' + esc(v) + \"\";" + count(old_version_link, javascript) == 1 || error( + "Bonito's version navigation changed; review the preview export adjustment", + ) + new_version_link = "return '' + esc(v) + \"\";" + # Exported package assets may be read-only. Write a site-owned script and + # leave the copied upstream asset intact. + patched_script = joinpath(build_dir, "assets", "docs-navigation.js") + write(patched_script, replace(javascript, old_lookup => "a.hash.slice(1)", old_version_link => new_version_link)) + original_script_url = replace(relpath(script, build_dir), '\\' => '/') + + for page in pages + path = joinpath(build_dir, page) + isfile(path) || error("Missing exported documentation page: $page") + html = read(path, String) + occursin(" '/') * "/" + page_url = replace(page, '\\' => '/') + html = replace(html, original_script_url => "assets/docs-navigation.js") + html = replace(html, "href=\"#" => "href=\"$page_url#") + + html = normalize_local_export_links(html, path, build_dir) + # Version metadata lives above dev/stable, and two levels above a PR preview. + version_loader = raw"""""" + versions_tag = r"]*\bsrc=\"\.\./versions\.js\"[^>]*>" + count(versions_tag, html) == 1 || error("Expected Bonito version metadata script in $page") + html = replace(html, versions_tag => version_loader) + extras = "" * + "" + count("", html) == 1 || error("Expected one HTML head in $page") + html = replace(html, "" => "" * extras; count=1) + html = replace(html, "" => ""; count=1) + write(path, html) + end + check_static_export(build_dir; pages) + return nothing +end + +function normalize_local_export_links(html, page_path, build_dir) + # Raw embeds and some Documenter contents links remain page-relative. + return replace(html, r"(?:href|src)=\"[^\"]*\"" => matched -> begin + attribute, reference = split(matched, "=\""; limit=2) + reference = chop(reference; tail=1) + occursin(r"^(?:[A-Za-z][A-Za-z0-9+.-]*:|/|#)", reference) && return matched + target = first(split(first(split(reference, '#')), '?')) + isempty(target) && return matched + ispath(joinpath(build_dir, target)) && return matched + resolved = normpath(joinpath(dirname(page_path), target)) + isfile(resolved) || return matched + relative = replace(relpath(resolved, build_dir), '\\' => '/') + suffix = reference[nextind(reference, lastindex(target)):end] + "$attribute=\"$relative$suffix\"" + end) +end + +function check_static_export(build_dir=joinpath(@__DIR__, "build"); pages) + binary_files = Set{String}() + for page in pages + html = read(joinpath(build_dir, page), String) + occursin(r"Bonito\.init_session\([^;]*,\s*false\);"s, html) || + error("Missing expected Bonito export bootstrap: $page") + markup = replace(html, r"]*>.*?"s => matched -> first(split(matched, '>'; limit=2)) * ">") + references = [m.captures[1] for m in eachmatch(r"(?:href|src)=\"([^\"]+)\"", markup)] + for matched in eachmatch(r"Bonito\.fetch_binary\([\"']([^\"']+)[\"']\)", html) + reference = matched.captures[1] + push!(references, reference) + push!(binary_files, reference) + end + for reference in references + startswith(reference, "//") && continue + occursin(r"^[A-Za-z][A-Za-z0-9+.-]*:", reference) && continue + target = first(split(first(split(reference, '#')), '?')) + isempty(target) && continue + target = replace(target, "%20" => " ", "&" => "&") + # The base itself deliberately leads from this page to the site root. + target == replace(relpath(build_dir, dirname(joinpath(build_dir, page))), '\\' => '/') * "/" && continue + ispath(joinpath(build_dir, target)) || error( + "Missing local export target $reference in $page", + ) + end + end + isempty(binary_files) && error("Static export contains no Bonito session data") + @info "Validated static documentation export" pages=length(pages) states=length(binary_files) + return nothing +end diff --git a/docs/make.jl b/docs/make.jl index 0dd08366c..499f23698 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,12 +1,14 @@ -#using Pkg -#Pkg.develop("PlantSimEngine") using PlantSimEngine using PlantMeteo using DataFrames, CSV using Documenter +using Bonito using CairoMakie using PlantSimEngine.Examples +include(joinpath(@__DIR__, "model_source.jl")) +include(joinpath(@__DIR__, "bonito_rendering.jl")) + function build_model_graph_example() output_dir = joinpath(@__DIR__, "src", "assets") mkpath(output_dir) @@ -29,104 +31,129 @@ build_model_graph_example() DocMeta.setdocmeta!(PlantSimEngine, :DocTestSetup, :(using PlantSimEngine, PlantMeteo, DataFrames, CSV, CairoMakie); recursive=true) +home = ( + name="PlantSimEngine.jl", + text="Build plant simulations from connected process models", + tagline="Combine models of growth and plant–environment interactions in Julia, " * + "from crop canopies to individual plants and organs.", + image="assets/logo.png", + actions=[ + (text="Couple existing models", link="journeys/users/one_object.html", theme="brand"), + (text="Write a process model", link="journeys/modelers/basic_model.html", theme="alt"), + ], + features=[ + ( + title="Crop and canopy models", + details="Connect phenology, canopy development and resource capture without representing every organ.", + link="journeys/users/one_object.html", + ), + ( + title="Functional–structural models", + details="Apply processes to individual organs and connect their exchanges as plants grow.", + link="journeys/users/one_plant.html", + ), + ( + title="Plant–environment interactions", + details="Combine leaf, canopy and soil processes, with different time steps and shared resources.", + link="journeys/users/maespa_synthesis.html", + ), + ], +) + makedocs(; modules=[PlantSimEngine], authors="Rémi Vezy and contributors", repo=Documenter.Remotes.GitHub("VirtualPlantLab", "PlantSimEngine.jl"), sitename="PlantSimEngine.jl", - format=Documenter.HTML(; - prettyurls=get(ENV, "CI", "false") == "true", - canonical="https://VirtualPlantLab.github.io/PlantSimEngine.jl", - edit_link="main", - assets=String[], - size_threshold=700000 + format=Bonito.DocumenterBonito(; + repo="github.com/VirtualPlantLab/PlantSimEngine.jl", + devbranch="main", + devurl="dev", + version=get(ENV, "GITHUB_REF_TYPE", "") == "tag" ? get(ENV, "GITHUB_REF_NAME", "dev") : "dev", + logo="assets/logo.png", + home, + description="Connect process models for crop canopies, plant architectures and plant–environment interactions in Julia, with tools for AI-assisted model development.", ), pages=[ "Home" => "index.md", "Start here" => [ - "Why PlantSimEngine ?" => "./introduction/why_plantsimengine.md", - "Mental model" => "./journeys/users/mental_model.md", - "One object over time" => "./journeys/users/one_object.md", - "Several same-scale objects" => "./journeys/users/several_objects.md", + "Why PlantSimEngine?" => "introduction/why_plantsimengine.md", + "Installation" => "prerequisites/installing_plantsimengine.md", + "Your first simulation" => "journeys/users/one_object.md", + "How the pieces fit" => "journeys/users/mental_model.md", + "Help from an AI coding agent" => "agent_skill.md", + ], + "Couple models" => [ + "Several independent objects" => "journeys/users/several_objects.md", + "One multiscale plant" => "journeys/users/one_plant.md", + "Several plants" => "journeys/users/several_plants.md", + "Connect values between objects" => "guides/multiscale/value_coupling.md", + "Collect and plot results" => "guides/data/outputs_plotting.md", + "Use observed values" => "guides/data/forcing_observations.md", + "Importing an MTG" => "guides/multiscale/import_mtg.md", + "Visualizing structure" => "guides/multiscale/visualizing_structure.md", ], - "Structure and composition" => [ - "One multiscale plant" => "./journeys/users/one_plant.md", - "Several plants" => "./journeys/users/several_plants.md", - "Value coupling" => "./guides/multiscale/value_coupling.md", - "Importing an MTG" => "./guides/multiscale/import_mtg.md", - "How composite models execute" => "./guides/multiscale/concepts.md", - "Visualizing structure" => "./guides/multiscale/visualizing_structure.md", + "Write models" => [ + "New process or new hypothesis?" => "step_by_step/implement_a_process.md", + "Write and test a first model" => "journeys/modelers/basic_model.md", + "Keep equations readable" => "guides/modelers/port_existing_model.md", + "Organize and test your models" => "guides/modelers/repository_and_tests.md", + "Cross-object values" => "journeys/modelers/cross_object_values.md", + "Choose a coupling mechanism" => "guides/coupling.md", + "Model compatibility and replacement" => "step_by_step/model_switching.md", + "Read weather and set time steps" => "journeys/modelers/environment_and_cadence.md", + "Call another model" => "journeys/modelers/hard_dependencies.md", + "Update growing conditions" => "journeys/modelers/mutable_environment.md", + "Models that remember values" => "guides/modelers/stateful_models.md", ], "Environment and time" => [ - "Read an environment" => "./journeys/users/environments.md", - "Different model cadences" => "./journeys/users/cadences.md", - "Hourly, daily, and weekly" => "./guides/time/hourly_daily_weekly.md", - "Advanced configuration" => "./guides/time/advanced_time_environment.md", + "Read an environment" => "journeys/users/environments.md", + "Different model time steps" => "journeys/users/cadences.md", + "Hourly, daily, and weekly" => "guides/time/hourly_daily_weekly.md", + "Choose compatible time steps" => "guides/time/advanced_time_environment.md", ], - "Dynamic and advanced simulations" => [ - "Modify plant structure" => "./journeys/users/structure_changes.md", - "Modify the environment" => "./journeys/users/mutable_environments.md", - "Control advanced execution" => "./journeys/users/advanced_execution.md", - "MAESPA-style synthesis" => "./journeys/users/maespa_synthesis.md", - "Part 2: roots and water" => "./tutorials/growing_plant/part2_roots_water.md", - "Part 3: debugging" => "./tutorials/growing_plant/part3_debugging.md", - "Manual calls" => "./guides/multiscale/manual_calls.md", - "Advanced coupling and hard dependencies" => "./step_by_step/advanced_coupling.md", + "Growth and advanced simulations" => [ + "Modify plant structure" => "journeys/users/structure_changes.md", + "Growth within a time step" => "tutorials/growing_plant/part1_growth.md", + "Roots and water" => "tutorials/growing_plant/part2_roots_water.md", + "Check a growing simulation" => "tutorials/growing_plant/part3_debugging.md", + "Modify the environment" => "journeys/users/mutable_environments.md", + "Control advanced execution" => "journeys/users/advanced_execution.md", + "MAESPA-style synthesis" => "journeys/users/maespa_synthesis.md", + "Control when other models run" => "guides/multiscale/manual_calls.md", + "More about calls between models" => "step_by_step/advanced_coupling.md", ], - "Implement models" => [ - "New process or new hypothesis?" => "./step_by_step/implement_a_process.md", - "Basic contract and reuse" => "./journeys/modelers/basic_model.md", - "Keep scientific kernels readable" => "./guides/modelers/port_existing_model.md", - "Repository layout and test pyramid" => "./guides/modelers/repository_and_tests.md", - "Cross-object values" => "./journeys/modelers/cross_object_values.md", - "Choose a coupling mechanism" => "./guides/coupling.md", - "Model compatibility and replacement" => "./step_by_step/model_switching.md", - "Environment and cadence traits" => "./journeys/modelers/environment_and_cadence.md", - "Hard dependencies" => "./journeys/modelers/hard_dependencies.md", - "Mutable environment controllers" => "./journeys/modelers/mutable_environment.md", - "Stateful models" => "./guides/modelers/stateful_models.md", + "Check and troubleshoot" => [ + "Common errors" => "troubleshooting/common_errors.md", + "Inspect a simulation" => "troubleshooting/runtime_contracts.md", + "Dependency cycles" => "troubleshooting/dependency_cycles.md", + "Numerical reliability" => "guides/data/numerical_reliability.md", + "Parameter fitting" => "working_with_data/fitting.md", ], - "Reference" => [ - "Installing PlantSimEngine" => "./prerequisites/installing_plantsimengine.md", - "Julia language basics" => "./prerequisites/julia_basics.md", - "Why Julia ?" => "./introduction/why_julia.md", + "Reference and tools" => [ + "Julia language basics" => "prerequisites/julia_basics.md", + "Why Julia?" => "introduction/why_julia.md", + "How multiscale models execute" => "guides/multiscale/concepts.md", "Model execution" => "model_execution.md", "Model traits" => "model_traits.md", - "Collecting and plotting outputs" => "./guides/data/outputs_plotting.md", - "Forcing observations" => "./guides/data/forcing_observations.md", - "Numerical reliability" => "./guides/data/numerical_reliability.md", - "Parameter fitting" => "./working_with_data/fitting.md", - "Graph editor" => "./guides/graph_visualizer_editor.md", - "Common errors" => "./troubleshooting/common_errors.md", - "Runtime contracts" => "./troubleshooting/runtime_contracts.md", - "Dependency cycles" => "./troubleshooting/dependency_cycles.md", - "Downstream testing" => "./troubleshooting_and_testing/downstream_tests.md", - "Environment backend extensions" => "./guides/extensions/environment_backends.md", - "AI agent skill" => "agent_skill.md", - "Loaded model catalog" => "./API/model_catalog.md", - "Public API" => "./API/API_public.md", - "Public symbol inventory" => "./API/public_symbols.md", - "Example models" => "./API/API_examples.md", + "Graph editor" => "guides/graph_visualizer_editor.md", + "Environment backend extensions" => "guides/extensions/environment_backends.md", + "Find available models" => "API/model_catalog.md", + "Public API" => "API/API_public.md", + "Public symbol inventory" => "API/public_symbols.md", + "Example models" => "API/API_examples.md", ], - "Migration" => [ - "From the mapping runtime" => "migration_composite_model.md", - ], - "Maintainers" => [ + "Contribute and migrate" => [ "Developer guidelines" => "developers.md", - "Internal API" => "./API/API_private.md", - "Public API refinement decisions" => "./dev/public_api_refinement_decisions.md", - "Public API refinement completion audit" => "./dev/public_api_refinement_completion_audit.md", - "Composite model/object design" => "./dev/composite_model_design.md", - "Distributed output ownership" => "./dev/distributed_output_ownership.md", - "Composite model/object implementation plan" => "./dev/composite_model_implementation_plan.md", - "Composite model/object completion audit" => "./dev/composite_model_completion_audit.md", - "MAESPA-style composite-model example handoff" => "./dev/maespa_model_handoff.md", - "Code cleanup audit" => "./dev/code_cleanup_audit.md", - "Release notes handoff" => "./dev/release_notes_handoff.md", + "Internal API" => "API/API_private.md", + "From the mapping runtime" => "migration_composite_model.md", "Roadmap" => "planned_features.md", ], ] ) +include(joinpath(@__DIR__, "check_static_export.jl")) +finish_static_export() + if get(ENV, "PLANTSIMENGINE_DOCS_BUILD_ONLY", "false") != "true" deploydocs(; repo="github.com/VirtualPlantLab/PlantSimEngine.jl.git", diff --git a/docs/model_source.jl b/docs/model_source.jl new file mode 100644 index 000000000..c9835736c --- /dev/null +++ b/docs/model_source.jl @@ -0,0 +1,23 @@ +module DocsSources + +using Markdown +using PlantSimEngine + +"""Render an exact source section, failing if its start or end marker moved.""" +function section(relative_path, from, to=nothing) + path = joinpath(pkgdir(PlantSimEngine), relative_path) + source = read(path, String) + starts = findall(from, source) + length(starts) == 1 || error("Expected one start marker in $relative_path: $from") + first_index = first(only(starts)) + last_index = lastindex(source) + if !isnothing(to) + stop = findnext(to, source, last(only(starts)) + 1) + isnothing(stop) && error("Missing end marker in $relative_path: $to") + last_index = prevind(source, first(stop)) + end + code = strip(source[first_index:last_index]) + return Markdown.MD([Markdown.Code("julia", code)]) +end + +end diff --git a/docs/src/API/API_examples.md b/docs/src/API/API_examples.md index e9e989266..f9620d22f 100644 --- a/docs/src/API/API_examples.md +++ b/docs/src/API/API_examples.md @@ -1,11 +1,15 @@ # Example models -PlantSimEngine provides example processes and models to users. They are available from a sub-module called `Examples`. To get access to these models in a working environment with PlantSimEngine, you can simply use this sub-module: +PlantSimEngine includes models for learning and testing. Load them with: ```julia using PlantSimEngine.Examples ``` +These examples show how to write equations and connect models. Check their +assumptions before using them in a scientific study. Start with +[your first simulation](../journeys/users/one_object.md) for a guided example. + ## List ```@index diff --git a/docs/src/API/API_private.md b/docs/src/API/API_private.md index 40b584bd8..73dd17933 100644 --- a/docs/src/API/API_private.md +++ b/docs/src/API/API_private.md @@ -1,7 +1,13 @@ # API - internal functions ## Un-exported -Private functions, types or constants from `PlantSimEngine`. These are not exported, so you need to use `PlantSimEngine.` to access them (*e.g.* `PlantSimEngine.DataFormat`). Most of them are developer code, but some may be useful for tinkerers, or to have greater control over some simulation parameters (future versions of this documentation might break those categories into separate pages for clarity). +This reference is for people working on PlantSimEngine itself. The names +below are internal functions, types, and constants. They may change as the +implementation develops. + +For building a simulation, use the [public API](API_public.md). To inspect +its connections and results, use the +[simulation reports](../troubleshooting/runtime_contracts.md). ## Index diff --git a/docs/src/API/API_public.md b/docs/src/API/API_public.md index 69afc094b..8221b9e1f 100644 --- a/docs/src/API/API_public.md +++ b/docs/src/API/API_public.md @@ -1,129 +1,154 @@ # Public API +This reference lists the functions for building, running, and inspecting a +simulation. For a first example, start with +[Couple Models On One Object](@ref). + +An **object** is one part of your simulated system, such as a plant or leaf. +Its **status** holds its changing values. A **model application** is a model +configured with a name, selected objects, and input or timing settings. +An input **binding** connects a model to the value it reads. The **carrier** +holds that connection, usually as a shared reference to the source value; +time-based inputs can instead read saved results. + ## Unified CompositeModel/Object API ### Scenario and model applications -- `CompositeModel` stores objects, model applications, instances, and environment. +- `CompositeModel` stores the objects, their model applications, reusable plant + instances, and environmental data or providers. - `CompositeModel(model, models...; status=..., timestep=..., type_promotion=..., status_transform=...)` is the concise one-object form and - lowers to the same object/application representation. -- `Object` represents one runtime entity with stable identity and status. -- `object_id(model, source)` resolves an `ObjectId`, registered `Object` or - `Status`, MTG node, or raw identifier against the live registry. MTG nodes - retain the exact identity assigned by the model's `id=` accessor during - adaptation or organogenesis; `object_id` does not reevaluate that accessor, - and copied or foreign nodes are rejected. The same methods accept a - `RunContext` or `Simulation`. -- `CompositeModelTemplate` and `ObjectInstance` reuse a model across instances. + creates one object and its model applications. +- `Object` represents one entity, such as a plant or organ, with an identifier + that stays the same and its own status. +- `object_id(model, source)` finds an object's identifier in the model's + registry, the collection of registered objects. `source` can be an + `ObjectId`, registered `Object` or `Status`, MTG node, or raw identifier. + MTG nodes keep the identifier assigned by the model's `id=` function when + the MTG was imported or the organ was created. `object_id` does not call + that function again, and rejects copied nodes or nodes from another model. + The same methods accept a `RunContext` or `Simulation`. +- `CompositeModelTemplate` and `ObjectInstance` reuse a set of model + definitions for several plants or other repeated objects. - `ModelSpec(model; name=..., on=..., inputs=..., calls=..., outputs_to=..., - every=..., environment=..., output_routing=..., updates=...)` is the one - application construction form. + every=..., environment=..., output_routing=..., updates=...)` configures a + model application. ### Coupling -- `ModelSpec(...; inputs=...)` declares value dependencies. -- `bound_input(context, :name)` opts a model kernel into an identity-aware - `BoundMany` view for one of its declared `Many` inputs; `object_ids(view)` - returns the aligned object identities without copying them. -- `ModelSpec(...; calls=...)` declares manually executable child models. +- `ModelSpec(...; inputs=...)` describes where a model's inputs come from. +- `bound_input(context, :name)` gives a model access to both the values and + source objects of a declared `Many` input through a `BoundMany` view. + `object_ids(view)` returns the source identifiers in the same order as the + values, without copying them. +- `ModelSpec(...; calls=...)` declares models that this model can run from + inside its own calculation. - `ModelSpec(...; outputs_to=(name=OutputTo(selector; vars=...),))` - declares status variables owned by the application but stored on selected - destination objects. Each variable uses `Required(T)` or `Default(value)`; - the compiler resolves identities and rejects ambiguous writers before - initializing statuses. -- `output_targets(context, :name)` returns the compiled [`OutputTargets`](@ref) - view for one named `outputs_to` group. Destination columns are exposed - explicitly as `targets.columns.`, and `object_ids(targets)` returns - their aligned, read-only identities. + declares variables that this application writes into other selected objects' + statuses. Each variable uses `Required(T)` or `Default(value)`. Before + initializing the statuses, PlantSimEngine finds the destination objects and + checks that competing applications do not write the same value. +- `output_targets(context, :name)` returns an [`OutputTargets`](@ref) view + for one named `outputs_to` group. Read or write a variable's destination + values through `targets.columns.`. `object_ids(targets)` returns + their identifiers in the same order; those identifiers are read-only. - `assign_outputs!(targets, table; id=:object_id)` assigns a - Tables.jl-compatible result by identity. The lower-level + Tables.jl-compatible result to objects using their identifiers. The `assign_outputs!(targets, ids, columns)` overload accepts an ID vector and a `NamedTuple` of columns directly. -- `Updates(:variable; after=:application_id)` orders intentional duplicate writers. -- `Input(...)` and `Call(...)` express model defaults through `dep(model)`. +- `Updates(:variable; after=:application_id)` sets the order when several + applications deliberately update the same variable. +- `Input(...)` and `Call(...)` describe a model's default input connections + and calls through `dep(model)`. - `Initializer(One(application=:name, ...))` declares one normally scheduled application that may initialize a newly registered object during its creation event. -- `run_call!(context, :name; publish=false)` executes every resolved hard-call - target and always returns a vector-like `CallTargets` collection. +- `run_call!(context, :name; publish=false)` runs every model and object + selected by that named call. Each such pair is a **call target**. The result + is always a vector-like `CallTargets` collection. - `run_call!(context, :name; sampled_environment=value)` forwards one already - sampled model-facing environment through cached typed execution batches. -- `call_model(context, :name)` returns the concrete model when a call resolves - to exactly one target. -- `call_targets(context, :name)` returns the same non-executing collection for - fine-grained execution with `run_call!(target; ...)`. -- `run_initializer!(context, :name, object)` runs an `Initializer` binding once - on that newborn object, initializes canonical local status without an extra - mid-step output sample, and returns its canonical `Status`. It is not a - trial-call or existing-object API. - -Distributed assignment requires exact destination coverage. Every selected -object ID must occur exactly once and every declared output column must be -present; additional table or `NamedTuple` columns are treated as metadata and -ignored. Result columns may alias destination storage only for direct -self-assignment of the same column in exact destination order. - -Obtain `OutputTargets` inside each model invocation and do not retain it across -a lifecycle barrier. Reusing the same ID-column object lets PlantSimEngine -reuse its compiled row permutation and promises that the IDs and their order -have not been mutated. Replace the ID-column object when either changes. + prepared set of environmental values to the selected models. It uses the + execution groups already prepared by PlantSimEngine. +- `call_model(context, :name)` returns the model when a call selects exactly + one target. +- `call_targets(context, :name)` returns those targets without running them, + so you can choose individual targets to run with `run_call!(target; ...)`. +- `run_initializer!(context, :name, object)` runs a declared `Initializer` + once on a newly created object. It sets values in that object's main stored + status and returns that `Status`, without adding an output-history sample + partway through the step. Use it only for initialization during object + creation, not for trial calls or existing objects. + +When assigning outputs to several objects, include every selected object ID +exactly once and provide every declared output column. Additional table or +`NamedTuple` columns are treated as metadata and ignored. A result column +may share storage with a destination column only when assigning that column +to itself in exactly the destination order. + +Obtain `OutputTargets` each time the model runs. Do not keep it for later +calls after changes to the objects have been processed. If you reuse the +same ID-column object, PlantSimEngine reuses the correspondence it calculated +between result rows and destination objects. This requires the IDs and their +order to remain unchanged. Supply a new ID-column object if either changes. ### Model input schema -- `Required(T)` declares an input that object state or another application must - supply. `T` is an expected type and may be generic. -- `Default(value)` declares a true model fallback that needs no user - initialization. +- `Required(T)` declares an input that you must supply in the object's status + or connect to another model. `T` is the expected type and may be generic. +- `Default(value)` supplies a model's fallback value when no input is provided. - `inputs_(model)` uses only these explicit declarations; plain literals are rejected. -- `outputs_(model)` literals remain initial output-state values. -- `init_variables(model)` returns only genuine input defaults and initial +- `outputs_(model)` gives the initial values of outputs. +- `init_variables(model)` returns only input defaults and initial output values. -- `VariableContract` records a variable's unit, spatial or object basis, - temporal basis, aggregation meaning, and intensive/extensive character - without wrapping its runtime value. -- `variable_contracts(model)` returns validated declarations from the - package-extension trait `PlantSimEngine.variable_contracts_`. A compiled - producer-consumer binding must have identical contracts once either side - declares one. +- `VariableContract` describes units and physical meaning: for example, + whether a variable is per plant or per square metre, a rate or a daily + total, and whether amounts from several objects can be added. The description + is stored separately from the numerical value. +- `variable_contracts(model)` returns checked declarations from + `PlantSimEngine.variable_contracts_`, which model packages implement. + When an input is connected to another model's output, their contracts must + be identical if either model declares one. ### Status representation - `CompositeModel(...; type_promotion=Dict(Float64 => Float32))` converts every - matching status value with `convert` when its storage is materialized. + matching status value with `convert` when the value's storage is created. - `CompositeModel(...; status_transform=(variable, value) -> ...)` applies a precise transformation based on the status variable name and value. The - returned value becomes the candidate for the general `type_promotion` - mapping, so the transform always runs first. + returned value is then checked against the `type_promotion` mapping, so + `status_transform` always runs first. - Ordinary numeric arrays are converted element by element when their elements match a mapping rule. Their shape is preserved. - The policy covers supplied object statuses, model input and output defaults, - and statuses of objects registered later through the lifecycle API. + and statuses of objects added later through the object-creation functions. - The policy is limited to status values. Model parameters, environment values, constants, object labels, and topology are not converted. -- Conversion occurs during status materialization or object registration, not - on every call to a model kernel. +- Conversion occurs when status storage is created or an object is registered, + not every time the model's equation runs. - `Diagnostics.explain_initialization(model)` reports `declared_type`, `original_type`, `transformed_type`, and `effective_type`, plus flags and the selected mapping rule for each initialized value. -The effective status type must be supported by the model kernel. Generic -`Required` declarations and generic computations allow the same model to use -`Float32`, uncertainty-carrying numbers, or another compatible numeric type. +The model's calculation must support the resulting numerical type. Keeping +`Required` declarations and equations open to different types allows the same +model to use `Float32`, numbers with uncertainty estimates, or another +compatible numerical type. See [Numerical Reliability](../guides/data/numerical_reliability.md) for complete examples. ### Selectors -- Multiplicity: `One(...)`, `OptionalOne(...)`, and `Many(...)`. -- Scope: `SceneScope()`, `Self()`, `Subtree()`, `SelfPlant()`, +- Number of matches: `One(...)`, `OptionalOne(...)`, and `Many(...)`. +- Where to look: `SceneScope()`, `Self()`, `Subtree()`, `SelfPlant()`, `Ancestor(...)`, and `Scope(name)`. - Label criteria: `kind=...`, `species=...`, `scale=...`, and `name=...`. -- Topology relations: `Relation(...)`. +- Connections between objects: `Relation(...)`. -`Self()` always means the current object: the object on which the consuming -application runs. It means a plant only when that object is itself the plant. +`Self()` always means the current object: the object on which the model +reading the input runs. It means a plant only when that object is itself +the plant. Selector fields are checked where the selector is used: @@ -136,60 +161,76 @@ Selector fields are checked where the selector is used: | object queries and `OutputRequest` selectors | object criteria only | Unsupported or misspelled fields fail when the selector is constructed. -Object-relative scopes and relations require a current object, so they belong -in inputs, calls, or contextual object/output queries rather than application -targets. +Selections such as descendants or ancestors need a current object to start +from. Use them in inputs, calls, or object/output queries with that context. +They cannot select where an application runs through `ModelSpec(...; on=...)`. ### Time and environment -- `ModelSpec(...; every=period)` sets an application cadence. -- `HoldLast`, `Interpolate`, `Integrate`, and `Aggregate` define temporal - input policies. -- `Environment(...)` configures environment providers and source remapping. -- Models declare sampled environment variables with `environment_inputs_`. -- Mutable environment controllers pass trial state with - `run_call!(context, name; environment=trial_state)` and commit accepted state - with `commit_environment!`. -- `OutputRequest(selector, variable; ...)` selects retained and optionally - resampled streams using the same object selector grammar. +- `ModelSpec(...; every=period)` sets how often an application runs. +- `HoldLast`, `Interpolate`, `Integrate`, and `Aggregate` describe how an input + uses results over time: keep the last value, interpolate, integrate, or + combine values over an interval. +- `Environment(...)` chooses where environmental data comes from and can + map source variable names to the names a model expects. +- Models list the environmental variables they read in `environment_inputs_`. +- A model that tries changes to its environment passes trial values with + `run_call!(context, name; environment=trial_state)`. It stores the accepted + values with `commit_environment!`. +- `OutputRequest(selector, variable; ...)` selects results to save and can + resample them at a chosen interval. It uses the same selectors as object + queries. ### Lifecycle -- `objects_from_mtg` and `CompositeModel(mtg; ...)` adapt an MTG into the object - registry. -- `add_organ!` creates and initializes a new organ in an MTG-backed model. -- `runtime_model(context)` gives lifecycle-capable kernels sanctioned access to - the live model from their `RunContext`. +- `objects_from_mtg` and `CompositeModel(mtg; ...)` create registered objects + from a MultiScaleTreeGraph (MTG). +- `add_organ!` creates and initializes a new organ when the model uses an MTG. +- `runtime_model(context)` gives a model's `run!` function access to the + running `CompositeModel`, for example to add or remove objects. - `object_id(context)`, `model_object(context)`, `model_status(context)`, and - `source_node(context)` resolve the current execution target. The status - accessor returns canonical registry state rather than the application-local - status view passed to a kernel. + `source_node(context)` return the current object's identifier, object, + status, and source MTG node, respectively. `model_status` returns the main + status stored for that object. The `status` argument passed to `run!` is + instead the view of variables used by that particular application. - `register_object!`, `remove_object!`, and `reparent_object!` change - topology. -- `move_object!` and `update_geometry!` change spatial state. -- Supported lifecycle operations automatically invalidate and refresh the - affected structural or spatial bindings before the next timestep. -- A creator that must run an application which already completed on existing - objects declares an `Initializer` call. The compiler orders the scheduled - target before the creator and the creator before direct non-temporal - same-step consumers; - `run_initializer!` admits exactly one target from the current pure-addition - event and rejects repeat, existing, reparented, manual-call, and - refresh-fallback execution. Each initialized output must have one potential - canonical writer across local and distributed destinations. Because - `run_initializer!` emits no mid-step stream sample, - downstream temporal consumers of a possible newborn output are rejected at - compilation; a `PreviousTimeStep` input used by the initializer itself - remains supported. -- `run!(model; steps=..., outputs=:none)` starts a fresh result timeline and + the objects and their parent relationships. +- `move_object!` and `update_geometry!` change position or geometry. +- These functions mark affected connections for updating. Changes to object + relationships are processed after the application that made them, so new + objects can run applications still remaining in the same time step. + Changes made between steps are processed before the next step. +- `Initializer` lets a model initialize an object it has just created, using + an application that already ran on existing objects. Its restrictions are + detailed below. +- `run!(model; steps=..., outputs=:none)` starts a fresh simulation history and returns a `Simulation`. - `continue!(simulation; steps=...)` and `step!(simulation)` advance an - existing timeline without resetting temporal state. -- `current_step(simulation)` reports the accepted timeline position. -- `final_state(simulation)` returns a latest-state snapshot without - requiring output retention; pass an object id or selector for multi-object - simulations. -- `collect_outputs(sim)` materializes retained output streams. + existing simulation, preserving the values needed for time-based inputs. +- `current_step(simulation)` reports the latest completed time step. +- `final_state(simulation)` returns a snapshot of the latest values even + when output history was not saved. Pass an object id or selector for + multi-object simulations. +- `collect_outputs(sim)` gathers saved results into rows for analysis. + +**Initializing objects during growth.** An `Initializer` application runs +before the model that creates new objects. Models that directly read the new +values run after the creator in the same step. The following restrictions +keep those new values consistent with the rest of the simulation: + +- `run_initializer!` accepts exactly one target from the current creation + event, and that event must only add objects. It rejects repeated + initialization, existing or reparented objects, and ordinary manual-call + bindings. It also rejects cases that require a full connection rebuild + instead of the update limited to the new objects. +- Each initialized output must have exactly one possible application writing + its main stored value. This check counts both local outputs and outputs + written to other objects. +- Initialization adds no output sample partway through a step. Models that + read the new values directly can use them in that step, but PlantSimEngine + rejects downstream time-based inputs that could read a newly created + object's output. The initializer itself can still use a `PreviousTimeStep` + input. ### Explanations @@ -218,88 +259,103 @@ translations from removed APIs. ### Model authoring and scenario validation -Use the neutral `Authoring` namespace for model discovery and machine-readable -validation: +Use `Authoring` to find models and inspect their definitions. Its reports +can also be read by tools such as an AI coding agent: - `Authoring.available_processes()` and `Authoring.available_models(...)` - discover models from loaded Julia modules; -- `Authoring.describe_model(instance)` records explicit process identity plus - the parameter values, ports, contracts, dependencies, traits, metadata, and - source location of a concrete instance. Its nested `field_provenance` - separately marks exact or declared model information, inferred source - information, and the independent provenance of constructor fields, defaults, - and methods; -- `Authoring.describe_model(ModelType)` is explicitly best effort and returns - an incomplete report when no real zero-argument constructor exists. It never - fabricates parameter values or constructs a dummy instance; + find models in loaded Julia modules; +- `Authoring.describe_model(instance)` reports the model's process, current + parameter values, inputs and outputs, variable contracts, input connections + and calls, execution settings, descriptive information, and source location. + Its nested `field_provenance` explains where each fact came from: the actual + model, an explicit declaration, or information inferred from the source. + The origins of constructor fields, defaults, and methods are reported + separately; +- `Authoring.describe_model(ModelType)` reports whatever can be determined + from the type. If it has no constructor that can be called without + arguments, the report is incomplete. It never invents parameter values + or creates a dummy instance; - current values from `Authoring.describe_model(instance)` stay in `parameters`; they are never relabeled as constructor defaults. Defaults are - inspected only from a real zero-argument type description; -- `Authoring.model_interface(instance)` returns the exact interface enforced - for object and instance overrides; -- `Authoring.model_interface(ModelType)` is best effort only when that type has - a real zero-argument constructor; otherwise it raises `ArgumentError` rather - than inventing parameter values; -- `Authoring.compare_models(a, b)` distinguishes common process identity from - direct override compatibility, binding changes, and other scenario - reconfiguration. Inspect `requires_binding_changes` for interface differences - that affect binding configuration and `requires_reconfiguration` for any - difference that prevents a direct override; each structured difference + inspected from a type description only when a constructor can actually be + called without arguments; +- `Authoring.model_interface(instance)` returns the declarations checked + when replacing a model with `Override` for an object or plant instance; +- `Authoring.model_interface(ModelType)` attempts the same inspection using + a constructor with no arguments. If no such constructor exists, it raises + `ArgumentError` rather than inventing parameter values; +- `Authoring.compare_models(a, b)` reports whether two models share a process, + whether one can directly replace the other, and what settings would need to + change. `requires_binding_changes` reports differences in inputs, outputs, + variable contracts, dependencies, output policies, or environmental + connections. `requires_reconfiguration` covers every + difference preventing a direct override. Each reported difference records its `path`, `kind`, values, `affects_override`, and `affects_bindings`; -- `Authoring.validate_model(model; strict=false)` validates declarations - without executing the scientific kernel. Strict mode requires a complete - `VariableContract` for every declared port; -- `Authoring.validate_scenario(model; strict=false)` preserves a partial - compilation report and structured diagnostics for incomplete scenarios; -- `Authoring.to_dict(report)` and `Authoring.to_json(report)` expose the - versioned report schema without serializing compiler internals; +- `Authoring.validate_model(model; strict=false)` checks declarations + without running the equation. Strict mode requires a complete + `VariableContract` for every declared input and output, including + environmental variables; +- `Authoring.validate_scenario(model; strict=false)` checks the simulation + setup. If it is incomplete, the result still includes a partial report + and diagnostic information; +- `Authoring.to_dict(report)` and `Authoring.to_json(report)` convert reports + to dictionaries or JSON using a versioned format. They do not include + internal compiler objects; - `Authoring.scenario_source(model; environments=...)` reconstructs readable, - editable Julia scenario code. Pass named runtime environment values through + editable Julia simulation setup code. Pass named environment values through `environments` so the generated code can refer to them explicitly; -- `Authoring.compiled_model_source(model_or_simulation)` produces an executable, - readable view of the resolved application order, targets, input provenance, - calls, and invoked kernel bodies; +- `Authoring.compiled_model_source(model_or_simulation)` produces readable, + executable Julia code showing the chosen application order, selected + objects, input sources, model calls, and calculation functions; - `Authoring.write_compiled_model_source(path, value)` writes that view explicitly. -These functions validate declared structure and coupling. They do not infer -units, assumptions, references, domains of validity, or scientific -equivalence. The compiled source is an explanatory execution view over the -normal compiled runtime, not a second scheduler. Use `scenario_source` when the -goal is to edit or version the scenario declaration; use -`compiled_model_source` when the goal is to inspect what compilation resolved. -A package may extend `Authoring.model_metadata(model)` with explicit metadata -such as summary, hypothesis, references, and maturity. It may extend -`Authoring.parameter_metadata(model)` with descriptions, units, domains, -defaults, references, or constraints for the fields of the model type. +These functions check the declared models and their connections. They do not +guess units, assumptions, references, valid use conditions, or whether two +equations are scientifically equivalent. The generated execution code uses +the normal runtime; it does not create a separate way to schedule the models. + +Use `scenario_source` to edit or save the simulation setup in version +control. Use `compiled_model_source` to inspect the calculations and +connections PlantSimEngine prepared from that setup. + +A model package can implement `Authoring.model_metadata(model)` to supply a +summary, hypothesis, references, and development or validation status. It can +implement `Authoring.parameter_metadata(model)` to describe each parameter's +meaning, units, valid range, defaults, references, or other constraints. ### CompositeModel graph visualization and editing -- `GraphEditor.model_graph_view(model; level=:applications)` returns the typed graph view. -- `GraphEditor.model_graph_view_json(model)` serializes the same DTO used by the browser. +- `GraphEditor.model_graph_view(model; level=:applications)` returns graph + data describing the models and their connections. +- `GraphEditor.model_graph_view_json(model)` converts the same graph data + used by the browser to JSON. - `GraphEditor.write_model_graph_view(path, model)` writes a self-contained static viewer. -- `GraphEditor.edit_graph(model; templates=..., environments=...)` starts the optional HTTP editor after `using HTTP` and keeps catalog values authoritative in Julia. +- `GraphEditor.edit_graph(model; templates=..., environments=...)` starts the + optional HTTP editor after `using HTTP`. The editor uses the templates + and environment values supplied from Julia. - `GraphEditor.current_model(session)`, `GraphEditor.undo!(session)`, `GraphEditor.redo!(session)`, and `close(session)` control an interactive session from Julia. See [Visualize And Edit A CompositeModel](../guides/graph_visualizer_editor.md) for the -runnable workflow, model discovery, selector previews, cycle breaking, and -Documenter embedding. +runnable workflow, finding models, previewing selected objects, handling +dependency cycles, and embedding a graph in Documenter pages. ### Environment backend extensions -Backend packages extend the protocol under `EnvironmentAPI`, including +Packages that provide environmental data implement functions under +`EnvironmentAPI`, including `EnvironmentAPI.AbstractEnvironmentBackend`, `EnvironmentAPI.bind_environment`, `EnvironmentAPI.sample`, `EnvironmentAPI.commit_environment!`, and `EnvironmentAPI.update_index!`. -The root-level `commit_environment!` remains part of the ordinary model-kernel -workflow for committing an accepted controller state. +The root-level `commit_environment!` is the function a model calls to store +accepted environmental values after a trial calculation. ### Fitting and evaluation -Generic fitting and metrics live under `Evaluation`: `Evaluation.fit`, +Parameter fitting and evaluation metrics are available under `Evaluation`: `Evaluation.fit`, `Evaluation.RMSE`, `Evaluation.NRMSE`, `Evaluation.EF`, and `Evaluation.dr`. PlantMeteo reducers are accessed from `PlantMeteo` directly rather than being re-exported by PlantSimEngine. @@ -310,11 +366,11 @@ re-exported by PlantSimEngine. PlantSimEngine.Advanced ``` -Compiler representations, cache refresh operations, and low-level binding -compilers live under `PlantSimEngine.Advanced`. They are intended for package -integration, diagnostics development, and compiler work rather than ordinary -scenario composition. Prefer `Diagnostics.explain_*`, which accepts a -`CompositeModel` directly, over manually compiling and inspecting fields. +`PlantSimEngine.Advanced` contains the compiler's data structures and functions +for preparing connections and refreshing cached information. Use it when +integrating a package or developing the compiler and its diagnostics. For +ordinary simulations, use `Diagnostics.explain_*` with a `CompositeModel` +to inspect the setup. Examples include `Advanced.compile_composite_model`, `Advanced.refresh_bindings!`, and the `Advanced.CompiledCompositeModel` family. These qualified APIs may evolve more diff --git a/docs/src/API/model_catalog.md b/docs/src/API/model_catalog.md index 254aad5c7..0b07f8394 100644 --- a/docs/src/API/model_catalog.md +++ b/docs/src/API/model_catalog.md @@ -1,127 +1,111 @@ # Loaded model catalog -This catalog is generated from the Julia modules loaded by the documentation -build. It is not a manually maintained registry: downstream packages appear -after they are loaded, and a type without a zero-argument constructor remains -visible as an incomplete, best-effort description. +Start with the scientific process you need, then choose a model and inspect +its requirements. PlantSimEngine can list models from packages already loaded +in your Julia session. It does not search all installed or available packages. -```@example loaded-model-catalog -using DataFrames -using PlantSimEngine +## Choose where to start -rows = NamedTuple[] -descriptions = Authoring.ModelDescription[] -for process_type in Authoring.available_processes() - model_types = Authoring.available_models(process_type) - if isempty(model_types) - push!(rows, ( - process=missing, - process_type=string(process_type), - model="", - package=missing, - provenance=:unavailable, - complete=false, - parameter_provenance=:unavailable, - diagnostics="no concrete model loaded", - )) - continue - end +| You want to… | Start here | +|---|---| +| Learn the interface with small examples | `PlantSimEngine.Examples` and [one-object simulation](../journeys/users/one_object.md) | +| Work on leaf gas exchange or energy balance | [PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl) and its model documentation | +| Write a new equation | [New process or new model?](@ref) | +| Compare two implementations | [Model compatibility and replacement](@ref) | - for model_type in model_types - description = Authoring.describe_model(model_type) - push!(descriptions, description) - parameter_field = description.field_provenance.parameters - push!(rows, ( - process=description.process, - process_type=something(description.process_type, ""), - model=description.model_type, - package=something(description.package, ""), - provenance=description.provenance, - complete=description.complete, - parameter_provenance=parameter_field isa NamedTuple ? - parameter_field.values : parameter_field, - diagnostics=join( - string.(getfield.(description.diagnostics, :code)), - ", ", - ), - )) - end -end +The `Toy...` models in these tutorials are teaching examples. Their presence +in a catalog does not establish scientific validation. -catalog = DataFrame(rows) -sort!(catalog, [:process_type, :model]) -catalog +## List a process's models + +After loading a package, list its process types with +`Authoring.available_processes()`. For a known process, request its models: + +```@example loaded-model-catalog +using PlantSimEngine, DataFrames +using PlantSimEngine.Examples + +Authoring.available_models(AbstractGrowthModel) ``` -`provenance=:best_effort` means the row was requested from a type. When -`complete=false`, inspect `diagnostics` and pass the concrete instance used by -the scenario to `Authoring.describe_model(instance)` before making decisions -about its parameters or interface. The nested `parameter_provenance` column -also distinguishes exact values from declared metadata and unavailable data. +In your own session, load the relevant scientific package first. The table on +this website reflects the documentation build's session only. -## Port and scientific-contract catalog +## Inspect a model you might use -The long table below is generated from each `ModelDescription.ports` entry. -Missing values remain missing: an incomplete type description produces an -explicit `:unavailable` row rather than guessed ports or contracts. +Construct a real model with explicit parameters. This avoids guessing the +defaults of a type that requires arguments. ```@example loaded-model-catalog -port_rows = NamedTuple[] -for description in descriptions - port_field = description.field_provenance.ports - declaration_provenance = port_field isa NamedTuple ? - port_field.declarations : port_field - contract_provenance = port_field isa NamedTuple ? - port_field.contracts : port_field - - if isempty(description.ports) - availability = description.complete ? :none : :unavailable - push!(port_rows, ( - process=description.process, - model=description.model_type, - complete=description.complete, - role=availability, - port=availability, - declaration=availability, - expected_type=string(availability), - unit=missing, - basis=missing, - temporal=missing, - aggregation=missing, - extent=missing, - declaration_provenance=declaration_provenance, - contract_provenance=contract_provenance, - )) - continue - end +candidate = ToyRUEGrowthModel(0.2) +description = Authoring.describe_model(candidate) + +( + model=description.model_type, + process=description.process, + parameters=description.parameters, + inputs=inputs(candidate), + outputs=outputs(candidate), +) +``` + +Read the package documentation to understand the equations, parameter units, +assumptions, and conditions where the model has been tested. The report only +shows the information its author has supplied. + +`variable_contracts(candidate)` shows the units and physical meaning recorded +for each variable. These declarations are called **variable contracts**. If +one side of a connection has a contract, the other side must have the same +one. Ask the model author to add missing declarations. If the quantities +differ, for example a value per plant and a value per ground area, use a +separate model to perform the conversion. + +## Check whether a candidate fits your simulation + +1. Confirm that its inputs can come from your data, environment, or other models. +2. Check that connected values have the same units, refer to the same area + or object, and describe the same time period. Check whether each is a + total, an average, or a rate. +3. Use `Authoring.compare_models(current, candidate)` when replacing a model. +4. Validate the assembled scenario with `Authoring.validate_scenario`, then + check a small run against an expected result. + +See [Coupling models](@ref) for connection choices and +[Model compatibility and replacement](@ref) for a complete comparison. + +## Reference: models visible during this build - for port in description.ports - contract = port.variable_contract - push!(port_rows, ( - process=description.process, - model=description.model_type, - complete=description.complete, - role=port.role, - port=port.name, - declaration=port.declaration, - expected_type=port.expected_type, - unit=isnothing(contract) ? missing : contract.unit, - basis=isnothing(contract) ? missing : contract.basis, - temporal=isnothing(contract) ? missing : contract.temporal, - aggregation=isnothing(contract) ? missing : contract.aggregation, - extent=isnothing(contract) ? missing : contract.extent, - declaration_provenance=declaration_provenance, - contract_provenance=contract_provenance, +The following table is generated from the loaded modules. `complete=false` +means a type could not provide a complete description, for example because +it needs parameter values before it can be created. Create a model with those +parameters and inspect it before choosing it. The `provenance` column records +where the description came from: the author's declarations or information +found by examining the code. Detailed reports give this source for each field. + +```@setup loaded-model-catalog +rows = NamedTuple[] +for process_type in Authoring.available_processes() + for model_type in Authoring.available_models(process_type) + model_description = Authoring.describe_model(model_type) + push!(rows, ( + process=model_description.process, + model=model_description.model_type, + package=something(model_description.package, ""), + complete=model_description.complete, + provenance=model_description.provenance, )) end end +catalog = DataFrame(rows) +sort!(catalog, [:package, :model]) +``` -port_catalog = DataFrame(port_rows) -sort!(port_catalog, [:process, :model, :role, :port]) -port_catalog +```@example loaded-model-catalog +catalog ``` -The same pattern can generate a package-specific process page after loading -that package. Filter the table by `package`, then enrich the human-facing page -with assumptions, equations, references, domain of validity, and scientific -validation evidence; Authoring deliberately does not infer those claims. +To reproduce this discovery yourself, loop over +`Authoring.available_processes()` and call +`Authoring.available_models(process_type)` for each process. Pass a concrete +model, such as `ToyRUEGrowthModel(0.2)`, to `Authoring.describe_model` for its +parameters, variables, physical meanings, and any problems found. diff --git a/docs/src/API/public_symbols.md b/docs/src/API/public_symbols.md index 04d068a8e..ed9b60022 100644 --- a/docs/src/API/public_symbols.md +++ b/docs/src/API/public_symbols.md @@ -1,150 +1,159 @@ # Public Symbol Inventory -This page records the supported default namespace and the five focused public -submodules. Compiler representations and cache controls are intentionally -listed separately under [`PlantSimEngine.Advanced`](#advanced-namespace). - -`using PlantSimEngine` imports the ordinary model-author and simulation-user -workflow plus the `Authoring`, `Diagnostics`, `GraphEditor`, `EnvironmentAPI`, -and `Evaluation` module names. Their members remain qualified unless a user -explicitly imports one of those submodules. +This page lists public names by purpose. Names for compiler data structures +and cached information are listed separately under +[`PlantSimEngine.Advanced`](@ref "Advanced namespace"). + +`using PlantSimEngine` makes the usual modeling and simulation functions +available, along with the `Authoring`, `Diagnostics`, `GraphEditor`, +`EnvironmentAPI`, and `Evaluation` module names. Functions in those modules +keep their prefix, such as `Diagnostics.explain_bindings`, unless you import +the module's functions explicitly. + +An object's **status** stores its changing values. A **model application** +configures a model's name, objects, connections, and timing. An input +**binding** connects a model to a source value, and its **carrier** holds +that connection, usually through a shared reference. The [Public API](@ref) +explains the functions and their requirements in detail. ## Scenario composition -- CompositeModel structure: `CompositeModel`, `Object`, `ObjectId`, `CompositeModelTemplate`, +- Building a simulation: `CompositeModel`, `Object`, `ObjectId`, `CompositeModelTemplate`, `ObjectInstance`, `Override`. -- Applications: `ModelSpec`, `OutputTo`, `Environment`, and `Updates`. -- Application inspection: `application_name`, `applies_to`, `value_inputs`, +- Configuring model applications: `ModelSpec`, `OutputTo`, `Environment`, and `Updates`. +- Inspecting application settings: `application_name`, `applies_to`, `value_inputs`, `model_calls`, `outputs_to`, `environment_config`, `output_routing`, `updates`. -- Dependency defaults: `Input`, `Call`, `Initializer`, `PreviousTimeStep`. +- Default input connections and calls: `Input`, `Call`, `Initializer`, `PreviousTimeStep`. ## Object selectors and queries -- Multiplicity: `One`, `OptionalOne`, `Many`. -- Scope and topology: `SceneScope`, `Self`, `Subtree`, `SelfPlant`, `Ancestor`, +- Choosing the number of objects: `One`, `OptionalOne`, `Many`. +- Choosing where to look and how objects are connected: `SceneScope`, `Self`, `Subtree`, `SelfPlant`, `Ancestor`, `Scope`, `Relation`. - Label criteria are selector keywords: `kind`, `species`, `scale`, and `name`. -- Identity and queries: `object_id`, `object_ids`, `model_objects`, +- Finding objects and their identifiers: `object_id`, `object_ids`, `model_objects`, `resolve_object_ids`, `resolve_objects`. - Object data: `geometry`, `position`, `bounds`. ## Execution, lifecycle, and outputs -- Execution: `run!`, `continue!`, `step!`, `Simulation`, `current_step`, +- Running and advancing a simulation: `run!`, `continue!`, `step!`, `Simulation`, `current_step`, `runtime_model`, `final_state`. - Output selection and collection: `OutputRequest`, `outputs`, `collect_outputs`. -- Distributed output assignment: `OutputTargets`, `output_targets`, and - `assign_outputs!`. Access destination carriers through - `targets.columns.` and aligned identities through - `object_ids(targets)`. -- Lifecycle: `register_object!`, `add_organ!`, `remove_object!`, +- Writing results to several objects: `OutputTargets`, `output_targets`, and + `assign_outputs!`. Access each variable's destination values through + `targets.columns.` and their object identifiers, in the same + order, through `object_ids(targets)`. +- Adding, removing, or moving objects: `register_object!`, `add_organ!`, `remove_object!`, `reparent_object!`, `move_object!`, `update_geometry!`, `mark_environment_binding_dirty!`, `objects_from_mtg`. -- Hard calls: `RunContext`, `CallTarget`, `CallTargets`, `call_model`, +- Running another model from within a calculation: `RunContext`, `CallTarget`, `CallTargets`, `call_model`, `call_targets`, `run_call!`. -- Newborn initialization: `Initializer`, `run_initializer!`. +- Setting initial values when an object is created: `Initializer`, `run_initializer!`. ## Diagnostics namespace -`PlantSimEngine.Diagnostics` owns structured explanations and supported -inspection: +`PlantSimEngine.Diagnostics` explains how the simulation is set up and what +happened during execution: - Structure: `Diagnostics.explain_objects`, `Diagnostics.explain_instances`, `Diagnostics.explain_scopes`. -- Compilation: `Diagnostics.explain_applications`, `Diagnostics.explain_bindings`, +- Model connections and execution order: `Diagnostics.explain_applications`, `Diagnostics.explain_bindings`, `Diagnostics.explain_calls`, `Diagnostics.explain_output_bindings`, `Diagnostics.explain_writers`, `Diagnostics.explain_schedule`, `Diagnostics.explain_execution_plan`. - Initialization, environment, and outputs: `Diagnostics.explain_initialization`, `Diagnostics.explain_environment`, `Diagnostics.explain_environment_bindings`, `Diagnostics.explain_output_retention`, `Diagnostics.explain_outputs`. -- Supported carrier inspection: `Diagnostics.input_carrier`, `Diagnostics.input_value`, +- Inspecting an input's connection and current value: `Diagnostics.input_carrier`, `Diagnostics.input_value`, `Diagnostics.has_reference_carrier`. -- Normalized selector addresses: `Diagnostics.ObjectAddress`, +- Consistent descriptions of selected objects: `Diagnostics.ObjectAddress`, `Diagnostics.object_address`. ## Authoring namespace -`PlantSimEngine.Authoring` is the stable inspection surface for model authors -and agents: +`PlantSimEngine.Authoring` helps model authors and coding agents find, +inspect, and check models: -- Discovery: `Authoring.available_processes` and +- Finding loaded models: `Authoring.available_processes` and `Authoring.available_models`. -- Exact instance description: `Authoring.describe_model` and +- Describing a model with its chosen parameters: `Authoring.describe_model` and `Authoring.model_interface`. -- Alternative comparison: `Authoring.compare_models`, including separate +- Comparing alternatives: `Authoring.compare_models`, including separate `requires_binding_changes` and `requires_reconfiguration` results. -- Structural validation: `Authoring.validate_model` and +- Checking declarations and connections: `Authoring.validate_model` and `Authoring.validate_scenario`. -- Explicit scientific metadata: `Authoring.model_metadata` and +- Supplying scientific descriptions: `Authoring.model_metadata` and `Authoring.parameter_metadata`. -- Stable serialization: `Authoring.to_dict`, `Authoring.to_json`, and +- Converting reports to versioned dictionaries or JSON: `Authoring.to_dict`, `Authoring.to_json`, and `Authoring.SCHEMA_VERSION`. -- Editable scenario reconstruction: `Authoring.scenario_source`. -- Readable resolved execution: `Authoring.compiled_model_source` and +- Generating editable simulation setup code: `Authoring.scenario_source`. +- Showing the calculations and connections prepared for execution: `Authoring.compiled_model_source` and `Authoring.write_compiled_model_source`. - Typed reports: `Authoring.ModelDescription`, `Authoring.ModelComparison`, `Authoring.ModelValidationReport`, and `Authoring.ScenarioValidationReport`. -A description built from a concrete instance includes its explicit `process` -identity and exact model values. Inspect nested `field_provenance` because -declarations, source information, and constructor metadata have independent -origins. A type-only description is best effort and never invents constructor -arguments or a dummy instance. A type-only interface requires a real -zero-argument constructor. Authoring validation is structural; it does not -establish scientific validity. +A description of a model instance includes its declared `process` and +actual parameter values. The nested `field_provenance` records where each +piece of information came from; declarations, source information, and +constructor information can have different origins. + +When you supply a type rather than an instance, the description reports only +what can be determined. It never invents constructor arguments or creates a +dummy model. To obtain the model interface from a type, that type must have +a constructor that can be called without arguments. These checks concern +model definitions and connections; they do not prove scientific validity. ## Model-author contract - Model identity: `AbstractModel`, `@process`, `process`. -- State schema and initialization: `Status`, `Required`, `Default`, +- Declaring variables and initial values: `Status`, `Required`, `Default`, `VariableContract`, `variable_contracts`, `init_variables`, `dep`. -- Model IO inspection: `inputs`, `outputs`, `variables`, +- Inspecting inputs and outputs: `inputs`, `outputs`, `variables`, `environment_inputs`, `environment_outputs`, `validate_environment_inputs`. -- Identity-aware many-input access: `bound_input`, `BoundMany`, and +- Reading several input values together with their source object identifiers: `bound_input`, `BoundMany`, and `object_ids`. -- Timing and routing traits: `timespec`, `output_policy`, `timestep_hint`, +- Timing and environment settings: `timespec`, `output_policy`, `timestep_hint`, `environment_hint`, `environment_bindings`, `environment_window`. -The underscore declarations `inputs_`, `outputs_`, `environment_inputs_`, -`environment_outputs_`, and `variable_contracts_` are intentionally -unexported extension functions. -Model authors implement them with qualified definitions such as +Model authors implement `inputs_`, `outputs_`, `environment_inputs_`, +`environment_outputs_`, and `variable_contracts_` with the package prefix, such as `PlantSimEngine.inputs_(model) = ...`. `inputs_` must return explicit `Required(T)` or `Default(value)` declarations; `outputs_` returns initial -output-state values; `variable_contracts_` returns `VariableContract` metadata -for declared status or environment variables. +output values; `variable_contracts_` returns `VariableContract` descriptions +of declared status or environment variables. These functions ending in `_` +are not imported by `using PlantSimEngine`. ## Time and reducers -- Scheduling: `ClockSpec`, `SchedulePolicy`, `HoldLast`, `Interpolate`, +- Choosing when models run and how inputs combine values over time: `ClockSpec`, `SchedulePolicy`, `HoldLast`, `Interpolate`, `Integrate`, `Aggregate`. - Meteorology reducers are not re-exported. Use qualified PlantMeteo names, for example `PlantMeteo.MeanReducer` or `PlantMeteo.RadiationEnergy`. ## EnvironmentAPI namespace -- Backend contract: `EnvironmentAPI.AbstractEnvironmentBackend`, `EnvironmentAPI.EnvironmentContext`, +- Implementing a provider of environmental data: `EnvironmentAPI.AbstractEnvironmentBackend`, `EnvironmentAPI.EnvironmentContext`, `EnvironmentAPI.GlobalConstant`, `EnvironmentAPI.environment_backend`, `EnvironmentAPI.environment_variables`, `EnvironmentAPI.base_step_seconds`, `EnvironmentAPI.get_nsteps`, and `EnvironmentAPI.bind_environment`. -- Sampling and mutation: `EnvironmentAPI.sample`, +- Reading and updating environmental values: `EnvironmentAPI.sample`, `EnvironmentAPI.sample_environment`, `EnvironmentAPI.commit_environment!`, and `EnvironmentAPI.update_index!`. - PlantMeteo conveniences: `Atmosphere`, `Constants`, `Weather`. ## GraphEditor namespace -- Graph DTOs: `GraphEditor.ModelGraphView` and +- Graph data: `GraphEditor.ModelGraphView` and `GraphEditor.model_graph_view`. -- Serialization and static views: `GraphEditor.model_graph_view_json`, +- Saving graph data and displaying static graphs: `GraphEditor.model_graph_view_json`, `GraphEditor.model_graph_view_html`, and `GraphEditor.write_model_graph_view`. -- Semantic edits and sessions live under the same namespace, including +- Editing models and connections, and controlling editor sessions: `GraphEditor.AddModelApplication`, `GraphEditor.apply_model_graph_edit`, `GraphEditor.edit_graph`, `GraphEditor.current_model`, `GraphEditor.undo!`, and `GraphEditor.redo!`. @@ -156,7 +165,8 @@ for declared status or environment variables. ## Advanced namespace -`PlantSimEngine.Advanced` contains the qualified compiler and cache API: +`PlantSimEngine.Advanced` contains the compiler's data structures and the +functions that prepare and update cached information: - registries and compiled representations: `ObjectRegistry`, `CompiledCompositeModel`, `CompiledModelApplication`, `CompiledModelInputBinding`, @@ -172,11 +182,10 @@ for declared status or environment variables. `model_revision`, `environment_revision`, `compiled_bindings`, `compiled_environment_bindings`. -These names require explicit qualification or `using PlantSimEngine.Advanced`. -They are not part of the concise user namespace and may evolve with compiler -implementation requirements. +Use these names with the `Advanced` prefix, or import them with +`using PlantSimEngine.Advanced`. They are not imported by +`using PlantSimEngine` and may change as the compiler develops. -The namespace-boundary test in `test/test-model-api-stabilization.jl` compares -the complete default public-name set with an explicit inventory and separately -checks every focused submodule. Adding or removing an export therefore requires -an intentional inventory update. +The test in `test/test-model-api-stabilization.jl` compares the full set of +public names with an explicit list and checks each submodule separately. +When adding or removing an exported name, update that list as well. diff --git a/docs/src/agent_skill.md b/docs/src/agent_skill.md index ff50975b7..0092d025e 100644 --- a/docs/src/agent_skill.md +++ b/docs/src/agent_skill.md @@ -1,18 +1,18 @@ # AI agent skill -PlantSimEngine includes an optional Codex/OpenAI-style skill for users who want an AI agent to help write simulations or implement models. +An **AI coding agent** can read and edit code and run tests with the tools you +make available. PlantSimEngine provides an optional skill with instructions +and executable examples for implementing process models and assembling +simulations. A **skill** is a folder of instructions and examples that your +agent can read while working. -The skill uses the Julia tools available in the agent's environment. It does -not require a particular editor or connector; repository and user execution -requirements still apply. +You choose the scientific question, assumptions, references, and validation +evidence. The agent can help turn those choices into code and check that the +declared models connect as intended. -The skill file is stored in the repository at: +## Set up the skill for your package version -```text -skills/plantsimengine/SKILL.md -``` - -Use the copy shipped with the package version that Julia actually loaded: +Find the skill shipped with the PlantSimEngine version you actually use: ```julia using PlantSimEngine @@ -22,60 +22,80 @@ skill_root = joinpath(package_root, "skills", "plantsimengine") (Base.pathof(PlantSimEngine), Base.pkgversion(PlantSimEngine), skill_root) ``` -Copy or link that complete `skills/plantsimengine` directory into the agent's -skill directory. Do not install a skill from a floating `main` branch for a -tagged or otherwise older package: its instructions may describe another API -generation. Updating the installed copy is an explicit user action. - -The skill gives agents the package-specific conventions they need for: - -- building object graphs with `CompositeModel`, `Object`, `CompositeModelTemplate`, and - `ObjectInstance`; -- applying models with `ModelSpec` and `on`; -- coupling values and manual model calls with `inputs` and `calls`; -- using cached hard-call plans through bulk `run_call!`, singular `call_model`, - and lifecycle-maintained object target buffers; -- configuring multirate simulations with `every`, `Dates.Period` values, - and temporal policies; -- binding global or spatial microclimate through `Environment`; -- reasoning about model-clock weather aggregation, `environment_hint` reducers, and - scenario source overrides; -- inspecting compiled scenarios with structured explanation helpers; -- reporting supplied, generated, bound, and unresolved variables with - `Diagnostics.explain_initialization`; -- accessing the live model from lifecycle-capable kernels with - `runtime_model(context)`; -- inspecting homogeneous runtime batches with `Diagnostics.explain_execution_plan`; -- collecting raw or requested model outputs with `outputs`, - `OutputRequest`, `collect_outputs`, and `Diagnostics.explain_output_retention`; -- implementing or wrapping models with `@process`, `inputs_`, `outputs_`, - `variable_contracts_`, `run!`, hard dependencies, and model traits; -- discovering, describing, comparing, and validating concrete models with - `Authoring` before editing a scenario; -- validating incomplete scenarios through versioned, serializable authoring - reports instead of inspecting compiler fields; -- checking `ModelDescription.field_provenance` so exact declarations are not - confused with inferred, best-effort, or unavailable information. - -The canonical source for a given package version is the local -`skills/plantsimengine/` directory below `pkgdir(PlantSimEngine)`. Its main -entry point is `SKILL.md`; its relative `references`, `assets`, and `scripts` -directories are part of the same versioned resource. - -The main file is a short router. It loads focused references for model -authoring, scenario coupling, repository organization, dynamic models, or -diagnostics. Copyable fixtures live under `assets/`, including a complete -minimal model, compatible and incompatible alternatives, an explicit physical -adapter, and their tests. Run the canonical local check with: +Copy or link that complete directory into your coding agent's skill directory, +following its installation instructions. Keep its `SKILL.md`, `references`, +`assets`, and `scripts` together. Use the copy from your installed package +rather than the latest `main` branch: different versions can describe +different APIs. + +The skill uses the Julia tools available in your agent's environment. It does +not require a particular editor or connector. + +## Ask it to assemble existing models + +Adapt this request to the packages, data, and scientific question you have: + +> Use the PlantSimEngine skill shipped with my loaded package. I want to +> compare two existing models for the same process. First identify available +> alternatives and explain their inputs, outputs, units, and assumptions. +> Show what data each needs and flag anything that is missing. Build the +> smallest simulation that can compare them with the same input data. Explain +> their connections, run the tests, and show the results. Keep any required +> physical conversion explicit. + +Useful inputs to provide are the package names, the process of interest, +your input data and its units, and the outputs you want to compare. The +[Loaded model catalog](@ref) and [Model compatibility and replacement](@ref) +show the corresponding manual workflow. + +## Ask it to implement an equation + +Provide the equation or source paper, definitions of the variables, +parameter values and units, and at least one expected result: + +> Use the PlantSimEngine skill shipped with my loaded package to implement +> the equation and variable definitions I provide. Check whether an existing +> process already represents this question. Keep the equation readable and +> declare each input and output, including its units and physical meaning. +> Test one calculation against my reference result, then use the model in +> a simulation of one object. +> If any assumption, physical conversion, parameter, or validation criterion +> is unspecified, identify it before choosing one. Show the code, test +> results, and remaining scientific questions. + +The [basic model tutorial](journeys/modelers/basic_model.md) follows this +sequence without an agent. For an existing implementation, also use +[Port an existing model](@ref). + +## Review what the agent returns + +Expect a concrete result you can inspect: + +- the loaded package path and version; +- the selected process and hypotheses, with the evidence supplied for them; +- readable model code and scenario configuration; +- checks that the required inputs are available, their units and meanings + match, and the models receive values from the intended sources; +- tests actually run, their results, and any remaining limitations. + +PlantSimEngine's `Authoring` reports describe models and compare interfaces. +`Diagnostics` explains inputs, connections, timing, and execution. The reports +show which information comes from the model author, which was found by +examining the code, and which is missing. These checks help find implementation and coupling errors; scientific +validation still needs suitable observations or reference results. + +## Check the packaged examples + +The skill includes a minimal model, alternative hypotheses, a physical +conversion model, coupling examples, and their tests. You or your agent can check +the copy supplied by the installed package with: ```julia include(joinpath( - pkgdir(PlantSimEngine), - "skills", - "plantsimengine", - "scripts", - "check-examples.jl", + pkgdir(PlantSimEngine), "skills", "plantsimengine", + "scripts", "check-examples.jl", )) ``` -Agents should still inspect the local package code before making changes. The skill is a usage and modeling guide, not a replacement for the current API definitions in `src/`. +Use [Model repository layout and tests](@ref) when you are ready to organize +your own reusable model package. diff --git a/docs/src/assets/brand.css b/docs/src/assets/brand.css new file mode 100644 index 000000000..57425a534 --- /dev/null +++ b/docs/src/assets/brand.css @@ -0,0 +1,97 @@ +/* PlantSimEngine's botanical palette and documentation layout adjustments. */ +:root { + --vp-c-brand-1: #156f64; + --vp-c-brand-2: #197b6f; + --vp-c-brand-3: #156f64; + --vp-c-brand-soft: rgba(21, 111, 100, 0.12); +} + +html.dark { + --vp-c-brand-1: #83cfa7; + --vp-c-brand-2: #197b6f; + --vp-c-brand-3: #156f64; + --vp-c-brand-soft: rgba(131, 207, 167, 0.14); +} + +/* Long API names must wrap in prose without widening the page. */ +.vp-doc :not(pre) > code { + overflow-wrap: anywhere; + white-space: normal; +} + +/* Keep search, version, theme and the navigation menu reachable on phones. */ +@media (max-width: 480px) { + .VPNav .title > span { + display: none; + } +} + +.VPHero .name { + color: var(--vp-c-brand-1); + background: none; + -webkit-text-fill-color: currentColor; +} + +.VPHero .image img { + max-width: 320px; + height: auto; +} + +@media (max-width: 640px) { + .VPHero .image img { + max-width: 200px; + } +} + +/* Keep the introduction readable on wide screens. */ +.VPHome .VPDoc .vp-doc { + max-width: 1040px; + margin-inline: auto; +} + +/* Scientific examples stay side by side when there is room for both. */ +.pse-home-examples { + display: grid; + grid-template-columns: minmax(0, 1.4fr) minmax(0, 1fr); + gap: 24px; + margin: 24px 0; +} + +.pse-home-examples figure { + display: flex; + flex-direction: column; + margin: 0; + padding: 16px; + border: 1px solid var(--vp-c-divider); + border-radius: 12px; +} + +.pse-home-examples img { + width: 100%; + height: 310px; + object-fit: contain; + background: white; + border-radius: 6px; +} + +.pse-home-examples figcaption { + margin-top: 16px; + font-size: 15px; + line-height: 1.65; +} + +.pse-home-examples figcaption a { + display: block; + margin-top: 8px; +} + +@media (max-width: 760px) { + .pse-home-examples { + grid-template-columns: minmax(0, 1fr); + } + + .pse-home-examples img { + height: auto; + max-height: 340px; + } +} diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png new file mode 100644 index 000000000..5dbff7185 Binary files /dev/null and b/docs/src/assets/logo.png differ diff --git a/docs/src/composite_model/quickstart.md b/docs/src/composite_model/quickstart.md deleted file mode 100644 index 988ae41cc..000000000 --- a/docs/src/composite_model/quickstart.md +++ /dev/null @@ -1,261 +0,0 @@ -# CompositeModel/Object Quickstart - -This page is the shortest path to a native composite-model/object simulation. - -Use this API for new multiscale, multi-plant, soil, microclimate, and -model-scale simulations. Applications use one direct constructor: - -```julia -ModelSpec( - model; - name=:application, - on=Many(scale=:Leaf), - inputs=(...), - calls=(...), - every=Dates.Hour(1), - environment=Environment(...), - output_routing=(...), - updates=Updates(...), -) -``` - -Scenarios are defined with `CompositeModel` and model applications. A model is a -reusable process implementation; an application is one configured use of that -model, including its name, target objects, inputs, cadence, and environment. -One application may run on many objects, and the same model may appear in -several applications with different parameters or targets. - -```@setup model_object_quickstart -using PlantSimEngine, PlantMeteo, Dates, DataFrames -using PlantSimEngine.Examples -``` - -## One Object, Several Models - -For models that all run on one object, the concise constructor lowers directly -to the ordinary CompositeModel/Object representation: - -```julia -model = CompositeModel(ModelA(), ModelB(); status=(initial_value=1.0,)) -``` - -Use the explicit form later in this guide when applications need names, -selectors, or other scenario policies. - -The first model has one object, `:scene`, and three model applications: - -- `ToyDegreeDaysCumulModel` computes daily thermal time; -- `ToyLAIModel` consumes cumulative thermal time and computes LAI; -- `Beer` consumes LAI and meteorology to compute absorbed PAR. - -The model implementations are ordinary PlantSimEngine kernels. The model -application layer decides where they run. With no explicit `every`, these -applications use the environment cadence. - -```@example model_object_quickstart -meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); - duration=Dates.Day, -) - -model = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.6); - environment=meteo_day, -) - -sim = run!(model; steps=30, outputs=:all) -out = collect_outputs(sim; sink=DataFrame) -first(out, 6) -``` - -The `Simulation` provides a snapshot of the latest status values: - -```@example model_object_quickstart -scene_status = final_state(sim) -(TT_cu=scene_status.TT_cu, LAI=scene_status.LAI, aPPFD=scene_status.aPPFD) -``` - -## Inspect The Compiled Bindings - -Before running, `Diagnostics.explain_initialization(model)` classifies each variable as -`:required`, `:defaulted`, `:supplied`, `:producer_bound`, `:generated`, or -`:environment_bound`. The report remains available when required values are -missing, so it can be used to finish configuring a model. - -The compiler infers unambiguous same-object dependencies from declared model -inputs and outputs: - -- `:LAI_Dynamic` reads `TT_cu` from `:Degreedays`; -- `:light_interception` reads `LAI` from `:LAI_Dynamic`. - -```@example model_object_quickstart -select( - DataFrame(Diagnostics.explain_bindings(model)), - :application_id, - :input, - :source_application_ids, - :carrier_kind, - :copy_semantics, -) -``` - -`carrier_kind = :ref` and `copy_semantics = :live_references` mean the -consumer sees a shared reference rather than a copied value. - -For runtime performance diagnostics, inspect the execution plan: - -```@example model_object_quickstart -select( - DataFrame(Diagnostics.explain_execution_plan(model)), - :application_id, - :object_ids, - :batch_size, - :inner_loop_dispatch, -) -``` - -## Request Outputs - -By default, model runs retain no user output streams. Pass `outputs=:all` to -retain every publisher, or pass `OutputRequest` values to retain and -materialize selected streams plus those required by temporal inputs. - -```@example model_object_quickstart -request = OutputRequest( - Many(scale=:Scene), - :LAI; - name=:lai_every_two_days, - application=:LAI_Dynamic, - policy=HoldLast(), - clock=Day(2), -) - -requested_sim = run!( - model; - steps=30, - outputs=request, -) - -collect_outputs(requested_sim, :lai_every_two_days; sink=nothing)[1:4] -``` - -The retention explanation reports why a stream was kept: - -```@example model_object_quickstart -Diagnostics.explain_output_retention(requested_sim) -``` - -## Many Objects As Inputs - -Use `ModelSpec(...; inputs=...)` when a model needs values from selected objects. This -model-scale LAI model reads live references to the surface of every plant: - -```@example model_object_quickstart -plant_scene = CompositeModel( - Object(:scene; scale=:Scene, kind=:scene), - Object( - :plant_1; - scale=:Plant, - kind=:plant, - parent=:scene, - status=Status(surface=12.0), - ), - Object( - :plant_2; - scale=:Plant, - kind=:plant, - parent=:scene, - status=Status(surface=8.0), - ); - applications=( - ModelSpec(ToyLAIfromLeafAreaModel(100.0); name=:scene_lai, on=One(scale=:Scene), inputs=(:plant_surfaces => Many( - scale=:Plant, - within=SceneScope(), - var=:surface, - ),)), - ), -) - -plant_sim = run!(plant_scene) -plant_model_status = final_state(plant_sim, One(scale=:Scene)) -(total_surface=plant_model_status.total_surface, LAI=plant_model_status.LAI) -``` - -The compiled binding shows a `RefVector` carrier: - -```@example model_object_quickstart -select( - DataFrame(Diagnostics.explain_bindings(plant_scene)), - :application_id, - :input, - :source_ids, - :carrier_kind, - :copy_semantics, -) -``` - -If the consumer model runs on each plant, use `within=Subtree()` to read only -objects inside the current plant. Use `within=SceneScope()` when a model model -must aggregate all matching objects. - -## Manual Calls - -Use `ModelSpec(...; calls=...)` when a parent model must directly run selected child models. -This is the mechanism for iterative solvers such as model energy balance: - -```julia -ModelSpec(SceneEnergyBalance(); name=:scene_energy, on=One(scale=:Scene), calls=(:leaf_energy => Many( - kind=:plant, - scale=:Leaf, - within=SceneScope(), - application=:energy_balance, - ), - :soil => One( - kind=:soil, - scale=:Soil, - within=SceneScope(), - application=:soil_water, - ),), every=Hour(1)) -``` - -For a one-shot call, execute all targets directly: - -```julia -targets = run_call!(context, :leaf_energy; publish=true) -``` - -`targets` is always vector-like regardless of whether the declaration uses -`One`, `OptionalOne`, or `Many`. For iterative control, retrieve the same -compiled targets without executing them: - -```julia -function PlantSimEngine.run!(model::SceneEnergyBalance, status, environment, - constants, context) - trial = trial_environment(model, status) - run_call!(context, :leaf_energy; environment=trial, publish=false) - - accepted = accepted_environment(model, status) - commit_environment!(context, accepted) - run_call!(context, :leaf_energy; publish=true) - - return nothing -end -``` - -`run_call!` defaults to `publish=false`, so trial calls mutate target statuses -without publishing temporal streams or committing mutable environment updates. -Pass non-committing trial state with `environment=trial_state`, then call -`commit_environment!` before publishing the accepted state. - -## Next Steps - -- [Migrating To The CompositeModel/Object API](../migration_composite_model.md) translates - scenarios written with removed APIs. -- [Public API](../API/API_public.md) lists constructors, selectors, lifecycle - helpers, environment helpers, and explanation helpers. -- [Model traits](../model_traits.md) documents `inputs_`, `outputs_`, `dep`, - `timespec`, `output_policy`, and `environment_inputs_`. -- [MAESPA-style model example handoff](../dev/maespa_model_handoff.md) - records the current multi-plant model energy-balance acceptance example. diff --git a/docs/src/dev/code_cleanup_audit.md b/docs/src/dev/code_cleanup_audit.md deleted file mode 100644 index 1e75bafb0..000000000 --- a/docs/src/dev/code_cleanup_audit.md +++ /dev/null @@ -1,97 +0,0 @@ -# Code Cleanup Audit - -## Status - -The compatibility cleanup is implemented on the `multi-plants` branch. - -The package now has one scenario compiler and runtime: the composite-model/object API. -The following superseded implementations were removed rather than deprecated: - -- `ModelList` and `SingleScaleModelSet`; -- `ModelMapping` and `MultiScaleModel`; -- `DependencyGraph`, `HardDependencyNode`, and `SoftDependencyNode`; -- `GraphSimulation` and the MTG mapping runner; -- mapping-specific multirate input resolution and output export; -- the unreleased domain prototype that preceded the composite-model/object API, - including `Domain`, `SimulationMapping`, `Route`, `AllDomains`, - `HardDomains`, and its separate scheduler, runtime, environment bridge, and - output publisher; -- mapping-only initialization, dataframe, dimension, and topology helpers; -- unused parallel-executor traits after removal of the executor runtime; -- dead `UninitializedVar`, `RefVariable`, `TreeAlike`, and `StatusView` types; -- the unreleased `CompositeModelTemplate(...; mapping=...)` alias and legacy - selector-to-mapping conversion helpers; -- compatibility tests, tutorials, and executable examples. - -Migration details are retained in -[`migration_composite_model.md`](../migration_composite_model.md) and -[`release_notes_handoff.md`](release_notes_handoff.md). - -## Current Ownership - -| Concern | Owner | -| --- | --- | -| Object registry, selectors, compilation, execution, lifecycle | `src/composite_model_api.jl` | -| Model application configuration | `src/ModelSpec.jl` | -| Status and reference vectors | `src/component_models/Status.jl`, `src/component_models/RefVector.jl` | -| Dates-based clocks and policies | `src/time/multirate.jl`, `src/time/runtime/clocks.jl` | -| Environment sampling | `src/time/runtime/environment_sampling.jl` | -| Environment backends | `src/time/runtime/environment_backends.jl` | -| Output request definition | `src/time/runtime/output_export.jl` | - -## Remaining Review Rules - -Future cleanup should reject: - -- a second scenario/runtime abstraction parallel to `CompositeModel`; -- compatibility wrappers for unreleased APIs; -- package-specific behavior in PlantSimEngine; -- model kernels that know their scenario object, timestep, or coupling unless - the scientific algorithm requires a hard call; -- dynamic per-object dispatch or copying in hot loops when compiled typed - batches and reference carriers are available; -- undocumented public names or agent instructions that describe removed APIs. - -## Verification - -Current cleanup evidence: - -- the `src` tree contains only the composite-model/object runtime and supporting status, - time, environment, fitting, trait, and example files; -- empty directories left by removed subsystems were deleted; -- `git diff --check` passes; -- PlantSimEngine precompiles and loads from a clean Kaimon session; -- `test/test-unified-model-object-api.jl` passes 576 tests; -- the complete package environment passes 885 tests, including Aqua and - doctests; -- `test/test-fitting.jl` passes; -- the documentation build passes, including executable examples and - cross-reference checks; -- repository search finds no superseded scenario-runtime definitions or - references in source, tests, examples, README, public docs, or the packaged - agent skill; -- remaining `ModelMapping` and `MultiScaleModel` references outside - development notes are migration text that explicitly points historical code - to the composite-model/object API. -- repository search finds no `Domain`, `SimulationMapping`, `Route`, - `AllDomains`, or `HardDomains` implementations, exports, tests, examples, or - public documentation. The only remaining references are development/release - notes that record their removal from this unreleased branch; -- ignored `.DS_Store` files were removed from the working tree outside `.git`. -- `ModelSpec` pipe-helper boilerplate was consolidated behind shared internal - helpers while keeping the public `on`, `inputs`, `calls`, `every`, - `Environment`, `Updates`, and `output_routing` grammar unchanged. -- the duplicate `Advanced.TimeStepTable` export was removed from the PlantMeteo - re-export block; `Advanced.TimeStepTable` remains exported once from the core status - export list. -- stale `PlantSimEngine.Examples` exports for the deleted - `ToyInternodeEmergence` example were removed. - -Downstream verification: - -- PlantBiophysics passes 117/117 tests against this working tree. -- XPalm's uncommitted CompositeModel/Object migration executes 74/75 assertions. The - remaining assertion retains the removed runtime's first-step LAI value, - while the explicit current dependency order produces zero from the initial - zero-biomass leaf before plant/model aggregation. PlantSimEngine intentionally - contains no package-specific compatibility workaround for that stale fixture. diff --git a/docs/src/dev/composite_model_completion_audit.md b/docs/src/dev/composite_model_completion_audit.md deleted file mode 100644 index 828ea4573..000000000 --- a/docs/src/dev/composite_model_completion_audit.md +++ /dev/null @@ -1,96 +0,0 @@ -# Unified CompositeModel/Object Completion Audit - -This audit records the evidence used to assess the breaking composite-model/object -redesign against `composite_model_design.md` and -`composite_model_implementation_plan.md`. - -Audit date: June 12, 2026. - -## Result - -The unified composite-model/object redesign is implemented as the primary public -configuration API. - -The superseded mapping implementation and the unreleased intermediate -prototype were removed after the composite-model/object runtime replaced them. - -## Public Contract - -The exported scenario vocabulary centers on: - -```julia -CompositeModel -Object -ModelSpec -Updates -Environment -``` - -Legacy scenario constructors such as `ModelMapping` and `MultiScaleModel` were -removed. - -Evidence: - -- `src/PlantSimEngine.jl` -- `docs/src/API/API_public.md` -- `docs/src/migration_composite_model.md` -- `README.md` - -## Requirement Evidence - -| Requirement | Evidence | -| --- | --- | -| One model object registry without prescribing plant topology | `CompositeModel`, `Object`, selectors, relations, scopes, and `objects_from_mtg` in `src/composite_model_api.jl`; selector and MTG adapter tests in `test/test-unified-model-object-api.jl` | -| Reusable species models and repeated plant instances | `CompositeModelTemplate`, `ObjectInstance`, `Override`, shared model ownership, and homogeneous/heterogeneous batches; four-instance and override tests | -| Soft/value dependencies | Compiled `ModelSpec(...; inputs=...)` bindings, same-object inference, scalar references, `RefVector`, `Advanced.ObjectRefVector`, temporal carriers, renaming, and optional inputs | -| Manual hard dependencies | Compiled `ModelSpec(...; calls=...)`, vector-like `CallTargets`, `run_call!(context, name)`, and fine-grained `run_call!(target)`; trial calls default to `publish=false` and accepted calls publish explicitly | -| Model-author dependency defaults | `Input(...)` and `Call(...)` entries from `dep(model)`, with `ModelSpec` overrides and binding provenance in explanations | -| Multirate execution | `every=Dates.Period`, model `timespec`, input policies, explicit windows, `PreviousTimeStep`, and stable compiled scheduling | -| Generic value types | Reference and temporal tests using `ModelObjectDualLike{BigFloat}` and `BigFloat` interpolation/integration without `Float64` conversion | -| Reference semantics and low-copy execution | Shared scalar references, typed many-object carriers, preinstalled status bindings, zero-allocation materialization tests, and a zero-allocation warmed 128-object execution batch | -| Duplicate writers | Canonical writer validation and `Updates(:variable; after=...)`, including pruning-after-allocation tests | -| Growth, pruning, reparenting, and movement | Central lifecycle APIs, structural/environment cache invalidation, dynamic target/carrier rebuilding, removed-object output history, and object-scoped geometry refresh tests | -| Automatic meteorology and microclimate | `environment_inputs_`, global and spatial backends, ancestor geometry fallback, source remapping, model hints, tabular aggregation, cached opaque handles, `run_call!(...; environment=trial_state)` trial sampling, and `commit_environment!` accepted mutable commits | -| Structured agent explanations | Object, instance, scope, application, binding, call, model-bundle, environment, schedule, writer, execution-plan, output, and retention explanations returning structured rows | -| Initialization workflow | `Required(T)` and `Default(value)` make the input contract explicit; `Diagnostics.explain_initialization` classifies required, defaulted, supplied, generated, producer-bound, and environment-bound variables before strict compilation | -| Runtime model access | `runtime_model` is the public accessor used by lifecycle-capable kernels and accepts `CompositeModel`, `RunContext`, and `Simulation` | -| One-object ergonomics | `CompositeModel(model, models...; status=...)` lowers to the same object/application compiler and runtime as explicit construction | -| Output ownership and retention | Application-qualified streams, `output_routing`, `OutputRequest(application=...)`, dynamic-object exports, and bounded policy-specific dependency histories | -| MAESPA acceptance case | `build_maespa_scene` and `run_maespa_example` use `CompositeModelTemplate`, `ObjectInstance`, `on`, `inputs`, `calls`, and `every`; verified by `test/test-maespa-model-example.jl` | -| Documentation and migration | CompositeModel/object-first README, home page, quickstart, execution guide, public API, migration guide, and explicitly labeled legacy reference sections | - -## Verification - -The following gates passed from a clean, controllable Kaimon Julia session: - -```text -test/test-unified-model-object-api.jl 576 passed -test/runtests.jl 885 passed -docs/make.jl passed -PlantBiophysics/test/runtests.jl 117 passed -git diff --check passed -``` - -The complete package suite includes Aqua, all focused restoration files, the -broad unified runtime regression, examples, fitting, and doctests. The -documentation build completed its executable examples, doctests, -cross-references, document checks, and HTML rendering successfully. - -The current uncommitted XPalm CompositeModel/Object migration loads this PlantSimEngine -worktree and executes 74 of 75 downstream assertions. Its remaining assertion -expects the removed runtime's first-step LAI (`0.000272`); the current compiled -dependency order correctly runs leaf area before plant and model aggregation, -so the initial zero-biomass leaf produces `0.0`. This is a downstream fixture -expectation in a dirty migration worktree, not a package-specific behavior to -restore in PlantSimEngine. No XPalm workaround was added here. - -## Compatibility Boundary - -Historical mapping source and tests were removed. Migration guidance remains -in the documentation for downstream packages moving to the composite-model/object API. -The branch-only intermediate prototype was also removed because it was never -released and has no compatibility boundary. - -Requested output histories are still materialized after a run. Dependency-only -temporal histories are bounded, but a fully online output sink would be an -additional optimization rather than a missing requirement of this redesign. diff --git a/docs/src/dev/composite_model_design.md b/docs/src/dev/composite_model_design.md deleted file mode 100644 index 8c983c99f..000000000 --- a/docs/src/dev/composite_model_design.md +++ /dev/null @@ -1,758 +0,0 @@ -# Unified CompositeModel/Object Design - -This page records the target breaking design for one composite-model/object -configuration and runtime API. - -The central idea is: - -> Structural groupings and scales are selections over objects in one model. - -The engine should expose one way to say "this model input comes from these -objects" and one way to say "this model must manually call these models". The -compiler can then choose whether the runtime carrier is a `Ref`, `RefVector`, -temporal stream, materialized value, or callable model handle. - -The public API should be simple enough to remember as: - -```julia -ModelSpec( - model; - name=:application, - on=Many(scale=:Leaf), - inputs=(...), - calls=(...), - every=Dates.Hour(1), - environment=Environment(...), - output_routing=(...), - updates=Updates(...), -) -``` - -Everything else should either be a selector, a trait declared by the model -author, or an internal compiled carrier. - -## Core Concepts - -### CompositeModel - -A `CompositeModel` is the whole simulation universe. It contains: - -- simulated objects; -- model applications; -- environment providers; -- time/runtime state; -- caches for object selections and environment bindings. - -Plants, soil, atmosphere, microclimate grids, organs, sensors, and artificial -objects all live in the same model-level object graph. - -### Object - -An object is any simulated entity with identity. It may have: - -- a unique object id; -- one or more labels, such as `scale=:Leaf`, `kind=:plant`, - `species=:oil_palm`; -- parent/child links; -- geometry or position; -- status variables; -- model applications. - -The engine must not prescribe a plant architecture. A plant can be described as -`Plant -> Internode -> Leaf`, `Plant -> Axis -> Segment -> Leaf`, -`Plant -> Metamer -> Organ`, or another topology. The engine only needs object -identity, labels, and relations. - -Existing `MultiScaleTreeGraph.Node` topologies enter the same registry through -`objects_from_mtg(root; ...)` or `CompositeModel(root; ...)`. The adapter traverses once -and accepts accessors for ids, labels, status, and geometry; the timestep -runtime does not query the MTG topology. - -### Scale - -A scale is a label on objects, not a separate runtime layer. Examples: - -```julia -:Scene -:Plant -:Axis -:Internode -:Leaf -:Soil -:SoilLayer -:Voxel -``` - -### Scope - -A scope is a named or inferred subset of objects. Examples: - -```julia -SceneScope() -Self() -SelfPlant() -Ancestor(scale=:Plant) -Scope(:oil_palm) -Many(kind=:plant) -Many(species=:oil_palm) -``` - -`Self()` means only the current object: the object on which the consuming -application runs. It never means the model, species, or plant unless that -object is itself the plant. `Subtree()` means that object and its descendants. -Neither spelling changes meaning with scale. - -`SelfPlant()` is the nearest containing plant scope. The more generic form is -`Ancestor(scale=:Plant)`. Use these when a model running below the plant scale -must access siblings or state inside the containing plant. - -Reusable plant models should use scope-relative queries. If an allocation -model is applied to each `:Plant`, `Many(scale=:Leaf, within=Subtree())` means -"the leaves inside this plant", not all leaves in the model. The same query -applied to an axis-scale model means "the leaves inside this axis". - -CompositeModel-level models widen the scope explicitly with `within=SceneScope()`. - -Topology-relative selections use `Relation(...)`: - -```julia -One(Relation(:parent)) -Many(Relation(:children)) -Many(Relation(:ancestors); scale=:Plant) -Many(Relation(:descendants); scale=:Leaf) -Many(Relation(:siblings)) -``` - -Supported relations are `:self`, `:parent`, `:children`, `:ancestors`, -`:descendants`, and `:siblings`. They resolve relative to the current model -application object. An explicit `within=...` scope intersects the relation -result; inferred default scopes do not hide parents or siblings. Relation -results are normalized to stable object-id order before bindings are compiled. - -### Object Template And Instance - -An object template is a reusable model/parameter bundle, for example one oil -palm species model. An object instance is one concrete object in the model. - -The same template can be mounted several times: - -```julia -oil_palm = CompositeModelTemplate( - kind=:plant, - species=:oil_palm, - applications=oil_palm_applications, - parameters=oil_palm_parameters, -) - -model = CompositeModel( - ObjectInstance(:palm_1, oil_palm; root=node1), - ObjectInstance(:palm_2, oil_palm; root=node2), - ObjectInstance(:palm_3, oil_palm; root=node3), - ObjectInstance(:palm_4, oil_palm; root=node4), -) -``` - -Models and parameters can be overridden at instance or object level: - -```julia -ObjectInstance(:palm_2, oil_palm; overrides=( - stomatal_conductance = Tuzet(; g1=3.2), -)) - -Override( - object=:leaf_12, - application=:photosynthesis, - model=Fvcb(; VcMaxRef=90.0), -) -``` - -Ownership is reference-based and explicit: - -- a template retains the supplied model and parameter objects without copying; -- unchanged instances share those exact objects; -- an instance override replaces one complete model application with another - user-owned model object; -- an object override replaces that application only for the selected object; -- PlantSimEngine does not mutate model fields or implicitly merge parameter - dictionaries. - -Overrides must preserve the model contract: process identity and declared -status/environment variable names cannot change. Parameter-only overrides of -the same concrete model type retain concrete runtime dispatch. Heterogeneous -alternative implementations are supported but may require dynamic dispatch for -the exceptional application. - -### Model Kernel And Model Application - -A model kernel is the reusable model implementation written by a modeler. It -defines a process, parameters, `inputs_`, `outputs_`, optional `dep` defaults, -optional environment traits, and `run!`. - -A model application is the scenario-specific use of that kernel on selected -objects, at a selected rate, with selected value inputs, model calls, update -rules, output routing, and environment binding behavior. - -The model kernel should not need to know: - -- the species it will be used with; -- the model it will be embedded in; -- the timestep chosen by the user; -- whether its inputs come from local state, another scale, another object, a - temporal stream, units, automatic differentiation values, or uncertainty - wrappers. - -The scenario owns those decisions through `ModelSpec`. - -Target shape: - -```julia -ModelSpec(LeafEnergyBalance(); name=:leaf_energy, on=Many(kind=:plant, scale=:Leaf), inputs=(...), calls=(...), every=Hour(1)) -``` - -Application names are optional when a process occurs only once. Scenario -declarations identify singular producers and call targets with -`application=:sunlit_photosynthesis`; `process=...` is reserved for explicit -discovery queries such as `Many(process=:photosynthesis)`. - -## Unified Model Configuration - -`ModelSpec` is the single scenario wrapper. Released mapping-era configuration -is replaced by explicit value inputs and callable model calls. - -### Applies To - -Use `ModelSpec(...; on=...)` to declare the object set where a model application runs. -This should be first-class, not inferred from a container or mapping key. - -```julia -ModelSpec(LeafState(); on=Many(kind=:plant, scale=:Leaf)) - -ModelSpec(AllocationModel(); on=Many(kind=:plant, scale=:Plant)) - -ModelSpec(SceneEB(); on=One(scale=:Scene)) -``` - -The same model kernel can be applied several times with different selectors, -parameters, timesteps, or input bindings. The compiler should normalize each -application to a stable application id. - -### Dependency Defaults From Traits - -Model authors should still declare `inputs_`, `outputs_`, and `dep`. In the -final design, `dep(model)` is the model-level place for default dependency -intent. Historical `ModelMapping` declarations are migration inputs to the -CompositeModel/Object runtime, not a second supported path. - -The rule is: - -- `inputs_(model)` declares the variables the model needs; -- `outputs_(model)` declares the variables the model computes; -- `dep(model)` declares default value sources or manual model calls when the - model author knows a sensible coupling pattern; -- `ModelSpec(...; inputs=(...))` and `ModelSpec(...; calls=(...))` override - or specialize those defaults for a specific simulation. - -For example, a plant allocation model can provide a plant-local default: - -```julia -dep(::PlantAllocationModel) = ( - leaf_carbon = Input(Many(scale=:Leaf, within=Subtree(), var=:leaf_carbon)), -) -``` - -An energy-balance model can declare that it usually calls a stomatal -conductance model manually: - -```julia -dep(::LeafEnergyBalanceModel) = ( - stomatal_conductance = Call(One(process=:stomatal_conductance)), -) -``` - -These trait defaults are not absolute wiring. They are model-author defaults -that make common cases work without repeating configuration, while scenario -authors keep final authority through `ModelSpec`. - -Compiler order: - -1. read `inputs_`, `outputs_`, and `dep`; -2. infer simple same-object value dependencies when unambiguous; -3. apply `dep(model)` defaults for value inputs and model calls; -4. apply `ModelSpec` overrides last. - -This order is part of the public contract. It keeps modeler defaults useful -without making them final wiring. Missing or ambiguous inputs after this pass -are errors, not incidental fallback behavior. - -### Value Inputs - -Use `ModelSpec(...; inputs=...)` when a model needs values before its `run!` method executes: - -```julia -ModelSpec(LAIModel(ground_area); inputs=(:leaf_areas => Many(scale=:Leaf, within=SceneScope(), var=:leaf_area))) -``` - -Reusable plant allocation: - -```julia -ModelSpec(AllocationModel(); on=Many(scale=:Plant), inputs=(:leaf_carbon => Many(scale=:Leaf, within=Subtree(), var=:leaf_carbon))) -``` - -The same declaration must compile to: - -- direct `Ref`/`RefVector` wiring when producer and consumer live in the same - object graph and rate; -- temporal stream reads when producer and consumer run at different rates; -- materialization when target status must be assigned before a - model runs; -- source-status lookup for graph-backed object selections. - -The important user rule is: - -- `ModelSpec(...; inputs=...)` means "give this model values"; the runtime schedules or - samples producers; -- the receiving model never manually calls the producer because of an - `ModelSpec(...; inputs=...)` declaration. - -### Carrier And Copy Semantics - -The compiler chooses the carrier, but the semantics must be documented and -explainable: - -| Situation | Preferred carrier | Copy behavior | -| --- | --- | --- | -| same-rate scalar input | shared `Ref` or local alias | no copy when possible | -| same-rate `Many(...)` input | `RefVector` or equivalent typed reference collection | no copy for live values | -| cross-rate input | temporal stream sample | value materialized for the consumer timestep | -| `Integrate` or `Aggregate` input | temporal window reduction | reduced value materialized | -| materialized target status input | compiler-generated assignment | assigned before consumer run | -| environment input | cached `EnvironmentBinding` sample | backend-defined value sample | - -This table is a required part of the design because performance, units, -automatic differentiation, and error propagation depend on preserving user -value types and avoiding hidden copies. - -PlantSimEngine should not force `Float64` internally. Status values, -parameters, environment values, and outputs must be allowed to use units, dual -numbers, uncertainty wrappers, tracked arrays, or other numeric-like types. -Compiled carriers should be parametric and type stable whenever the object set -and value type are known at initialization. - -### Multirate Inputs - -Multirate must be supported by the same `ModelSpec(...; inputs=...)` declaration, not a -separate mapping language. The public time language should remain `Dates` -periods. - -Example: - -```julia -ModelSpec(PlantAllocation(); on=Many(kind=:plant, scale=:Plant), inputs=(:leaf_assimilation => Many( - scale=:Leaf, - within=Subtree(), - var=:assimilation, - policy=Integrate(), - window=Day(1), - )), every=Day(1)) -``` - -Policy precedence should stay explicit: - -1. input-level policy in `ModelSpec(...; inputs=...)`; -2. producer `output_policy(model)`; -3. default `HoldLast()`. - -Cross-rate links must go through temporal state even when they point to objects -that could otherwise be reference-wired. - -Same-timestep feedback cycles are broken explicitly on the receiving input: - -```julia -ModelSpec(CarbonState(); inputs=(PreviousTimeStep(:carbon_biomass) => One( - scale=:Plant, - application=:carbon_allocation, - var=:carbon_biomass, - ),)) -``` - -`PreviousTimeStep(:x)` removes the producer-to-consumer edge from the current -timestep graph and reads the latest source sample at or before the previous -model timestep. Before a source sample exists, the initialized consumer status -value for `x` is used. This makes initialization part of the scenario contract -instead of silently inventing a zero value. - -### Model Calls - -Use `ModelSpec(...; calls=...)` when a model must manually run selected models, typically -inside an iterative solver. This is the required public API name and must be -implemented as part of the unified composite-model/object redesign, not left as a later -rename. - -```julia -ModelSpec(SceneEB(); calls=(:leaf_energy => Many( - kind=:plant, - scale=:Leaf, - process=:energy_balance, - )), calls=(:soil => One(kind=:soil, application=:soil_water))) -``` - -Inside `run!`, the model model receives call handles and calls -`run_call!(call)` during trial iterations, then -`run_call!(call; publish=true)` for the accepted final solution. The default is -deliberately `publish=false`: trial calls mutate target status for convergence -checks but do not append temporal samples or write environment outputs. - -The important user rule is: - -- `ModelSpec(...; calls=...)` means "give this model callable model handles"; -- the parent model owns the call stack and can iterate, reject, or accept trial - calls; -- call outputs are published only according to the call publication contract. - -`Diagnostics.explain_calls(compiled)` exposes this as -`publication_policy=:explicit_accept`, with `default_publish=false` and -`accepted_publish=true`. - -Binding and call explanations also report where each dependency declaration -came from: - -- `origin=:inferred_same_object` for compiler-inferred value dependencies; -- `origin=:model_default` for `Input(...)` or `Call(...)` declarations coming - from `dep(model)`; -- `origin=:model_spec` for scenario-level `ModelSpec(...; inputs=...)` or `ModelSpec(...; calls=...)`, - including declarations that override a model default. - -### Multiplicity - -Selection multiplicity is explicit: - -```julia -One(...) -Many(...) -OptionalOne(...) -``` - -`OptionalOne(...)` resolves to zero or one dependency. With zero matches, an -input keeps its `inputs_` default and a call returns an empty -`call_targets(...)` collection. Explanations retain these unresolved -optional bindings instead of hiding them. - -The compiler validates that `One(...)` resolves to exactly one producer per -consumer scope. `Many(...)` returns a vector-like value or target collection. - -### Address Normalization - -All source and target declarations normalize to an internal address: - -```julia -Diagnostics.ObjectAddress( - scope, - kind, - species, - scale, - name, - process, - application, - var, - relation, - policy, - window, - from_status, - after, - multiplicity, -) -``` - -Only the compiler works with this normalized address. Users should not need to -construct it manually. [`Diagnostics.object_address`](@ref) is the structured diagnostic -view and preserves every normalized selector field, including temporal and -status-routing fields. - -## Object Lifecycle And Spatial Contracts - -Growth, pruning, organ creation, reparenting, and moving organs must all update -the same compiled caches: - -- object selections used by `on`, `inputs`, and `calls`; -- `RefVector` or equivalent many-object carriers; -- temporal stream ownership; -- writer validation; -- environment bindings. - -The public mutation API should make cache invalidation explicit and centralized: - -```julia -register_object!(model, object; parent) -remove_object!(model, object) -reparent_object!(model, object, new_parent) -move_object!(model, object, geometry_or_position) -Advanced.refresh_bindings!(model) -``` - -Spatial environment backends should depend on a small geometry contract, not on -a particular plant representation: - -```julia -position(object_or_status) -geometry(object_or_status) -bounds(object_or_status) -``` - -Packages can provide richer geometry, octrees, voxel grids, or layers, but -PlantSimEngine should only require enough information to bind an object to an -environment provider. - -## Duplicate Writers And Updates - -Most variables should have one canonical writer per object and timestep. When a -variable is intentionally updated by several models, the scenario should say so -where the model applications are assembled: - -```julia -ModelSpec(PruningModel(); on=Many(scale=:Leaf), updates=Updates(:leaf_biomass; after=:carbon_allocation)) -``` - -`Updates(...)` should be rare and explicit. It is a scenario-level ordering -rule, because a model author cannot predict every model that will later update -the same variable. - -## Environment And Microclimate - -Meteorology should remain automatic unless a model or scenario needs special -behavior. Models declare environment variables: - -```julia -environment_inputs_(::LeafEnergyModel) = ( - T=0.0, - Rh=0.0, - Wind=0.0, - Ri_PAR_f=0.0, - CO2=0.0, -) -``` - -The runtime resolves those variables through the model environment service. - -Default resolution: - -1. A global/table environment backend gives every object the current sampled row. -2. A voxel, octree, layered, or grid backend samples the cell bound to the - object. -3. If the object has no position, use the parent position. -4. If no spatial binding can be made, fall back to the global environment or error when - the environment variable is required. - -Users can override the binding contract: - -```julia -EnvironmentResolver( - bind=(model, object) -> containing_cell(model.microclimate, position(object)), -) -``` - -PlantSimEngine should define the protocol and caching hooks, not the voxel or -octree implementation. Specialized packages should provide concrete spatial -backends. - -The environment backend protocol should be small and backend-oriented: - -```julia -handle = EnvironmentAPI.bind_environment(backend, object, context, config) -EnvironmentAPI.sample(backend, handle, variable, time) -EnvironmentAPI.sample(backend, handle, trial_state, variable, time) -commit_environment!(backend, handle, accepted_state, time) -EnvironmentAPI.update_index!(backend, changed_entities, removed_object_ids) -``` - -`environment_inputs_(model)` declares what a model reads from the active environment -provider, while `environment_outputs_(model)` declares what it may commit. Controllers -commit accepted mutable microclimate state with -`commit_environment!(context, accepted_state)` and run trial descendants with -`run_call!(context, name; environment=trial_state)`. Simple global meteorology -remains the default provider. - -Scenario-level environment source remapping belongs on `Environment(...)`, for -example: - -```julia -ModelSpec(LeafGasExchange(); name=:gas_exchange, on=Many(scale=:Leaf), environment=Environment(provider=:global, sources=(CO2=:Ca,))) -``` - -Here the model reads `environment.CO2` because that is its declared generic -contract, while the active environment backend samples the source variable -`:Ca`. Environment binding refresh validates source availability when the -backend can enumerate variables, and explanations report both -`required_inputs` and `source_inputs`. - -Global tabular meteorology follows the model application's compiled -`ModelSpec(...; every=...)`. PlantMeteo samples the table with the reducer and window from -`environment_hint(...)` when the model runs more slowly than the weather base step. -An `Environment(; sources=...)` override replaces only the source variable; it -does not discard the model-author reducer. The prepared weather sampler is -compiled once, and one sampled row is reused by every object targeted by the -same application at that timestep. - -Spatial or mutable backends retain control of their own temporal semantics. -PlantSimEngine supplies the compiled object/cell binding and current simulation -time; a specialized microclimate backend decides whether its local state is -instantaneous, interpolated, or internally integrated. - -### Cached Environment Bindings - -Spatial lookup must not happen for every model call. At initialization and when -objects are created, the runtime builds an environment binding cache: - -```julia -EnvironmentBinding( - object_id, - provider=:microclimate_grid, - cell_id, - variables=(:T, :Rh, :Wind, :Ri_PAR_f), -) -``` - -Runtime sampling is: - -```text -object -> cached binding -> environment cell -> current values -``` - -Invalidation events: - -- object created; -- object removed; -- object moved; -- geometry changed; -- environment grid rebuilt or refined; -- model environment requirements changed. - -Geometry APIs should provide ergonomic invalidation: - -```julia -mark_environment_binding_dirty!(model, object) -update_geometry!(object, geometry; invalidate_environment=true) -``` - -Before each timestep, dirty bindings are refreshed in batch. - -## Compilation Strategy - -The compiler builds one global dependency graph over object addresses. -The graph includes: - -- value dependencies from `ModelSpec(...; inputs=...)`; -- callable dependencies from `ModelSpec(...; calls=...)`; -- model update edges from `Updates(...)`; -- temporal policy edges; -- environment reads and writes; -- object-scope selection caches. - -The runtime representation is an implementation detail: - -- same-rate local links can stay as aliases; -- cross-rate links use temporal state; -- many-object links use `RefVector` or node-value streams; -- call links use immutable call plans with lifecycle-maintained target buffers; -- environment links use application-level plans and object-specific handles. - -### Immutable plans and mutable object state - -The application graph is immutable during a simulation. Growth changes which -objects participate in that graph, not which applications, dependency -declarations, cadence rules, or selector programs exist. The compiler keeps -these two ownership layers separate: - -| Immutable for the scenario | Mutable at lifecycle barriers | -| --- | --- | -| application identity, model specification, and dense application slot | application target object ids | -| dependency edges and topological order | value carriers and temporal source buffers | -| compiled input and hard-call selector programs | hard-call target buffers | -| cadence definitions and schedule entries | schedule cursor and current execution groups | -| output-retention requirements and publication variables | stream instances and request membership intervals | -| environment backend/configuration, sampling rules, sampler, and prepared source | object handles, geometry provenance, and spatial index entries | - -`CompiledScenarioPlan` owns the immutable application, input, call, ordering, -and cadence definitions. Object-level bindings delegate to these plans rather -than copying their selector, policy, contract, or environment metadata. -`CompiledExecutionPlan` uses dense application slots for root scheduling and -keeps homogeneous target batches concrete. - -A `LifecycleDelta` journals additions, removals, reparenting, and movement once. -At the safe barrier after the mutating application, the runtime consumes that -shared delta to update affected application targets, input carriers, hard-call -targets, temporal storage, output membership, environment handles, and -execution groups. Applications still due later in the same timestep may run on -new objects. The following unchanged timestep returns to the same precompiled -schedule without selector resolution or graph reconstruction. - -The final execution plan should group contiguous targets with the same concrete -model, status, model-bundle, input-binding, and environment-binding types. -Dynamic dispatch may occur once at the application/batch boundary, but not for -every leaf in a homogeneous target set. Exceptional model overrides form -separate concrete batches while preserving stable object order. Lifecycle or -environment refreshes rebuild these batches before the next timestep. - -The public explanation API must describe the normalized graph, not the internal -carrier choice. - -Use `run!(model; performance=true)` only for coarse phase instrumentation. The -structured `Diagnostics.explain_runtime_performance(simulation)` view groups -the resulting counters into immutable-plan compilation, object-target -instantiation, lifecycle-buffer updates, steady-state execution, output -collection, and initial totals. Benchmark the normal runtime with -`performance=false`, because enabled instrumentation deliberately calls -`time_ns()` around compiler/runtime boundaries. - -## Agent-Facing Requirements - -The final design must be understandable by agents through structured -explanation helpers: - -```julia -Diagnostics.explain_objects(model) -Diagnostics.explain_instances(model) -Diagnostics.explain_scopes(model) -Diagnostics.explain_bindings(sim) -Diagnostics.explain_calls(sim) -Diagnostics.explain_environment_bindings(sim) -Diagnostics.explain_schedule(sim) -Diagnostics.explain_writers(sim) -Diagnostics.explain_execution_plan(sim) -Diagnostics.explain_output_retention(sim) -Diagnostics.explain_runtime_performance(sim) -``` - -These helpers should return stable structured data, not only pretty text. A -binding row should include at least: - -- consumer application id; -- consumer object id; -- consumer variable; -- source selector; -- resolved producer application id or environment provider id; -- resolved producer object ids; -- process/name filters; -- temporal policy and window; -- carrier kind; -- copy/reference semantics; -- reason the binding was chosen; -- whether it came from inference, `dep(model)`, or `ModelSpec`. - -Execution-plan rows should additionally expose the selected object ids, -concrete model/status/carrier types, batch size, and whether the inner loop is -homogeneous and specialized. - -Output-retention rows should expose the retained application id, variable, -retention reasons, compiled retention horizon, and current target count so -agents can distinguish default retain-all behavior, requested output streams, -and bounded temporal-dependency streams. - -Errors should report concrete object labels, scope selectors, process names, -variables, and suggested fixes. - -## API Position - -This is a breaking design. Model kernels use -`run!(model, status, environment, constants, context)` while the scenario -configuration surface uses `CompositeModel`, `Object`, `ModelSpec`, selectors, -`ModelSpec(...; inputs=...)`, `ModelSpec(...; calls=...)`, `ModelSpec(...; every=...)`, and `Environment(...)`. diff --git a/docs/src/dev/composite_model_implementation_plan.md b/docs/src/dev/composite_model_implementation_plan.md deleted file mode 100644 index cd575289b..000000000 --- a/docs/src/dev/composite_model_implementation_plan.md +++ /dev/null @@ -1,1036 +0,0 @@ -# Unified CompositeModel/Object Implementation Plan - -This plan is the persistent handoff for replacing the historical -multiscale-mapping system with one composite-model/object address system. - -The implementation can be incremental internally, but the target API is -breaking. Do not preserve experimental intermediate APIs as user-facing -concepts in the final design. - -The target public surface should be centered on a small set of concepts: - -```julia -ModelSpec( - model; - name=:application, - on=Many(scale=:Leaf), - inputs=(...), - calls=(...), - every=Dates.Hour(1), - environment=Environment(...), - output_routing=(...), - updates=Updates(...), -) -``` - -This is the API memory target for users, modelers, and agents. Additional -types should be selectors, model traits, or internal compiled carriers. - -## Implementation Progress - -- Started Phase 0 by adding typed application metadata, now constructed - directly with `ModelSpec` keywords. -- Added `ModelSpec(model; name=...)` application names and getters: - `application_name`, `applies_to`, `value_inputs`, `model_calls`, and - `environment_config`. -- Added selector and address types: `SceneScope`, `Self`, `Subtree`, - `SelfPlant`, `Ancestor`, `Scope`, `Relation`, `One`, `OptionalOne`, `Many`, - and `Diagnostics.ObjectAddress`. -- Added initial `CompositeModel`/`Object` registry types and lifecycle hooks: - `register_object!`, `remove_object!`, `reparent_object!`, `move_object!`, - and `Advanced.refresh_bindings!`. -- Added registry-backed selector resolution with `resolve_object_ids` and - `resolve_objects` for `SceneScope()`, `Self()`, `SelfPlant()`, - `Ancestor(...)`, `Scope(...)`, label keywords such as `kind=:plant` and - `scale=:Leaf`, and `One`/`OptionalOne`/`Many` cardinality checks. -- Added `Diagnostics.explain_scopes(model)` for agent-readable scope diagnostics. It - reports the global model scope, each object subtree, each named - `Scope(...)`, and label groups by scale, kind, and species with concrete - resolved object ids. -- Selector cardinality and named-scope failures now report the consumer - context, matched object ids, requested criteria, available scales, kinds, - species, and names inside the resolved scope, plus bounded edit-distance - suggestions. -- `Relation(...)` selectors now resolve `:self`, `:parent`, `:children`, - `:ancestors`, `:descendants`, and `:siblings` relative to the consuming - object. Explicit scopes constrain relation results, default dependency scopes - do not erase parent/sibling queries, and compiled `ModelSpec(...; inputs=...)` can use these - relations without runtime selector resolution. -- `Diagnostics.ObjectAddress(selector)` normalizes scope, relation, label, routing, - temporal-policy, and status-ordering fields into one structured diagnostic - record. -- Started the object-address compiler with `Advanced.compile_composite_model(model, specs)` and - compiled model application/binding carriers. The compiler now resolves - `ModelSpec(...; on=...)` target object ids, object-relative `ModelSpec(...; inputs=...)` source - object ids, and object-relative `ModelSpec(...; calls=...)` callee object/application ids - before runtime. -- Added `Diagnostics.explain_applications`, `Diagnostics.explain_bindings`, and `Diagnostics.explain_calls` - for the compiled model view. These explanations expose application ids, - processes, target ids, input source ids, call callee ids, temporal policy, - window, and carrier hints. -- Added status-backed compiled input carriers. When source objects already - hold `Status` values, `ModelSpec(...; inputs=...)` bindings now precompile a scalar shared - `Ref`, a homogeneous `RefVector`, or an `Advanced.ObjectRefVector` fallback for - heterogeneous reference-preserving vectors. `Diagnostics.input_carrier`, `Diagnostics.input_value`, - and `Diagnostics.has_reference_carrier` expose these carriers, and `Diagnostics.explain_bindings` - reports carrier kind, copy/reference semantics, carrier type, and reference - availability. -- Added conservative same-object input inference in the model compiler. When a - model declares an `inputs_` variable that is not covered by explicit/default - `ModelSpec(...; inputs=...)`, and exactly one other application on the same object outputs - the same variable, `Advanced.compile_composite_model` creates an inferred reference binding. - `Diagnostics.explain_bindings` now reports binding `origin` values such as - `:model_default`, `:model_spec`, and `:inferred_same_object`. -- Compiled input bindings now carry producer metadata. When an `ModelSpec(...; inputs=...)` - selector uses `process=` or `application=`, `Advanced.compile_composite_model` validates that a - matching source application exists for the selected source objects. - `Diagnostics.explain_bindings` reports `source_application_ids`, `process`, and - `application` for agent-readable dependency diagnostics. -- Dependency selectors in `ModelSpec(...; inputs=...)` and `ModelSpec(...; calls=...)` now infer a default - scope from the consumer object when no explicit `within=...` is provided: - model objects default to `SceneScope()`, while non-model objects default to - `Self()`. Shared model/soil dependencies from organs should therefore use - `within=SceneScope()` explicitly. -- `Advanced.compile_composite_model` now validates `Required(T)` status inputs - from `inputs_(model)`. Each required input must either have a compiled - binding or already exist on the target object `Status`; otherwise - compilation errors with the concrete application id, object id, and input - variable. -- CompositeModel compilation creates an empty `Status` for model-targeted - objects when status is omitted, inserts missing `outputs_` fields and - `Default(value)` inputs from their initial values, and installs explicitly or - implicitly bound input carriers. Unbound `Required(T)` inputs remain - compilation errors. -- `Advanced.compile_composite_model` now rejects `ModelSpec(...; inputs=...)` declarations whose left-hand - variable is not declared by the target model's `inputs_`. This catches - misspelled or stale scenario bindings before they create silent unused - metadata. -- `Advanced.compile_composite_model` now validates source availability for status-backed - non-temporal `ModelSpec(...; inputs=...)` bindings. When selected source objects already - have `Status` values, the requested source variable must resolve to - references instead of silently compiling to an unused/no-op binding. -- Carrier compilation preserves source `Status` references and arbitrary value - types; tests cover scalar refs, heterogeneous many-object vectors, and a - homogeneous dual-like `BigFloat` value through `RefVector`, model arithmetic, - source mutation, and typed output publication. -- Same-object renaming is supported directly by `ModelSpec(...; inputs=...)`, for example - `inputs=(:renamed_signal => One(within=Self(), var=:signal),)`. The compiler - aliases the source `Ref`, records the renamed source variable in - `Diagnostics.explain_bindings`, and schedules the producer before the consumer. -- Same-rate input carriers are installed directly into consumer `Status` - reference cells during model compilation. Scalar bindings share the source - `Ref`; many-object bindings store the compiled `RefVector` or - `Advanced.ObjectRefVector` once. The timestep runtime performs no assignment for - these bindings, and a focused `Many(...)` materialization gate verifies zero - allocations after compilation. -- Reference wiring adds a missing bound input field to the consumer `Status` - schema when needed, instead of requiring users to duplicate compiler-owned - input placeholders. -- Added call ambiguity validation in the compiled model view: a call can select - by process when unique, and must use `application=:name` when several model - applications with the same process match the same object. -- Added a model binding cache with `Advanced.refresh_bindings!`, `Advanced.bindings_dirty`, - `Advanced.compiled_bindings`, and `Advanced.model_revision`. Object creation, removal, - and reparenting now invalidate the compiled binding cache and bump a model - revision before the next refresh. -- Added an environment binding cache with `Advanced.refresh_environment_bindings!`, - `Advanced.compile_environment_bindings`, `Advanced.CompiledEnvironmentBinding`, - `Advanced.CompiledEnvironmentBindings`, `Advanced.environment_bindings_dirty`, - `Advanced.compiled_environment_bindings`, `Advanced.environment_revision`, and - `Diagnostics.explain_environment_bindings`. The compiler resolves each - application/object environment provider, backend, required - `environment_inputs_`, support descriptor, and backend cell before runtime. -- Added the minimal model geometry contract: `geometry(object_or_status)`, - `position(object_or_status)`, and `bounds(object_or_status)`. Environment - binding refreshes now call `EnvironmentAPI.update_index!(backend, changed_entities, removed_object_ids)` once per - distinct backend before `Advanced.EnvironmentAPI.bind_environment`, giving spatial backends a current - model-wide object/entity list for precomputed microclimate lookup. -- Automatic spatial binding now uses the nearest ancestor geometry when a - target object has no geometry of its own. Existing backends still receive an - `Object` carrying the target id/status, while its binding-time geometry comes - from the ancestor. Explanations report `geometry_source=:self`, `:ancestor`, - or `:global` and the source object id. -- Moving an object invalidates environment bindings for descendants that - inherit its geometry, stopping at descendants with their own geometry. This - preserves unaffected cached bindings. -- Environment refresh now reconciles model environment contracts against - cached spatial bindings. If only `environment_inputs_` changes while application - id, object, process, provider, backend, status, and geometry provenance remain - unchanged, required metadata is updated while the cached cell is reused - without `EnvironmentAPI.update_index!` or `Advanced.EnvironmentAPI.bind_environment`. -- `validate_environment_inputs(model)` and - `validate_environment_inputs(compiled_scene, environment_or_backend)` now validate - composite-model/object model application `environment_inputs_` against the active - environment or an explicit replacement. Errors report model application ids, - so duplicate process applications remain diagnosable. -- `Environment(; sources=(target=:source,))` now remaps model-facing - environment variables to backend source variables. Environment binding - refresh validates missing source variables when the backend can enumerate its - variables, and `Diagnostics.explain_environment_bindings` reports both `required_inputs` - and `source_inputs`. -- CompositeModel applications now infer model-author default environment source remaps - from `environment_hint(...).bindings` when the scenario does not provide explicit - environment bindings. Scenario `Environment(; sources=...)` keeps precedence over - the trait. -- Global tabular meteorology is now sampled at each model application's - compiled clock. `environment_hint(...).bindings` reducers and windows are applied - through PlantMeteo, while `Environment(; sources=...)` replaces only the - source variable and preserves the selected reducer. Prepared weather - samplers are shared by applications using the same weather table, and each - application/timestep sample is cached once per run so all target objects - reuse it. -- Object creation, removal, and reparenting invalidate both structural and - environment bindings. Object movement invalidates only environment bindings, - so moving a leaf or changing its geometry can refresh microclimate lookup - without rebuilding object/model binding carriers. -- Added public geometry invalidation helpers: - `update_geometry!(model, object, geometry; invalidate_environment=true)` - and object-scoped `mark_environment_binding_dirty!(model, object)`. - Geometry-only changes record the affected object ids and refresh only their - compiled environment bindings; descendants inheriting moved ancestor - geometry are invalidated as part of the same object-scoped refresh. -- Started composite-model/object execution with `run!(model; steps=...)`. - The runtime refreshes compiled object bindings and environment bindings, - materializes precompiled `ModelSpec(...; inputs=...)` carriers into consumer `Status` - fields, samples the bound environment backend, and calls generic model - kernels through the existing `run!` contract. -- CompositeModel/object execution now publishes model outputs to model-local temporal - streams. Compiled `ModelSpec(...; inputs=...)` bindings marked as `:temporal_stream` can - materialize `HoldLast`, `Interpolate`, `Integrate`, and `Aggregate` values - before the consumer runs, using selector source ids, source variables, - windows, and the model base timestep. -- CompositeModel temporal `ModelSpec(...; inputs=...)` now honor producer `output_policy(...)` traits - when the selector omits `policy=...` and resolves to a unique source - application. Explicit selector policies remain scenario-level overrides. -- CompositeModel `Interpolate(...)` matches the established multirate runtime: - bracketed samples use linear interpolation, online consumers use linear - extrapolation from the last two samples when requested, and insufficient or - non-interpolable values fall back to hold-last. `mode=:hold` and - `extrapolation=:hold` are supported, invalid modes fail during model - compilation, and interpolation arithmetic preserves generic numeric value - types without converting model values to `Float64`. -- Unified `ModelSpec(...; inputs=...)` now supports explicit lagged dependencies with - `PreviousTimeStep(:input) => selector`. Lagged bindings use temporal streams, - read source samples at or before `t - 1`, preserve the initialized consumer - status value until history exists, and do not add a same-timestep scheduling - edge. This allows feedback cycles to compile without changing generic model - kernels. -- CompositeModel/object execution now exposes explicit mutable environment - commits through `commit_environment!(context, accepted_state)` and - non-committing trial sampling through - `run_call!(context, name; environment=trial_state)`. - Meteorological state stays in the environment backend instead of being staged - through same-named status values. -- Added root application scheduling from `ModelSpec(...; every=...)` using `Dates.Period` - values and the model environment base step. `Diagnostics.explain_schedule` on a - `Advanced.CompiledCompositeModel` now reports each application clock, phase, timestep in base - steps, timestep duration in seconds, and whether the application is scheduled - as a root application or is manual-call-only. -- CompositeModel application scheduling now also honors a model's `timespec(...)` trait - when `ModelSpec(...; every=...)` is omitted. Scenario-level `ModelSpec(...; every=...)` keeps - precedence over the model trait, matching the established multirate runtime. -- CompositeModel application scheduling now validates `timestep_hint(...)` required - bounds for base-step-derived clocks. Hints remain compatibility constraints; - they do not override explicit `ModelSpec(...; every=...)` or non-default `timespec(...)`. -- `Advanced.compile_composite_model` now computes a stable topological application order from - resolved `ModelSpec(...; inputs=...)` producer edges and `Updates(...)` writer-order edges. - Inputs produced by manual-call-only applications are redirected to the parent - application that owns the `ModelSpec(...; calls=...)` call stack. `run!(model)` uses this - precompiled order instead of user declaration order, cycles fail at compile - time, and `Diagnostics.explain_schedule` reports `execution_index`. -- `Advanced.CompiledCompositeModel` now pre-indexes input and call bindings by - `(application_id, object_id)`. Per-object input materialization and - `call_targets` lookup uses these indexes instead of scanning every - binding in the model at each model call. -- `Advanced.CompiledCompositeModel` now also pre-indexes applications by application id. - Hard-call target resolution and stable ordered-application materialization - use this index instead of scanning or rebuilding lookup dictionaries. -- `Advanced.CompiledEnvironmentBindings` now pre-indexes environment bindings by - `(application_id, object_id)`. Environment sampling and mutable environment - output scattering use direct lookup instead of scanning all environment - bindings for every model invocation. -- Added `RunContext` and `CallTarget`. Models can retrieve manual - `ModelSpec(...; calls=...)` targets with `call_targets(context, :name)` and execute - them with `run_call!`, preserving explicit call-stack control in the - composite-model/object runtime. Manual calls execute immediately under the parent call - stack; applications selected by `ModelSpec(...; calls=...)` are skipped by the root - `run!(model)` loop and only execute through `run_call!`. -- Added composite-model/object duplicate-writer validation. During `Advanced.compile_composite_model`, each - `(object, output variable)` now has one canonical writer unless later - writers declare `Updates(:var; after=...)`. The `after` token can match a - previous application id/name or process, so scenario authors can express - cases such as pruning after carbon allocation without changing either model - implementation. -- Added `Diagnostics.explain_writers(compiled)`. It reports each object/variable writer - group, duplicate-writer status, writer application ids/processes, and the - `Updates(...)` declarations used to validate ordered updates. -- Extended `explain_model_specs` rows with application name, target selector, - value inputs, manual calls, and environment metadata. -- Started Phase 3 by compiling simple `ModelSpec(...; inputs=...)` declarations to typed - scale/variable carriers, for example - `inputs=(:x => Many(scale=:Leaf, var=:y),)`. -- Added model-level `Input(...)` defaults from `dep(model)` into - `ModelSpec` value inputs. Scenario-level `ModelSpec(...; inputs=(...))` - overrides those defaults before the native binding is compiled. -- Removed the intermediate scenario bridge after the composite-model/object compiler - gained native `ModelSpec(...; inputs=...)` support. Manual value-transfer carriers are not - retained as user-authored API. -- Removed the intermediate dependency resolver after `ModelSpec(...; calls=...)` became - native composite-model/object metadata. Manual model execution now goes through - `CallTargets`, `call_targets`, and `run_call!`. -- Added model-level `Call(...)` defaults from `dep(model)` into - `ModelSpec` manual-call metadata. Scenario-level - `ModelSpec(...; calls=(...))` overrides those defaults, and - `dep(::ModelSpec)` excludes raw `Call(...)` trait entries so default calls - are normalized through the same bridge as explicit calls. -- Migrated the MAESPA example's model energy-balance hard calls to - scenario-level `ModelSpec(scene_model; calls=(...))`. -- Migrated the MAESPA example's model LAI leaf-area transfer to consumer-side - `ModelSpec(LAIModel(...); inputs=(...))`. -- Started Phase 5 with `CompositeModelTemplate` and `ObjectInstance`. A template stores - reusable composite-model/object `ModelSpec`s plus default object labels, and an - instance mounts those specs inside one named object subtree. -- `CompositeModel(...)` accepts `ObjectInstance` values directly or through its - `instances` keyword. An instance root can be an owned `Object` or the id of - an object supplied separately to the model. -- Mounted template applications receive stable instance-prefixed application - names and an implicit `Scope(instance_name)` on unqualified - `ModelSpec(...; on=...)` selectors. Their `ModelSpec(...; inputs=...)`, `ModelSpec(...; calls=...)`, scheduling, - writer validation, and execution use the normal compiled composite-model/object path. -- Instance overrides can replace one template application by application name - or process. Overrides must be unambiguous and preserve process identity. - Instances without overrides retain the exact shared model object from the - template. -- Template labels fill missing `kind` and `species` metadata throughout the - mounted subtree, while the root receives the instance name used by - `Scope(...)`. Tests cover four instances, plant-local aggregation, shared - model storage, and one process-level model override. -- Added explicit exceptional-organ overrides with - `Override(object=..., application=..., model=...)` through - `ObjectInstance(...; object_overrides=...)`. The override must resolve to one - template application, belong to the instance subtree, and preserve process, - input, output, and environment-variable declarations. -- Object overrides remain one logical model application: the compiler stores - the selected replacement model by target object id. Dependency bindings, - writer ownership, application names, and manual calls therefore remain - unchanged, and no selector resolution occurs in the runtime loop. -- Parameter/model ownership is explicit. Templates retain user-supplied model - and `parameters` objects by reference; unchanged instances share them. - Instance and object overrides retain their user-supplied replacement model - by reference. PlantSimEngine does not copy models or mutate model fields to - merge parameter overrides. -- Same-concrete-type object overrides use a concretely typed object-to-model - table. Structured application explanations report shared/per-object storage, - concrete versus heterogeneous dispatch, overridden object ids, and model - types. -- `CompositeModel` retains mounted instance metadata and `Diagnostics.explain_instances(model)` - reports each instance root, current subtree object ids, mounted application - ids, instance/object overrides, template labels, and parameter ownership. - `Diagnostics.explain_objects(model)` also reports instance membership. -- New objects registered below an instance automatically inherit missing - template `kind` and `species` labels. Instance explanations derive membership - from the current topology, so growth, pruning, and reparenting do not leave a - separate stale membership list. -- CompositeModel hard calls can run under temporary local meteorology with - `run_call!(context, name; environment=local_state)`. Descendants sample the - temporary state through normal environment bindings, while `publish=false` - suppresses output publication and environment commits. This supports - iterative microclimate solvers such as the MAESPA model energy-balance loop. -- Model kernels read their own parameters from the `model` argument. Generic - hard-dependency kernels such as `Monteith` and `Fvcb` discover declared call - targets through `call_targets` and execute them through `run_call!`. -- CompositeModel duplicate-writer validation now ignores manual-call-only applications - when validating canonical root writers. This keeps hard-dependency children - from being treated as independent root writers when they intentionally update - the same object status inside their parent call stack. -- Added a unified composite-model/object MAESPA example path: - `build_maespa_scene(...)` and `run_maespa_example(...)`. - It uses `CompositeModelTemplate`, `ObjectInstance`, `on`, `inputs`, `calls`, - and `every=Dates.Period` with two plant species, one shared soil object, - model LAI, and model energy balance. -- `test/test-maespa-model-example.jl` verifies the unified composite-model/object - MAESPA path. -- `run!(model)` now returns a `Simulation` wrapper with the mutated - `CompositeModel`, compiled model bindings, compiled environment bindings, and the - model-local temporal output streams. This keeps existing status mutation - behavior but makes model outputs inspectable after a run. -- Added `outputs(sim::Simulation)`, `collect_outputs(sim)`, and - `Diagnostics.explain_outputs(sim)` for composite-model/object runs. The explanation reports object - ids, variables, publishing application ids, sample counts, time bounds, and - value types. -- `run!(model; tracked_outputs=...)` now accepts `OutputRequest` and returns - requested model outputs through `collect_outputs(sim)` or - `collect_outputs(sim, :request_name)`. CompositeModel requests are materialized from - retained typed temporal streams after the run. They support `HoldLast`, - `Interpolate`, `Integrate`, and `Aggregate`, `Dates.Period` export clocks, - canonical-publisher inference when unique, explicit `process=...` - selection, and dynamic objects over each object's own published sample - interval. -- CompositeModel output requests now compile a publisher-level retention plan. With - `tracked_outputs=nothing`, the model runtime retains all output streams for - historical inspection. With explicit `tracked_outputs`, including an empty - request vector, it retains only requested publisher streams plus streams - required by temporal `ModelSpec(...; inputs=...)`. Dependency-only streams are pruned after - publication to the compiled policy horizon: latest-only for `HoldLast`, the - input window for `Integrate`/`Aggregate`, and enough source history for - `Interpolate`/`PreviousTimeStep`. Explicitly requested streams retain their - complete histories for post-run export. Export is therefore not yet fully - online, but unrequested temporal dependencies no longer grow for the full - simulation. -- Added `Diagnostics.explain_output_retention(sim)` to report which application/variable - streams are retained and whether the reason is default retention, an output - request, or a temporal dependency. Dependency-only rows also report their - compiled `retention_steps`; unbounded requested/default rows report - `nothing`. -- CompositeModel temporal streams are now keyed by application id, object id, and - variable. Multiple applications can publish the same variable on the same - object without overwriting each other's stream samples. -- CompositeModel output-export tests now cover requested-output `DataFrame` - materialization, canonical publisher inference when `process=` is omitted, - rejection when only stream-only publishers exist, and ambiguity when an - explicit process matches both a stream-only and a canonical publisher. -- CompositeModel `OutputRequest(...)` now accepts `application=...` to select an - explicit application id/name when the same process is mounted more than - once. Explicit application selection can retain and export a - `:stream_only` publisher. -- Each model temporal stream owns a concrete `Vector{Tuple{Float64,T}}` - selected from its first published value rather than boxing all values as - `Any`. Output type changes fail explicitly, and `Interpolate`/`Integrate` - tests verify `BigFloat` histories and reduced values remain `BigFloat`. -- CompositeModel `output_routing=(var=:stream_only,)` now matches the unified graph - semantics: stream-only outputs are excluded from canonical writer validation - and same-object input inference, while remaining available in output streams - and explicit `inputs=(... One(application=:name), ...)` selections. -- `run!(model; steps=...)` now refreshes dirty structural bindings at timestep - boundaries. Objects created, removed, or reparented by a model during one - timestep update `ModelSpec(...; on=...)` target sets, input carriers, call targets, - writer validation, and scheduling before the next timestep. -- Geometry-only mutations refresh environment bindings at the next timestep - without recompiling structural bindings. The returned `Simulation` - always contains final compiled structural and environment bindings, including - mutations performed on the last step. -- Environment dirty tracking is now object-scoped for geometry-only changes. - `move_object!`, `update_geometry!`, and - `mark_environment_binding_dirty!(model, object)` retain unaffected compiled - bindings and re-run `Advanced.EnvironmentAPI.bind_environment` only for applications targeting the - changed object. Structural changes and provider-wide invalidation still - rebuild the complete environment cache. -- Runtime lifecycle tests cover a model-created leaf joining a leaf - application and plant-local `RefVector`, a pruned leaf leaving both before - the next step, and a moved leaf switching mock microclimate cells. -- Root model execution now compiles contiguous homogeneous target batches. - Each target prebinds its concrete model, `Status`, input-binding tuple, and - environment binding. Runtime dispatch occurs once - at the batch function barrier; the inner object loop is specialized on a - concrete target type. -- Exceptional object overrides with another concrete model implementation - become separate batches without changing stable object execution order. - Structural or environment binding refresh recompiles the execution plan - before the next timestep. -- Added `Diagnostics.explain_execution_plan(scene_or_simulation)`. It reports batch object - ids, concrete model/status/carrier types, batch sizes, and inner-loop dispatch - semantics. A focused 128-leaf gate verifies zero allocations inside a warmed - homogeneous no-output batch. -- Added `objects_from_mtg(root; ...)` and `CompositeModel(root::MultiScaleTreeGraph.Node; - ...)`. Existing MTG topology is traversed once into the unified registry, - preserving stable node-derived ids, parent relations, labels, geometry, and - explicitly imported runtime status through configurable accessors; the - canonical adapter does not read or write runtime objects in MTG attributes. - -The composite-model/object compiler is executable: selectors normalize to object -addresses, resolve before runtime, and compile into reference, temporal, call, -writer, and environment carriers. The historical mapping compiler has been -removed. - -## Phase 0: Public Contract Freeze - -Goal: decide the small public vocabulary before implementing internals. - -Define: - -- `ModelSpec(model; name=nothing)` as the model-application wrapper. -- `ModelSpec(...; on=selector)` as the target object-set declaration. -- `ModelSpec(...; inputs=...)` for value dependencies. -- `ModelSpec(...; calls=...)` for manual call-stack dependencies. -- `Updates(...)` for rare ordered duplicate writers. -- `every=period::Dates.Period` and related multirate policies. -- `Environment(...)` for optional environment resolver/backend overrides. - -Rules: - -- a model kernel remains generic and declares `inputs_`, `outputs_`, optional - `dep`, optional `environment_inputs_`, and `run!`; -- a model application decides where the kernel runs, at what rate, and how its - inputs, calls, updates, outputs, and environment are bound; -- application ids are stable and can be generated from explicit `name`, - process, object selector, and occurrence index; -- if several applications provide the same process on the same object set, - selectors must disambiguate by application name or another explicit filter. - -Acceptance tests: - -- a model can be applied twice to the same leaf objects with different names; -- a dependency selector can choose by process when unique and by name when not; -- structured explanations expose model kernel type, process, application name, - and target object ids. - -## Phase 1: CompositeModel Object Registry - -Goal: introduce the internal object model without changing public behavior yet. - -Implement: - -- `ObjectId` as the stable identity key for every runtime object. -- `ModelObject` metadata with labels: - `scale`, `kind`, `species`, optional `name`, parent id, child ids, and - optional geometry/position handle. -- `Advanced.ObjectRegistry` storing objects, parent/child relations, and indexes by - label. -- adapters from existing MTG state into the registry: - each selected root and each MTG node gets an object id; - single-status simulations get one object with `scale=:Default`. -- object lifecycle hooks for add/remove/reparent that mirror the existing MTG - runtime reindexing. - -Acceptance tests: - -- the MAESPA example registers five leaf objects, two plant objects, one soil - object, and one model object; -- `status(sim, :plant_A, :Leaf)` and `status(sim, :Leaf)` can be expressed as - registry queries; -- add/remove/reparent updates object registry relations and status views. - -## Phase 2: Selector And Scope Language - -Goal: make "which objects?" explicit and reusable. - -Implement selector types: - -```julia -SceneScope() -Self() -Subtree() -SelfPlant() -Ancestor(scale=:Plant) -Scope(name) -Relation(...) -``` - -Object labels use keyword criteria such as `kind=:plant`, -`species=:oil_palm`, `scale=:Leaf`, and `name=:leaf_1`. - -Implement multiplicity wrappers: - -```julia -One(selector...) -OptionalOne(selector...) -Many(selector...) -``` - -Selectors must normalize to `Diagnostics.ObjectAddress` objects with enough context to be -resolved relative to a consuming object. - -Implement `ModelSpec(...; on=...)` using the same selector system. The target object -set of a model application must never be hidden inside a mapping key or -implicit scale table. - -Definitions: - -- `Self()` means only the current object: the object on which the consuming - model application runs. It is a plant only when that object is the plant. -- `Subtree()` means the current object and its descendants. -- `SelfPlant()` means the nearest containing plant scope. -- `Ancestor(scale=:Plant)` is the generic selector form for `SelfPlant()`. -- `SceneScope()` means the whole model. -- `Scope(name)` means a named scope or object collection. - -Rules: - -- unqualified selectors inside a reusable plant application bundle default to - `within=Self()`; -- model-level selectors default to `within=SceneScope()`; -- `One(...)` errors unless exactly one object resolves per consumer; -- `Many(...)` preserves stable object-id order; -- object-id order replaces incidental traversal order as the semantic default. -- selectors are resolved during compilation or binding refresh, not inside the - inner model loop. - -Acceptance tests: - -- plant allocation on four oil palms reads only leaves under each plant; -- model LAI reads leaves across all plant objects; -- a species-specific model model can read only `species=:oil_palm` leaves; -- a model application target set declared with `ModelSpec(...; on=...)` produces stable - application/object pairs; -- selector errors report available labels and near matches. - -## Phase 3: Unified Value Inputs - -Goal: use `ModelSpec(...; inputs=...)` as the only user-facing value-dependency declaration. -Historical `MultiScaleModel(...)` mappings are migration sources only. - -Target API: - -```julia -ModelSpec(AllocationModel(); on=Many(kind=:plant, scale=:Plant), inputs=(:leaf_carbon => Many(scale=:Leaf, within=Subtree(), var=:leaf_carbon))) - -ModelSpec(LAIModel(area); on=One(scale=:Scene), inputs=(:leaf_areas => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:leaf_area))) -``` - -Implement: - -- `ModelSpec(...; inputs=...)` as `ModelSpec` configuration. -- `Input(...)` or an equivalent internal wrapper that lets `dep(model)` - provide default value-input bindings. -- normalized input bindings from target variable to `Diagnostics.ObjectAddress`. -- compiler pass that decides carrier: - direct reference, `RefVector`, temporal stream, or materialization. -- status-default insertion for materialized target variables using the - consumer model's `inputs_` default. -- temporal policies on value inputs: - `HoldLast`, `Interpolate`, `Integrate`, `Aggregate`. -- `Dates.Period` windows on value inputs, for example `window=Day(1)`. -- copy/reference semantics reporting for every compiled input binding. - -Rules: - -- model authors still declare `inputs_`; scenario authors decide where those - inputs come from; -- `dep(model)` may provide defaults for common value-input bindings in - composite-model/object composition; -- scenario-level `ModelSpec(...; inputs=(...))` always wins over `dep(model)` - defaults; -- same-rate local links should keep reference semantics where possible; -- cross-rate links always go through temporal state; -- duplicate source candidates are errors unless the selector disambiguates; -- materialization carriers, when needed, are internal compiler details - and are not user-authored structs; -- same-rate scalar and many-object links should avoid copies when they can use - aliases, shared refs, `RefVector`, or an equivalent typed carrier; -- PlantSimEngine must preserve arbitrary value types, including units, - automatic differentiation numbers, uncertainty wrappers, and other - numeric-like values. - -Carrier expectations: - -| Binding kind | Runtime carrier | -| --- | --- | -| same-rate scalar | shared `Ref` or local alias | -| same-rate many-object | `RefVector` or equivalent typed reference collection | -| cross-rate | temporal stream sample | -| integrate/aggregate | temporal window reduction | -| materialized cross-object input | generated pre-run status assignment | -| environment | cached environment binding sample | - -Acceptance tests: - -- the MAESPA model LAI cross-object input is declared with `ModelSpec(...; inputs=...)` and - produces the same `lai` and `leaf_area`; -- historical plant allocation `MultiScaleModel([:leaf_carbon => [:Leaf => :leaf_carbon]])` - becomes `ModelSpec(...; inputs=...)` and remains plant-local; -- a same-scale rename currently expressed with `SameScale()` works through - `ModelSpec(...; inputs=...)`; -- multi-rate value inputs integrate object streams by object id. -- same-rate many-object bindings do not allocate per timestep in a benchmarked - hot loop beyond unavoidable model work. -- unitful or dual-number status values survive `ModelSpec(...; inputs=...)` without forced - conversion to `Float64`. - -## Phase 4: Unified Model Calls - -Goal: use `ModelSpec(...; calls=...)` as the only user-facing manual model-call declaration. -The same mechanism must also be usable from `dep(model)` so hard-dependency -traits become default call declarations. - -Target API: - -```julia -ModelSpec( - SceneEB(); - on=One(scale=:Scene), - calls=( - :leaf_energy => - Many(kind=:plant, scale=:Leaf, process=:energy_balance), - :soil => One(kind=:soil, application=:soil_water), - ), -) -``` - -Implement: - -- `ModelSpec(...; calls=...)` as `ModelSpec` configuration. -- `Call(...)` or an equivalent internal wrapper that lets `dep(model)` provide - default manual-call dependencies. -- call resolution from `Diagnostics.ObjectAddress` to concrete `ModelCall` handles, or an - equivalent callable runtime object if the final internal type name differs. -- same-status hard dependency calls using the same public API. -- publication semantics: - trial `run_call!(call)` mutates status only; - final `run_call!(call; publish=true)` appends outputs and temporal - streams. -- structured call explanations with parent application id, selected callee - application ids, selected object ids, selector, and publication behavior. - -Rules: - -- calls are manual call-stack dependencies and are not independently - scheduled under the parent; -- `dep(model)` call defaults are model-author defaults, not final wiring; -- scenario-level `ModelSpec(...; calls=(...))` overrides `dep(model)` defaults; -- hard target outputs still participate in dependency graph compilation through - the owning parent when needed; -- call selection must be visible through explanation helpers. - -Acceptance tests: - -- MAESPA model energy balance uses `ModelSpec(...; calls=...)` and still controls iterative - leaf energy calls; -- missing call selectors report `kind`, `scale`, `process`, and available - matches; -- final accepted calls publish exactly once per timestep. -- an iterative model model can run selected leaf and soil calls several times - with `publish=false` and publish only the accepted state. - -Implemented: - -- `run_call!(::CallTarget)` defaults to `publish=false`, matching the - iterative manual-call contract. -- One-shot accepted calls use `publish=true` explicitly. -- An iterative hard-call regression executes two default non-publishing trials - followed by one accepted call and verifies exactly one environment write and - one temporal output sample for the accepted state. -- `Diagnostics.explain_calls(compiled)` reports - `publication_policy=:explicit_accept`, `default_publish=false`, and - `accepted_publish=true` for every compiled call edge. -- `ModelSpec` now retains per-binding provenance for value inputs and manual - calls. Bindings from `dep(model)` are reported as `:model_default`, - scenario-level `ModelSpec(...; inputs=...)` and `ModelSpec(...; calls=...)` are reported as `:model_spec`, - and compiler-created same-object value links are reported as - `:inferred_same_object`. `Diagnostics.explain_bindings`, `Diagnostics.explain_calls`, and - `explain_model_specs` expose these origins for agent-readable diagnostics. -- Zero-match `OptionalOne(...)` dependencies remain compiled and visible. - Optional inputs retain the consumer `inputs_` default with - `carrier_kind=:optional_default`; optional calls expose an empty target set - and `resolved=false` instead of failing compilation. - -## Phase 5: Object Templates, Instances, And Overrides - -Goal: support several plants of the same species with shared default models and -selective per-instance differences. - -Target API: - -```julia -oil_palm = CompositeModelTemplate( - kind=:plant, - species=:oil_palm, - mapping=oil_palm_mapping, -) - -model = CompositeModel( - ObjectInstance(:palm_1, oil_palm; root=node1), - ObjectInstance(:palm_2, oil_palm; root=node2, overrides=( - stomatal_conductance = Tuzet(; g1=3.2), - )), -) -``` - -Implement: - -- template-level model specs and parameters; -- instance-level model/parameter overrides by process; -- object-level overrides for exceptional organs; -- conflict validation when two overrides target the same process/object. -- shared parameter/model storage when template instances do not override - anything, with explicit copy/ownership behavior when they do. - -Rules: - -- templates do not prescribe topology; they attach mappings to whatever object - tree the instance provides; -- default `Self()` selectors resolve inside the current instance; -- model-wide models must opt into wider scope. - -Acceptance tests: - -- four oil palm instances share model objects/parameters when not overridden; -- one palm instance can override one process parameter; -- allocation remains per plant while model LAI sees all leaves. - -MAESPA status: - -- the unified composite-model/object MAESPA path uses `CompositeModelTemplate` and - `ObjectInstance` for species A and B. - -## Phase 5B: Object Lifecycle And Cache Invalidation - -Goal: make growth, pruning, and moving organs update every compiled binding -through one mutation path. - -Implement public lifecycle hooks: - -```julia -register_object!(model, object; parent) -remove_object!(model, object) -reparent_object!(model, object, new_parent) -move_object!(model, object, geometry_or_position) -Advanced.refresh_bindings!(model) -``` - -Implement invalidation for: - -- object selector caches; -- model application target sets; -- `RefVector` or equivalent many-object carriers; -- temporal stream ownership; -- writer validation; -- environment bindings. - -Rules: - -- topology and geometry changes do not silently leave stale carriers; -- object creation should bind the new object to model applications selected by - `ModelSpec(...; on=...)` before the next timestep; -- moving an object should refresh environment bindings without rebuilding - unrelated model bindings unless the move changes object relations or labels. - -Acceptance tests: - -- creating a new leaf adds it to plant-local allocation and model LAI before - the next timestep; -- pruning/removing a leaf removes it from many-object carriers and temporal - stream ownership; -- changing a leaf insertion angle can refresh only the affected environment - binding when topology is unchanged. - -## Phase 6: Environment Binding Cache - -Goal: make environment and microclimate sampling automatic and fast. - -Implement: - -- `EnvironmentBinding` cache: - object id, backend/provider id, cell/layer id, required variables. -- default environment resolver: - global environment data for non-spatial backends; - object position for spatial backends; - parent position fallback; - global fallback or validation error. -- dirty flags and batched refresh: - `mark_environment_binding_dirty!`; - `update_geometry!(...; invalidate_environment=true)`; - automatic dirty marking on object creation, removal, reparenting, and - environment grid rebuild. -- explanation helper: - `Diagnostics.explain_environment_bindings(sim)`. -- minimal geometry accessors or traits: - `position`, `geometry`, and `bounds`. -- backend protocol: - `Advanced.EnvironmentAPI.bind_environment`, opaque handles, committed/transient `sample`, - `commit_environment!`, and `EnvironmentAPI.update_index!`. -- `Environment(...)` overrides for scenario-specific resolver/backend choices. -- `Environment(; sources=(CO2=:Ca,))` for scenario-specific environment source - remapping without changing model kernels. - -Runtime rule: - -```text -object -> cached binding -> backend cell/layer -> current environment values -``` - -Spatial lookup must happen only during binding refresh, not inside every model -call. - -Acceptance tests: - -- global environment data gives the same values to all objects; -- missing global environment variables fail during environment binding refresh when - the backend can enumerate variables; -- `Environment(; sources=...)` remaps backend variables to model-facing - `environment_inputs_` names and is visible in explanations; -- a model running every two hours over hourly global meteorology receives a - windowed weather sample rather than only the current raw row; -- model `environment_hint` reducers/windows are honored, and an - `Environment(; sources=...)` override changes the source without discarding - the reducer; -- all objects targeted by one application reuse one global weather sample per - application/timestep; -- mock grid backend binds leaves to cells once at initialization; -- moving one leaf marks only that leaf binding dirty and refreshes it before - the next timestep; -- model `environment_inputs_` changes update required variables without recomputing - spatial links unless necessary. -- `commit_environment!(context, accepted_state)` commits mutable microclimate - state back to the active backend. - -## Phase 7: Compiler, Scheduler, And Explanation Cleanup - -Goal: make the unified graph the source of truth. - -Implement: - -- one compiler that builds a global dependency graph over object addresses; -- materialization and multiscale reference wiring as internal carriers; -- object/scope dependency scheduling; -- writer validation through the same graph, including `Updates(...)`; -- model application scheduling from `ModelSpec(...; on=...)` target sets; -- multirate scheduling based on `Dates.Period` values in `ModelSpec(...; every=...)` and - input windows; -- typed compiled bindings that avoid selector resolution in timestep hot loops; -- typed homogeneous execution batches that move dynamic dispatch outside the - per-object inner loop while preserving ordered heterogeneous overrides; -- arbitrary value type preservation through status, input carriers, temporal - storage, and environment samples; -- structured explanation: - `Diagnostics.explain_objects`, `Diagnostics.explain_scopes`, `Diagnostics.explain_bindings`, - `Diagnostics.explain_calls`, `Diagnostics.explain_environment_bindings`, `Diagnostics.explain_schedule`, - `Diagnostics.explain_writers`. - -Acceptance tests: - -- old `MultiScaleModel` examples rewritten with `ModelSpec(...; inputs=...)` produce matching - outputs; -- historical cross-object examples rewritten with `ModelSpec(...; inputs=...)` produce - matching outputs; -- MAESPA hard-call example rewritten with `ModelSpec(...; calls=...)` produces matching - outputs; -- explanation helpers include enough concrete object ids, scales, processes, - and variables for an AI agent to repair bad mappings. -- `Diagnostics.explain_bindings(sim)` reports whether each dependency came from inference, - `dep(model)`, or `ModelSpec`, and reports carrier/copy semantics. -- no selector resolution occurs inside the per-object, per-model timestep loop - for static composite models. -- a warmed homogeneous execution batch performs no allocations beyond model, - output-stream, or backend work requested by the application itself; -- multirate simulations use the same object-address graph as same-rate - simulations. - -## Phase 8: Breaking API Removal And Migration Docs - -Goal: remove the old configuration surface once parity is proven. - -Removed: - -- `MultiScaleModel(...)` as public scenario configuration; -- superseded scenario containers and value-transfer authoring; -- superseded manual-dependency selectors. - -Write migration notes: - -- `MultiScaleModel([:x => [:Leaf => :y]])` -> `inputs=(:x => Many(scale=:Leaf, var=:y),)`; -- cross-object value declarations -> consumer `ModelSpec(...; inputs=...)`; -- manual dependency declarations -> `ModelSpec(...; calls=...)`; -- repeated species assemblies -> `CompositeModelTemplate` plus `ObjectInstance`; -- explicit environment wiring -> environment resolver/binding backend. -- `InputBindings(...)` -> source and temporal policy information inside - `ModelSpec(...; inputs=...)`; -- `MeteoBindings(...)` and `MeteoWindow(...)` -> `Environment(...)` and - environment sampling/window policy; -- `ModelSpec(...; output_routing=...)` -> model-application output policy; -- `PreviousTimeStep(...)` -> temporal policy/cycle-breaking marker in the - unified graph; -- `ScopeModel(...)` -> `ModelSpec(...; on=...)` plus selector scope. - -Regression tests must cover all migrated examples before removal. - -Migration documentation progress: - -- Added `docs/src/migration_composite_model.md` with direct translations for - `MultiScaleModel`, repeated object assemblies, - `TimeStepModel`, `InputBindings`, `MeteoBindings`, `ScopeModel`, and - `SameScale`. -- Documentation navigation and the home page now identify the composite-model/object API - as the target for new multiscale and multi-plant work. -- The documentation home page now uses executable composite-model/object examples as the - primary quickstart. It shows `CompositeModel`, `Object`, `ModelSpec`, `on`, - `inputs`, `every`, automatic same-object binding inference, multi-object - `Many(...)` inputs, and manual `ModelSpec(...; calls=...)` syntax. -- The repository README now mirrors the composite-model/object entry point instead of - teaching `ModelMapping` first. It includes smoke-tested `CompositeModel`/`Object` - quickstart code, `ModelSpec(...; inputs=...)` multi-object coupling, conceptual - `ModelSpec(...; calls=...)` syntax, and links to the migration guide. -- Added `docs/src/composite_model/quickstart.md` as the first native - composite-model/object tutorial page and promoted it in the documentation navigation. - The page contains docs-tested examples for one-object model chaining, - inferred same-object bindings, `OutputRequest` retention, multi-object - `ModelSpec(...; inputs=...)`, `RefVector` carrier explanations, and manual `ModelSpec(...; calls=...)` - syntax. -- The repository agent skill teaches the unified public vocabulary. -- The public API page now starts with curated composite-model/object groups for scenario - construction, selectors, coupling, lifecycle, environment, runtime, and - structured explanations. - -Current removal audit: - -- The unreleased intermediate scenario and runtime subsystem has been deleted, - including its carriers, dependency selectors, target helpers, tests, - examples, and documentation. -- Public manual-call control now uses vector-like `CallTargets`, - `run_call!(context, name)`, `call_targets`, and `run_call!(target)`. -- `RunContext` defines Symbol-named `run_call!` and `call_targets` directly. -- The legacy mapping transforms are removed: - `MultiScaleModel`, `SameScale`, `TimeStepModel`, `InputBindings`, - `MeteoBindings`, `MeteoWindow`, and `ScopeModel` are not retained as - compatibility constructors. -- `ModelMapping` is removed. Retained documentation mentions it only as - historical migration context. -- Historical MTG mapping and mapping-level multirate pages were removed from - the active documentation navigation. A future documentation cleanup can - replace - these historical pages with equivalent composite-model/object tutorials rather than - retaining them as migration reference. -- The model execution page has been rewritten as a composite-model/object-first guide. - It now documents compilation, same-rate reference carriers, temporal - `ModelSpec(...; inputs=...)`, manual `ModelSpec(...; calls=...)`, `Updates(...)`, `ModelSpec(...; every=...)`, - environment binding, output retention, lifecycle cache invalidation, and - compatibility translations from the historical mapping runtime. -- The detailed first simulation tutorial now starts from the composite-model/object API - instead of `ModelMapping`. It introduces model kernels, object status, - compiled applications, inferred same-object bindings, model outputs, and a - short compatibility note for historical mapping examples. -- The quick examples page now uses copy-pasteable composite-model/object examples for - Beer light interception, degree-days/LAI/light coupling, biomass growth, and - retained `OutputRequest` exports. `ModelMapping` appears only in the - compatibility note. -- The standard model coupling, model switching, and coupling more complex - models step-by-step tutorials now teach `CompositeModel`, `Object`, `ModelSpec`, - `on`, `every`, inferred soft `ModelSpec(...; inputs=...)`, and manual - `ModelSpec(...; calls=...)` first. Historical `PlantSimEngine.ModelMapping(...)` appears - only in compatibility notes on those pages. -- The home page has been replaced by native composite-model/object examples. The - repository README has also been replaced by native composite-model/object examples, - and a dedicated composite-model/object quickstart is now available in the main - documentation navigation. -- CompositeModel/object tests cover scheduling, temporal policies, binding inference - and overrides, environment contracts and aggregation, output routing and - application-qualified export, and structured explanations. Legacy mapping - regression tests were removed with the old runtime. -- CompositeModel/object tests now include public environment-contract validation parity for - missing environment variables, explicit `Environment(; sources=...)` - remapping, model-author `environment_hint` source defaults, and validation against - an explicit replacement environment object/backend. -- Test code uses the canonical `ModelSpec(...; every=...)` spelling and composite-model/object - modifiers. Legacy transform tests were removed with the old compatibility - constructors. -- The unified MAESPA path is implemented and tested through `on`, - `inputs`, `calls`, `call_targets`, and `run_call!`. - -## Resolved API Decisions - -- `SceneScope`, `Self`, `Subtree`, `SelfPlant`, `Ancestor`, `Scope`, and - `Relation` are the public topology selector names. Object labels use - `kind=`, `species=`, `scale=`, and `name=` keyword criteria. -- `ModelSpec(...; inputs=...)` is the only scenario-level value-binding - construction form. -- `ModelSpec(...; every=...)` is the canonical timestep configuration. -- `Environment(...)` owns provider/resolver/source configuration. Temporal - value windows belong to the consuming `ModelSpec(...; inputs=...)` selector. -- Object templates own reusable model applications and parameters, not plant - topology construction. They consume explicit object trees or MTGs adapted - through `objects_from_mtg`. -- The old multiscale and mapping-transform implementations have been removed. - -## Completion Evidence - -The requirement-by-requirement evidence and final verification commands are -recorded in `composite_model_completion_audit.md`. diff --git a/docs/src/dev/distributed_output_ownership.md b/docs/src/dev/distributed_output_ownership.md deleted file mode 100644 index ba2e0b7ee..000000000 --- a/docs/src/dev/distributed_output_ownership.md +++ /dev/null @@ -1,330 +0,0 @@ -# Distributed output ownership - -Status: implemented public and compiler contract. - -## Problem - -Most PlantSimEngine applications compute outputs on the same objects on which -they execute. Some scientifically useful models have a different shape: - -- one radiative-transfer model executes once on a complete scene and computes - values for every simulated organ; -- one plant allocation model executes once per plant and computes allocation - and reserve values for many organs; or -- one soil or microclimate model executes on a shared domain and computes local - values for several plant objects. - -These are not hard calls to per-object models. The scene or plant application -owns the computation and cadence, while each destination object owns its local -state value. - -Passing writable `Many(...; from_status=true)` carriers can modify those -values, but it does not declare the producing application as their writer. -Producer inference, scheduling, diagnostics, lifecycle refresh, and output -retention would then lose the scientific ownership of the result. - -## Terms - -- **Execution target:** the object on which an application runs. A scene light - model has one `Scene` execution target. -- **Output destination:** an object whose status owns one output computed by - that application. The same scene light application can have many `Leaf` and - `Internode` destinations. -- **Output binding:** the compiled relationship between one application, - execution target, destination selector, destination object IDs, and declared - output variables. -- **Destination ownership:** the writer relationship - `(destination_object_id, variable) => application_id`. - -Execution targets and output destinations are deliberately distinct. A model -does not need fake per-organ applications merely to publish values computed -elsewhere. - -## Public declaration and scene writer - -The scenario declares named destination groups with `outputs_to`: - -```julia -ModelSpec( - SceneLightModel(solve_light); - name=:scene_light, - on=One(scale=:Scene), - outputs_to=( - organs=OutputTo( - Many( - scale=(:Leaf, :Internode), - within=SceneScope(), - ); - vars=( - incident_par=Default(0.0), - absorbed_par=Default(0.0), - sky_fraction=Required(Float64), - ), - ), - ), -) -``` - -`Default(value)` creates the destination status variable when needed. -`Required(T)` requires it to exist on every selected destination. Only -`coverage=:exact`, the default, is accepted. - -The scene kernel looks up its compiled group and publishes an identified -solver table: - -```julia -PlantSimEngine.@process "scene light" verbose = false - -struct SceneLightModel{F} <: AbstractScene_LightModel - solve::F -end - -PlantSimEngine.inputs_(::SceneLightModel) = NamedTuple() -PlantSimEngine.outputs_(::SceneLightModel) = NamedTuple() - -function PlantSimEngine.run!( - model::SceneLightModel, - status, - environment, - constants, - context, -) - targets = output_targets(context, :organs) - result = model.solve( - runtime_model(context), - environment, - object_ids(targets), - ) - assign_outputs!(targets, result; id=:object_id) - return nothing -end -``` - -`result` may be any Tables.jl-compatible row or column table. Its row order is -independent of selector order because assignment uses `ObjectId` values. - -## `OutputTargets` runtime surface - -`output_targets(context, :organs)` performs a typed lookup on the current -`RunContext`; it does not resolve a selector or rebuild an identity index in -the model call. The group name must be a `Symbol` declared by the current -application. - -The returned `OutputTargets` supports `length`, `isempty`, `eachindex`, and -`object_ids`. Its destination carriers are available only through the explicit -column namespace: - -```julia -targets.columns.incident_par -targets.columns.absorbed_par -``` - -Output variables and compiled-binding metadata are deliberately not forwarded -into the public property namespace: `propertynames(targets)` exposes only -`:columns`. This keeps output names separate from implementation fields. An -output named `columns` remains accessible as `targets.columns.columns`. - -`object_ids(targets)` is an aligned, read-only identity carrier over the -compiled destination IDs. Positions have no botanical meaning. Direct -positional writes to `targets.columns.` are valid when the producing -algorithm already uses this exact identity order; identified external results -should use `assign_outputs!`. - -An `OutputTargets` value belongs to the current model invocation and lifecycle -generation. Kernels obtain it from `RunContext` on every call and do not store -it on their model. - -## Identified assignment - -The Tables.jl path is the general adapter: - -```julia -assign_outputs!(targets, result_table; id=:object_id) -``` - -The lower-level path accepts stable columns directly: - -```julia -assign_outputs!(targets, result_ids, result_columns) -``` - -Here `result_ids` is an `AbstractVector` and `result_columns` is a -`NamedTuple`. The lower-level overload avoids a Tables.jl adapter but uses the -same validation, identity mapping, and assignment implementation. - -Both forms require: - -- one result ID for every current destination; -- no unknown, duplicate, extra, or missing IDs; -- equal lengths for the ID and every declared result column; and -- every variable declared by the `OutputTo` group. - -Additional table or `NamedTuple` columns are metadata and are ignored. They -can carry solver-facing values such as `source_element`, `component_index`, or -geometry provenance without becoming status variables. Conversely, omitting a -declared output is an error even when that destination status already has a -value. - -No subset or retain-last coverage mode exists. An adapter handles filtered, -abscised, dead, or non-geometrized organs deliberately, or the destination -selector excludes them. - -## Identity and permutation cache - -Each compiled output binding stores destination IDs, an ID-to-position index, -and live reference-backed columns. The first assignment validates the result -IDs and compiles either an exact-order marker or a row-to-destination -permutation. - -The runtime cache is keyed by object identity of the result ID column. Reusing -the same ID-column object promises that its IDs and order are immutable; the -cache does not rescan or hash its contents on every timestep. Value columns may -be mutated and reused freely. Replace the ID-column object whenever its IDs or -order changes. - -This contract applies to both public overloads because the Tables.jl path -extracts its ID column before entering the lower-level implementation. Reusing -a table with the same ID carrier reuses the mapping; constructing a new ID -carrier triggers validation and recompilation. - -## Atomic validation and aliasing - -Coverage, column lengths, value conversions, and source/destination aliasing -are checked before any destination status is changed. If mapping validation -fails, the partially reused cache buffers are marked invalid so a later valid -assignment recompiles cleanly. - -A result column may share destination storage only when all three conditions -hold: - -1. the result IDs are already in exact destination order; -2. the source is the same declared output column; and -3. the source and destination use the same complete mapping. - -Permuted views, partially overlapping views, cross-column aliases, and -permuted self-assignment are rejected. Custom array wrappers that can share -storage must implement Julia's `Base.dataids` and `Base.mightalias` contract so -PlantSimEngine can detect that relationship before mutation. - -## Compilation, ownership, and ordinary consumers - -For every output group, compilation resolves: - -1. the producing application and execution object; -2. the destination selector and current destination IDs; -3. declared variables and their `Required` or `Default` initialization; -4. concrete reference-backed destination columns; -5. the destination ID index; and -6. writer ownership for every `(destination_id, variable)` pair. - -Destination status initialization occurs before consumer input compilation. -Writer collisions are rejected unless an existing `Updates(...; after=...)` -declaration establishes intentional ordering. - -A destination model consumes the value through its ordinary input contract: - -```julia -PlantSimEngine.inputs_(::LeafPhotosynthesis) = ( - absorbed_par=Required(Float64), -) - -ModelSpec( - LeafPhotosynthesis(); - name=:leaf_photosynthesis, - on=Many(scale=:Leaf), -) -``` - -Producer inference finds the scene application that owns -`(leaf_id, :absorbed_par)`, binds the leaf status field, and schedules the -scene writer before the leaf consumer. The consumer does not use -`output_targets`, `from_status=true`, a copy model, or an explicit -`after=:scene_light` dependency. - -## Lifecycle - -The scenario application graph and selectors remain immutable while object -membership may change. At a supported lifecycle barrier, PlantSimEngine: - -- rebuilds affected destination memberships and reference columns; -- rebuilds the destination ID index; -- advances the binding membership generation and invalidates result mappings; -- updates writer ownership and consumer scheduling metadata; -- initializes new destination status variables; and -- opens or closes retained streams as requested. - -An empty destination group remains a typed `OutputTargets` group and can gain -members after organ creation. The next model invocation receives the refreshed -view and recompiles its result mapping. Ordinary timesteps do not resolve the -selector or traverse the graph. - -## Output retention and diagnostics - -Retained streams are keyed by producing application, destination object, and -variable. Distributed destinations change which object IDs are enumerated, -not the scientific identity of the producer. - -Use the supported diagnostics rather than inspecting compiled fields: - -- `Diagnostics.explain_output_bindings` shows execution objects, groups, - destination IDs, column carrier types, coverage, and membership generation; -- `Diagnostics.explain_writers` shows the producing application for each - destination variable; -- `Diagnostics.explain_bindings` and `Diagnostics.explain_schedule` show - ordinary consumer coupling and execution order; and -- `Diagnostics.explain_output_retention` shows retained destination streams. - -`outputs=:none` does not allocate destination-history streams. Current values -remain visible through `final_state` because assignment writes directly to -destination statuses. - -## Performance characteristics - -The implementation keeps ordinary applications on their existing path. -Applications without distributed outputs use the empty compiled marker and an -empty output-target tuple; they do not resolve selectors or build assignment -caches. - -For distributed outputs: - -- destination selectors, IDs, indexes, ownership, and columns are compiled - before execution; -- stable ID carriers reuse their exact-order marker or permutation; -- exact-order assignment avoids indexed destination lookup in the write loop; -- homogeneous destination references produce typed `RefVector{T}` columns and - a concrete recursive column loop; -- heterogeneous destination reference types fall back to `ObjectRefVector`, - with conversion against each destination reference; and -- lifecycle changes rebuild only the affected compiled execution targets. - -After warm-up, the stable homogeneous exact-order and permuted columnar paths -can execute without allocations. Heterogeneous destinations preserve correct -per-object types but are an intentionally slower fallback. Benchmark -compilation, lifecycle refresh, steady-state assignment, and output collection -separately when changing these internals. - -## Alternatives rejected - -### A second `Many` of IDs - -This duplicates compiler-owned identity, lets selectors diverge, and treats -identity as a biological input. It also does not solve writer ownership, -scheduling, or retention. - -### Fake per-object applications - -These misrepresent computation and cadence, enlarge the application graph, and -make bookkeeping models appear scientifically meaningful. - -### Public `CallTargets` reuse - -`CallTargets` represents executable callee applications and includes model, -environment, status-view, and hard-call state. Distributed outputs need the -lighter columnar `OutputTargets` view. - -### Per-step table join - -A table join or MTG traversal in every model execution is avoidable work and -makes ordering errors possible. PlantSimEngine compiles the identity mapping -once per stable ID carrier and invalidates it when destination membership -changes. diff --git a/docs/src/dev/maespa_model_handoff.md b/docs/src/dev/maespa_model_handoff.md deleted file mode 100644 index b04d9edf1..000000000 --- a/docs/src/dev/maespa_model_handoff.md +++ /dev/null @@ -1,161 +0,0 @@ -# MAESPA-Style CompositeModel Example Handoff - -The executable acceptance example is `examples/maespa_model_example.jl`, with -focused coverage in `test/test-maespa-model-example.jl`. - -## CompositeModel Shape - -- One `:Scene` object owns canopy microclimate and model-scale fluxes. -- One shared `:Soil` object owns soil water state. -- Species A and B are reusable `CompositeModelTemplate`s mounted as independent - `ObjectInstance`s. -- Each plant instance contains one plant object, one internode object, and its - own leaf objects. -- Species parameters differ while the model application structure is shared. - -Leaf applications use the copied PlantBiophysics subsample models: - -- `Monteith` for `:energy_balance`; -- `Fvcb` for `:photosynthesis`; -- `Tuzet` for `:stomatal_conductance`. - -## Coupling - -The model energy-balance application controls iterative canopy-air, leaf, and -soil calls. `ModelSpec(...; calls=...)` expresses execution ownership only: the scene model -decides when subprocesses run. - -```julia -ModelSpec(scene_model; name=:scene_eb, on=One(scale=:Scene), inputs=(:psi_soil => - One(kind=:soil, scale=:Soil, application=:soil_water, var=:psi_soil),), calls=(:energy_balance => - Many(kind=:plant, scale=:Leaf, process=:energy_balance), - :soil => - One(kind=:soil, scale=:Soil, application=:soil_water),), environment=Environment(provider=:forcing, sink=:canopy), every=Dates.Hour(1)) -``` - -The scene receives above-canopy forcing from the `:forcing` provider and has -`:canopy` as its explicit commit sink. Trial leaf calls use -`run_call!(context, :energy_balance; environment=trial_environment)`, so all hard-called -leaves sample the trial canopy atmosphere through their compiled handles without -committing it. After convergence, the scene commits the accepted canopy -atmosphere with `commit_environment!(context, accepted_environment)` and publishes one -accepted leaf call against that committed environment. - -Scene/soil values are wired declaratively with `ModelSpec(...; inputs=...)`, not by manually -writing another object's status. The soil model receives accepted scene fluxes -through live references: - -```julia -ModelSpec(SoilWater(...); name=:soil_water, on=One(kind=:soil, scale=:Soil), inputs=(:transpiration => - One( - scale=:Scene, - within=SceneScope(), - application=:scene_eb, - var=:scene_transpiration, - ), - :infiltration => - One( - scale=:Scene, - within=SceneScope(), - application=:scene_eb, - var=:scene_infiltration, - ),), every=Dates.Hour(1)) -``` - -This creates a parent-controlled feedback loop: the scene reads mapped -`psi_soil` when it starts its energy-balance solve, computes accepted scene -water fluxes, writes `scene_transpiration` and `scene_infiltration`, then calls -the soil model. The soil call sees those scene values through input carriers -and publishes the updated soil state. If the intended science is an explicit -lag rather than same-step parent control, use `PreviousTimeStep(:psi_soil)` on -the scene input. - -CompositeModel LAI receives live references to every leaf area: - -```julia -ModelSpec(LAIModel(ground_area); name=:lai_dynamic, on=One(scale=:Scene), inputs=(:leaf_areas => Many( - kind=:plant, - scale=:Leaf, - within=SceneScope(), - process=:leaf_state, - var=:leaf_area, - ),), every=Dates.Day(1)) -``` - -The scene energy-balance model uses the same mapping mechanism for leaf-scale -values needed during the hard-call solve. It maps leaf area, leaf carbon, trial -leaf inputs (`Ra_SW_f`, `aPPFD`, `Ψₗ`), and accepted leaf fluxes (`Rn`, `λE`, -`H`, `A`) into scene-level vector inputs. The scene model then writes or reads -those vectors, while the referenced leaf statuses remain the single source of -truth. - -```julia -ModelSpec(scene_model; name=:scene_eb, on=One(scale=:Scene), inputs=(:leaf_areas => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:leaf_area), - :leaf_carbon => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:leaf_carbon), - :leaf_Ra_SW_f => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:Ra_SW_f), - :leaf_aPPFD => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:aPPFD), - :Ψₗ => Many(kind=:plant, scale=:Leaf, within=SceneScope(), var=:Ψₗ), - :leaf_rn => Many(kind=:plant, scale=:Leaf, within=SceneScope(), policy=HoldLast(), var=:Rn), - :leaf_lambda_e => Many(kind=:plant, scale=:Leaf, within=SceneScope(), policy=HoldLast(), var=:λE), - :leaf_h => Many(kind=:plant, scale=:Leaf, within=SceneScope(), policy=HoldLast(), var=:H), - :leaf_a => Many(kind=:plant, scale=:Leaf, within=SceneScope(), policy=HoldLast(), var=:A),)) -``` - -`HoldLast()` is intentional for the leaf flux vectors: it asks the compiler for -live references to the current held status values, so the parent scene solve can -iterate hard-call trial states without materializing temporal streams. - -Allocation is plant-local because its leaf selector uses `within=Subtree()`: - -```julia -ModelSpec(allocation; name=:allocation, on=One(scale=:Plant), inputs=(:leaf_carbon => Many(scale=:Leaf, within=Subtree(), var=:leaf_carbon)), every=Dates.Day(1)) -``` - -## Meteorology - -Input meteorology is above-canopy forcing wrapped in a -`MaespaSingleLayerEnvironment`. The backend stores two meteorological states: - -- `forcing`: the above-canopy `Weather`/time series sampled by the scene; -- `canopy`: the mutable canopy `Atmosphere` sampled by every leaf. - -The scene application uses `Environment(provider=:forcing, sink=:canopy)`. -Leaf energy-balance applications use `Environment(provider=:canopy)`. The -one-layer backend does not look at process names, geometry, or cells; all leaves -intentionally sample the same current canopy atmosphere. - -`canopy_air_update(...)` is a plain helper, not a model application. It reads -canopy-scale leaf fluxes aggregated in the scene, computes the MAESPA-style -canopy air update, and returns a new `Atmosphere`. The accepted solution is -committed directly with: - -```julia -commit_environment!(context, accepted_environment) -``` - -CompositeModel status also stores diagnostics for the resulting below-canopy -microclimate: - -- `canopy_tair`; -- `canopy_vpd`; -- `canopy_rh`; -- `canopy_htot`; -- `canopy_gcanop`. - -Trial iterations pass the candidate atmosphere through `run_call!`, preserving -the leaf applications' compiled provider handles. The accepted state is the -only state committed to the mutable environment backend. - -## Acceptance Checks - -The focused test verifies: - -- five leaves across two species and one shared soil object; -- instance membership and mounted application ids; -- model calls to all leaf energy-balance applications and the soil model; -- nested `Monteith -> Fvcb -> Tuzet` call bundles; -- live-reference LAI and plant-local allocation bindings; -- hourly energy balance and daily LAI/allocation schedules; -- exactly one accepted publication per manually called target and timestep; -- finite canopy microclimate, leaf energy, photosynthesis, soil feedback, and - species-specific allocation after a 25-hour run. diff --git a/docs/src/dev/public_api_refinement_completion_audit.md b/docs/src/dev/public_api_refinement_completion_audit.md deleted file mode 100644 index 023b63fb8..000000000 --- a/docs/src/dev/public_api_refinement_completion_audit.md +++ /dev/null @@ -1,43 +0,0 @@ -# Public API Refinement Completion Audit - -This audit records the supported contract and the evidence used to stabilize it. -It complements the [decision record](public_api_refinement_decisions.md) and the -[public symbol inventory](../API/public_symbols.md). - -## Contract evidence - -| Requirement | Supported contract | Evidence | -|:--|:--|:--| -| Public boundary | Composition, model-author, diagnostic, and extension symbols are exported by default; compiler/cache representations live under `PlantSimEngine.Advanced`. | `test-model-api-stabilization.jl` checks the namespace boundary; Documenter's missing-doc check covers exported docstrings. | -| Application identity | Repeated process applications require explicit names. Inputs, calls, outputs, overrides, and `Updates(...; after=...)` use canonical application IDs. Singular process references are rejected; `Many(process=...)` remains an explicit discovery query. | Stabilization, binding-inference, hard-call, output, override, and update tests cover repeated applications and actionable errors. | -| Selector grammar | `Self()` is one object, `Subtree()` is that object plus descendants, `SelfPlant()` is the containing plant, and `SceneScope()` is the model. `One`, `OptionalOne`, and `Many` share the same criteria across targeting, coupling, lookup, and outputs. | Multi-plant selector tests, instance/template tests, lifecycle tests, and XPalm downstream tests. | -| Outputs | `outputs=:none` is the safe default; `:all` and selector-based `OutputRequest`s are explicit. Request names are unique, application identity is preserved, and removed-object history remains collectable. | Output-boundary, runtime-matrix, multirate, lifecycle-history, and allocation tests. | -| Execution ownership | `run!` starts a fresh simulation; `continue!` and `step!` advance its live handle without resetting time, streams, schedules, or environment position. | Split-run equivalence, multirate-boundary, environment-resume, and lifecycle-continuation tests. | -| Construction and initialization | `CompositeModel(models...; status=...)` lowers to ordinary objects and `ModelSpec`s. `Diagnostics.explain_initialization` reports application, object, origin, defaults, expected/provided types, and remedies without running kernels. | Concise/explicit lowering equivalence and initialization report tests. | -| Diagnostics | Supported explanation functions accept `CompositeModel` directly and compiled views where useful; simulation overloads avoid field inspection. Results are structured vectors that can be filtered with ordinary Julia predicates. | Structured explanation assertions throughout the model test matrix and documentation examples. | -| Lifecycle | Registration, MTG growth, removal, reparenting, movement, and geometry updates are the supported mutation paths. Cycle/self-parent failures are atomic; structural and geometry invalidation remain targeted. | Stabilization, unified integration, environment, and lifecycle-output tests. | -| Model-author API | The kernel is `run!(model, status, environment, constants, context)`. Model parameters come from `model`; `runtime_model`, call-target accessors, traits, and lifecycle helpers are the supported context surface. | `test-model-contract.jl`, hard-call tests, growing-plant tutorial, and downstream model suites. | -| Compatibility | `tracked_outputs`, singular scenario `process=` references, output-request `process=`, and process-only overrides are removed. Mapping runtimes are not restored. | Migration guide plus rejection tests. | - -## Validation matrix - -The release gate is: - -1. complete PlantSimEngine package tests, including allocation gates and doctests; -2. a full Documenter build with missing-doc and executable-example checks; -3. full PlantBiophysics and XPalm downstream suites against this checkout; -4. benchmark smoke tests for native, multirate, PlantBiophysics, and XPalm paths; -5. `git diff --check` and searches for transitional spellings outside explicit - migration/history documentation. - -This matrix covers one/many objects, all selector multiplicities, soft inputs, -hard calls, duplicate writers, temporal policies, global/spatial environments, -templates, instances, overrides, lifecycle mutation, generic values, output -retention modes, fresh/continued execution, and homogeneous hot-loop allocation. - -## Deliberate compatibility boundary - -Compiled structs and cache controls are qualified advanced APIs and may evolve. -Direct mutation of `Object` or `CompositeModel` fields is unsupported. Historical -`ModelMapping`, executor, and status-vector runtimes are outside the compatibility -surface and must not be reintroduced. diff --git a/docs/src/dev/public_api_refinement_decisions.md b/docs/src/dev/public_api_refinement_decisions.md deleted file mode 100644 index fbc768925..000000000 --- a/docs/src/dev/public_api_refinement_decisions.md +++ /dev/null @@ -1,105 +0,0 @@ -# Public API refinement decisions - -This decision record defines the target public contract for the CompositeModel/Object -API. The CompositeModel/Object compiler and runtime remain the only supported scenario -runtime. - -## Terminology and identity - -- An **object** is one runtime entity with a stable `ObjectId`. -- A **model** is one scientific implementation of a process. -- A **process** is model metadata and may have several applications. -- An **application** is one named, configured occurrence of a model in a model. -- User declarations that identify a producer, writer, update predecessor, call - target, or output stream use application identity. -- Process queries are discovery filters. They are not substitutes for an - application identifier when more than one application matches. -- Every application receives a deterministic identifier. An explicit - `ModelSpec(...; name=...)` is used verbatim. An unnamed application uses its - process name only when that identifier is unique; repeated unnamed - applications are rejected with instructions to name them. -- Mounted template applications are qualified as - `instance_name__application_name`. - -## Object selectors and scope - -The same `One`, `OptionalOne`, and `Many` selector values are accepted by -application targeting, inputs, calls, object queries, and output requests. - -Scope names have one meaning: - -- `Self()` selects only the current object. -- `Subtree()` selects the current object and all of its descendants. -- `SelfPlant()` selects the current object's plant root and its descendants. -- `Ancestor(...)` selects the matching ancestor's subtree. -- `SceneScope()` searches the whole model. -- `Scope(name)` searches the named object's subtree. -- `Relation(...)` selects objects with the requested topological relationship. - -Selectors that require a current object fail when used without a context. -Cross-object coupling is always visible in the declaration through `Subtree`, -`SelfPlant`, `Ancestor`, `Scope`, `SceneScope`, or `Relation`. - -## Outputs - -`run!` uses an explicit `outputs` keyword: - -```julia -run!(model; outputs=:none) -run!(model; outputs=:all) -run!(model; outputs=request) -run!(model; outputs=requests) -``` - -The default is `outputs=:none`. Temporal dependency streams required by the -runtime are still retained with bounded histories; they are not user-retained -outputs. - -The former `tracked_outputs` keyword has been removed. Use `outputs` directly; -there is no dual spelling. - -An `OutputRequest` contains an object selector, a variable, an optional -application identifier, a unique result name, and optional temporal resampling -policy. `OutputRequest(:Leaf, :x)` remains a convenience spelling that lowers -to `OutputRequest(Many(scale=:Leaf), :x)` during migration. - -## Execution and continuation - -`run!(model; steps=n, ...)` starts a fresh result timeline at step one while -mutating model status. It returns a live `Simulation` execution handle. - -`continue!(simulation; steps=n)` advances that simulation from its current -step, preserving retained streams, temporal dependency history, environment -position, and multirate clock phase. It returns the same simulation. - -`step!(simulation)` is equivalent to `continue!(simulation; steps=1)`. - -Calling `run!` on an already-mutated model intentionally creates a new result -timeline. Users who intend temporal continuation use `continue!`; the distinct -operation prevents an accidental step-index reset. - -Lifecycle mutations between calls to `continue!` are compiled before the next -timestep using the existing targeted invalidation contract. - -## Public namespaces - -The default namespace is organized around: - -- model composition and execution; -- model-author declarations and kernel helpers; -- supported structured explanations; -- documented environment extension interfaces. - -Compiled representation types, cache dirty flags, raw compiler stages, and -low-level invalidation helpers are qualified advanced/internal APIs unless a -documented external extension requires them. Removing an export does not make a -symbol inaccessible through `PlantSimEngine.Symbol`; it removes the accidental -promise that ordinary users should depend on it. - -## Compatibility policy - -- Removed legacy mapping/executor APIs are not restored. -- Superseded CompositeModel/Object spellings are removed rather than retained - as aliases or fallback methods. -- Benchmarks, examples, documentation, PlantBiophysics, and XPalm target the - canonical API. diff --git a/docs/src/dev/release_notes_handoff.md b/docs/src/dev/release_notes_handoff.md deleted file mode 100644 index 9a5b694a9..000000000 --- a/docs/src/dev/release_notes_handoff.md +++ /dev/null @@ -1,521 +0,0 @@ -# Release Notes Handoff - -This page is the persistent release-note source for the composite-model/object redesign -and cleanup branch. Keep it factual: mark what is implemented, what is removed, -and what is only planned. - -## Implemented Breaking Cleanup - -Source details live in `code_cleanup_audit.md`. - -- Removed `ModelList`, `ModelMapping`, `GraphSimulation`, `MultiScaleModel`, - and the separate mapping dependency/runtime stack. Use `CompositeModel`, `Object`, - and model applications. -- Removed direct and batch mapping `run!` methods. -- Removed string scale names. Use symbols, for example `:Leaf`. -- Removed mapping-specific type-promotion configuration. -- Removed `ModelMapping` completely; it is not retained as a qualified - compatibility API. -- Removed old multiscale output indexing helpers. Convert outputs explicitly - before indexing. -- Replaced mapping-specific same-scale rename sentinels with - `inputs=(:local => One(within=Self(), var=:source),)`. -- Removed unused parallel-executor traits after deleting the executor runtime. -- Removed dead mapping-era wrappers and traits: `UninitializedVar`, - `RefVariable`, `TreeAlike`, and `StatusView`. -- Removed the unreleased `CompositeModelTemplate(...; mapping=...)` alias and dead - selector-to-mapping conversion helpers. -- Removed stale `PlantSimEngine.Examples` exports for the deleted - `ToyInternodeEmergence` example. -- Replaced many source-side validation `@assert`s with explicit errors. -- Added `Updates(:var; after=:application)` for ordered duplicate writers. -- Added `runtime_model(runtime)` as the sanctioned live-model accessor for - `RunContext` and `Simulation`; kernels no longer need to inspect - `context.compiled.model`. -- Added `Diagnostics.explain_initialization(model)` with structured `:required`, - `:defaulted`, `:supplied`, `:generated`, `:producer_bound`, and - `:environment_bound` dispositions. -- Added `CompositeModel(model, models...; status=...)` as a thin one-object constructor - that lowers to the normal object and `ModelSpec` representation. -- Calendar-aligned windows remain unsupported. Temporal windows use - duration-based `Dates.Period` semantics. - -## Removed Unreleased Scenario Prototype - -An experimental scenario runtime was developed and replaced on this branch -before release. Its source, tests, examples, and documentation were removed -rather than retained as compatibility code. - -The removed API included `Domain`, `SimulationMapping`, `Route`, -`AllDomains`, and `HardDomains`, together with the domain scheduler, run loops, -route materialization, environment bridge, graph runner, and output publisher. -Because this API was never released, there is no compatibility layer or user -migration path for it. - -The reusable behavior now lives in the composite-model/object runtime: object selectors, -compiled `ModelSpec(...; inputs=...)`, manual `ModelSpec(...; calls=...)`, `Dates`-based scheduling, -environment backends, dynamic object lifecycle handling, and structured -explanations. - -Dynamic MTG growth now has one public high-level operation: `add_organ!`. -An MTG-backed `CompositeModel` retains the accessors and status initializer used during -initial adaptation. By default, `add_organ!` reuses that policy for new nodes, merges -explicit initial values, attaches the resulting `Status`, registers the model -object, and invalidates runtime bindings. `register_object!` remains available -as the low-level registry operation. XPalm and PlantGeom were migrated away -from package-local wrappers that duplicated this lifecycle sequence. - -Topology engines that have already made a new node's attributes authoritative -may call `add_organ!(...; use_status_adapter=false)`. This advanced opt-out -skips only the stored adapter status initializer; PlantSimEngine still copies -the node attributes, applies explicit initial values with the normal -precedence, forces the exact node identity, registers the object, and -invalidates bindings. Callers must not disable the adapter when it contributes -fields that are absent from the new node. - -## Implemented MAESPA-Style Example Changes - -The current `examples/maespa_model_example.jl` is the main executable example -for multi-plant model coupling. - -- Uses copied PlantBiophysics subsample models: - `Monteith`, `Fvcb`, and `Tuzet`. -- Uses two plant instances with different parameters and shared scale names - such as `:Plant` and `:Leaf`. -- Uses a shared soil model. -- Uses `SceneEB` with `ModelSpec(...; calls=(...))` to manually run leaf - `:energy_balance` and soil `:soil_water` targets. -- Ports MAESPA-style canopy air temperature and VPD update through the - `canopy_air_update(...)` helper and `gbcanms`. -- Treats input meteorology as above-canopy forcing, runs trial leaves with - `run_call!(...; environment=trial_state)`, commits accepted canopy - meteorology with `commit_environment!`, and writes - below-canopy microclimate diagnostics to model status fields: - `canopy_tair`, `canopy_vpd`, `canopy_rh`, `canopy_htot`, and - `canopy_gcanop`. -- Adds `LAIModel` and declares plant leaf-area materialization with - `ModelSpec(...; inputs=(...))`. -- Computes plant allocation daily from plant-local `leaf_carbon` vectors. -- Adds `run_call!` for manually executing compiled model call targets. -- Adds model-level `Input(...)` and `Call(...)` dependency defaults through - `dep(model)`, with scenario-level `ModelSpec(...; inputs=...)` and `ModelSpec(...; calls=...)` overriding - those defaults in `ModelSpec`. -- Adds initial registry-backed model selector resolution with - `resolve_object_ids` and `resolve_objects` for global, self-relative, - plant-relative, ancestor-relative, and named-scope object selections. -- Adds `Diagnostics.explain_scopes(model)` for structured scope diagnostics. It reports - the model scope, object subtree scopes, named `Scope(...)` entries, and - scale/kind/species label groups with concrete object ids. -- Selector failures now include context, matched object ids, requested - criteria, available labels, and near-match suggestions. Misspelled labels - such as `scale=:Leef` therefore suggest `:Leaf` instead of returning only a - cardinality count. -- `Relation(...)` now supports `:self`, `:parent`, `:children`, `:ancestors`, - `:descendants`, and `:siblings` in object-relative input, call, and query - selectors. Relation results are compiled to concrete object ids and may be - constrained by an explicit scope. Application targets reject relations - because they have no current object context. -- Selector labels now have one spelling (`scale=:Leaf`, `kind=:plant`, - `species=:oil_palm`, and `name=:leaf_1`); the duplicate `Scale`, `Kind`, and - `Species` wrappers were removed. `Diagnostics.ObjectAddress` preserves all normalized - object, routing, temporal, and status-ordering fields, while positional - topology selectors such as `Relation(:parent)` remain supported. -- Adds the first compiled composite-model/object view with `Advanced.compile_composite_model`, - `Advanced.CompiledCompositeModel`, `Advanced.CompiledModelApplication`, `Advanced.CompiledModelInputBinding`, - `Advanced.CompiledModelCallBinding`, `Diagnostics.explain_applications`, - `Diagnostics.explain_bindings`, and `Diagnostics.explain_calls`. -- The compiled model view resolves `ModelSpec(...; on=...)`, `ModelSpec(...; inputs=...)`, and - `ModelSpec(...; calls=...)` to object ids ahead of runtime, and reports temporal policy, - window, carrier hints, and callee application ids for agent-readable - diagnostics. -- Unscoped composite-model/object dependency selectors now infer scope from the consumer: - model consumers default to `SceneScope()`, while non-model consumers default - to `Self()`. Cross-scope shared dependencies, such as leaf models reading - soil state, should use `within=SceneScope()` explicitly. -- Adds status-backed compiled input carriers for the composite-model/object view: - scalar shared refs, homogeneous `RefVector`s, and `Advanced.ObjectRefVector` fallback - carriers. `Diagnostics.input_carrier`, `Diagnostics.input_value`, and `Diagnostics.has_reference_carrier` expose - them for tests, diagnostics, and future runtime execution. -- Same-rate model inputs are now wired into consumer `Status` references once - during compilation. Scalar and `Many(...)` inputs remain live references, - missing bound input fields are compiler-generated without inventing - canonical values for `Required(T)`, and repeated non-temporal input - materialization is allocation-free. -- Same-rate `ModelSpec(...; inputs=...)` carriers preserve arbitrary concrete value types. - Regression coverage passes a dual-like `BigFloat` wrapper through a typed - `RefVector`, model arithmetic, source mutation, and output publication - without conversion to `Float64`. -- Same-object variable renaming now uses normal `ModelSpec(...; inputs=...)` syntax instead of - `SameScale()`. Renamed inputs share the producer reference and contribute the - expected producer-to-consumer scheduling edge. -- `Diagnostics.explain_bindings` now reports stable carrier kind and copy/reference - semantics, making reference-wired inputs and materialized temporal values - explicit for users and agents. -- Adds model binding cache helpers: - `Advanced.refresh_bindings!`, `Advanced.bindings_dirty`, `Advanced.compiled_bindings`, and - `Advanced.model_revision`. Object registration, removal, and reparenting invalidate - cached compiled bindings before the next refresh. -- Adds composite-model/object environment binding cache helpers: - `Advanced.refresh_environment_bindings!`, `Advanced.compile_environment_bindings`, - `Advanced.CompiledEnvironmentBinding`, `Advanced.CompiledEnvironmentBindings`, - `Advanced.environment_bindings_dirty`, `Advanced.compiled_environment_bindings`, - `Advanced.environment_revision`, and `Diagnostics.explain_environment_bindings`. -- Adds `geometry`, `position`, and `bounds` accessors for model objects/statuses. - Environment binding refreshes call `EnvironmentAPI.update_index!(backend, changed_entities, removed_object_ids)` before - binding objects to backend cells/layers, so spatial backends can precompute - model-wide lookup structures. -- Spatial environment binding now falls back to the nearest ancestor geometry - for objects without their own geometry. Binding explanations expose the - geometry provenance, and moving an ancestor refreshes only descendants that - inherit its geometry. -- Environment binding refresh can now update changed `environment_inputs_` metadata - without repeating spatial indexing or cell lookup when the - application/object/provider/geometry contract is otherwise unchanged. -- `Environment(; sources=(CO2=:Ca,))` now remaps model-facing environment - variables to backend source variables. CompositeModel environment binding refresh - validates missing source variables for enumerable backends such as - `EnvironmentAPI.GlobalConstant`, and explanations expose both `required_inputs` and - `source_inputs`. -- `validate_environment_inputs(model)` and - `validate_environment_inputs(compiled_scene, environment_or_backend)` now validate - composite-model/object environment contracts directly. Missing-variable diagnostics use - model application ids, and validation honors both scenario - `Environment(; sources=...)` remaps and model-author `environment_hint` defaults. -- Object movement now invalidates environment bindings without rebuilding the - structural object/model binding cache. -- Adds public geometry lifecycle helpers: - `update_geometry!(model, object, geometry; invalidate_environment=true)` and - object-scoped `mark_environment_binding_dirty!(model, object)`. They - currently invalidate the model environment binding cache and leave room for - finer-grained dirty tracking later. -- Adds the first composite-model/object runtime with `run!(model; steps=...)`. - It materializes compiled `ModelSpec(...; inputs=...)` carriers, samples bound environment - inputs, and executes generic model kernels on object `Status` values. -- CompositeModel/object compiler now infers simple same-object value bindings from - `inputs_`/`outputs_` when one producer is unambiguous. `Diagnostics.explain_bindings` - reports each binding origin, including `:model_default`, `:model_spec`, and - `:inferred_same_object`. -- Compiled input bindings now validate `ModelSpec(...; inputs=...)` `process=`/`application=` - filters when they are provided, and `Diagnostics.explain_bindings` reports - `source_application_ids`, `process`, and `application`. -- `Advanced.compile_composite_model` now errors for required `inputs_(model)` variables that are - neither bound through `ModelSpec(...; inputs=...)`/inference nor present on the target object - `Status`. -- `Advanced.compile_composite_model` now prepares model-owned status schemas automatically: - model-targeted objects may omit `Status`, declared outputs and `Default` - inputs are inserted from their initial values, and bound `Required` inputs - are installed through their compiled carriers. External unbound `Required` - inputs still need explicit initialization. -- `Advanced.compile_composite_model` now rejects `ModelSpec(...; inputs=...)` entries whose receiving variable is - not declared by the model's `inputs_`, making binding typos explicit at - compile time. -- `Advanced.compile_composite_model` now validates status-backed non-temporal `ModelSpec(...; inputs=...)` - source availability, so bindings that select existing source objects but no - source `Status` reference fail at compile time instead of becoming no-ops. -- CompositeModel/object runtime now publishes model outputs to model-local temporal - streams and resolves temporal `ModelSpec(...; inputs=...)` with `HoldLast`, `Integrate`, - and `Aggregate` policies before consumer execution. -- CompositeModel temporal `ModelSpec(...; inputs=...)` now use producer `output_policy(...)` traits as - the default when the selector omits `policy=...` and resolves to a unique - source application. Explicit selector policies override the trait. -- CompositeModel applications now infer model-author default environment source remaps - from `environment_hint(...).bindings` when the scenario does not provide explicit - environment bindings. Scenario `Environment(; sources=...)` remains the override. -- CompositeModel/object runtime exposes `run_call!(...; environment=trial_state)` - for non-committing trial meteorology and `commit_environment!` for accepted - mutable environment - commits from model kernels. -- CompositeModel/object root applications now honor `ModelSpec(...; every=...)` values backed by - `Dates.Period` scheduling. `Diagnostics.explain_schedule` reports normalized clocks and - whether an application is root-scheduled or manual-call-only. -- CompositeModel/object root applications now also honor `timespec(...)` model traits - when no explicit `ModelSpec(...; every=...)` is provided. Scenario-level `ModelSpec(...; every=...)` - remains the override. -- CompositeModel/object root applications now validate `timestep_hint(...)` required - bounds for clocks derived from the model base step. Hints remain - compatibility constraints, not scheduling overrides. -- CompositeModel/object execution now uses a stable topological application order - compiled from `ModelSpec(...; inputs=...)` producer edges and `Updates(...)` ordering. - Dependencies on manual-call-only applications are redirected to their parent - caller, same-timestep cycles fail during compilation, and - `Diagnostics.explain_schedule` reports `execution_index`. -- `Advanced.CompiledCompositeModel` now pre-indexes input and call bindings by application and - object id. Runtime input materialization and hard-call lookup no longer scan - all model bindings for every object/model invocation. -- `Advanced.CompiledCompositeModel` now pre-indexes applications by application id, removing - application scans from hard-call target resolution and dictionary rebuilding - from ordered execution setup. -- `Advanced.CompiledEnvironmentBindings` now pre-indexes environment bindings by - application and object id, removing the model-wide binding scan from - environment sampling and output scattering. -- Adds `RunContext` and `CallTarget`; composite-model/object models can use - `run_call!(context, :name)` plus `call_targets(context, :name)` for fine-grained manual `ModelSpec(...; calls=...)` - execution. -- Applications selected by `ModelSpec(...; calls=...)` are skipped by the root - `run!(model)` loop and execute only through explicit `run_call!`, preserving - parent-controlled hard-call execution. -- Adds composite-model/object duplicate-writer validation in `Advanced.compile_composite_model`. A variable - may have only one canonical writer per object unless later writers declare - `Updates(:var; after=...)`, where `after` can match a previous application - id/name or process. -- Adds `Diagnostics.explain_writers(compiled)` to report object-variable writer groups, - duplicate writers, and the `Updates(...)` declarations that validate ordered - updates. -- Adds the first reusable object-template path with `CompositeModelTemplate` and - `ObjectInstance`. Templates bundle reusable `ModelSpec`s and default - `kind`/`species` labels; instances mount them inside a named object subtree. -- `CompositeModel(...)` accepts mounted instances whose roots are either owned objects - or references to separately supplied model objects. -- Template applications are scoped to their instance and receive stable - instance-prefixed application ids. Unmodified instances share the template's - model objects, while instance overrides can replace one application by name - or process when the replacement implements the same process. -- Adds `Override(...)` and `ObjectInstance(...; object_overrides=...)` for - exceptional organs. Overrides are resolved during compilation to concrete - object ids without splitting the logical application or changing its - dependency bindings. -- Template models, template parameter metadata, and replacement models are - retained by reference. The runtime does not copy models or mutate fields to - apply parameter overrides. -- Override validation requires the same process and declared status/environment - variable names. Application explanations report model storage, dispatch - mode, overridden object ids, and replacement model types. -- Adds `Diagnostics.explain_instances(model)` and instance membership in - `Diagnostics.explain_objects(model)`. Instance rows expose roots, current object - membership, mounted applications, overrides, template labels, and - reference-based parameter ownership. -- Objects created below a mounted instance inherit missing template `kind` and - `species` labels. Membership explanations use the current topology rather - than a copied instance object list. -- CompositeModel hard calls now support trial microclimate through - `run_call!(context, name; environment=local_state)`, so hard-called - descendants resample the temporary environment through their normal - environment bindings. -- CompositeModel hard calls now default to `publish=false`. Trial calls mutate target - status without publishing temporal samples or environment writes; accepted - states must use `run_call!(target; publish=true)`. Iterative-call tests verify - that several trials followed by one accepted call publish exactly once. -- `Diagnostics.explain_calls(compiled)` now exposes the manual-call publication contract - through `publication_policy`, `default_publish`, and `accepted_publish` - fields. -- `ModelSpec` now keeps provenance for `ModelSpec(...; inputs=...)` and `ModelSpec(...; calls=...)`. - Declarations coming from `dep(model)` are `:model_default`, scenario-level - declarations and overrides are `:model_spec`, and structured explanations - expose these origins for release-note and migration diagnostics. -- Compiled `OptionalOne(...)` inputs and calls now accept zero matches. - Optional inputs keep their declared model default, optional calls return an - empty target collection, and both remain visible in structured explanations. -- Model kernels read their own parameters from the `model` argument. Hard-call - models and targets are available through focused context APIs such as - `call_targets`, `run_call!`, and `runtime_model`. -- CompositeModel duplicate-writer validation now ignores manual-call-only applications - when validating canonical root writers, so hard-dependency children are not - treated as independent root writers for variables they update inside a parent - call stack. -- Adds `build_maespa_scene(...)` and `run_maespa_example(...)`. - This unified composite-model/object MAESPA path uses `CompositeModelTemplate`, - `ObjectInstance`, `on`, `inputs`, `calls`, and - `every=Dates.Period` with two plant species, one shared soil object, - model LAI, and model energy balance. -- `test/test-maespa-model-example.jl` verifies the unified composite-model/object - MAESPA path. -- `run!(model)` now returns a `Simulation` wrapper containing the mutated - model, compiled object bindings, compiled environment bindings, and - model-local temporal output streams. -- Adds model output inspection helpers: - `outputs(sim::Simulation)`, `collect_outputs(sim)`, and - `Diagnostics.explain_outputs(sim)`. These expose object ids, variables, publishing - application ids, sample counts, time bounds, and value types. -- `run!(model; tracked_outputs=...)` now accepts `OutputRequest` for - composite-model/object runs. Requested outputs are collected from retained typed model - streams after the run, can be read with `collect_outputs(sim)` or - `collect_outputs(sim, :request_name)`, support the standard temporal - policies and `Dates.Period` export clocks, and respect dynamic object - lifetimes by exporting each object only across its own sample interval. This - now prunes retained streams at publisher level: `tracked_outputs=nothing` - keeps all streams, explicit requests keep requested application/variable - streams plus streams required by temporal `ModelSpec(...; inputs=...)`, and - `tracked_outputs=OutputRequest[]` keeps no streams unless temporal - dependencies require them. Dependency-only streams now have bounded - policy-specific histories: latest-only for `HoldLast`, the required window - for `Integrate`/`Aggregate`, and sufficient recent source samples for - `Interpolate`/`PreviousTimeStep`. Requested and default retain-all streams - still preserve complete histories, and export remains post-run rather than - fully online. -- Adds `Diagnostics.explain_output_retention(sim)` for structured diagnostics of retained - model output streams, their reasons, and the compiled retention horizon for - dependency-only streams. -- CompositeModel temporal streams are now keyed by application id, object id, and - variable, so two applications can publish the same variable on the same - object without overwriting each other's stream samples. -- CompositeModel output-export tests now cover requested-output `DataFrame` - materialization, canonical publisher inference without `process=...`, - rejection when only stream-only publishers exist, and ambiguity when an - explicit process matches both a stream-only and a canonical publisher. -- `OutputRequest(...)` now accepts `application=...` for composite-model/object runs. - This disambiguates repeated applications of the same process and permits - explicit export of a named `:stream_only` publisher. -- CompositeModel temporal streams now retain a concrete value type per - application/object/output stream. Type changes fail explicitly, while - generic values such as `BigFloat` remain typed through publication, - interpolation, and integration. -- CompositeModel temporal `ModelSpec(...; inputs=...)` now implement the complete `Interpolate(...)` - policy used by the existing multirate runtime: linear interpolation when - samples bracket the requested time, online linear extrapolation from the - last two samples, and configurable hold behavior. Interpolation modes are - validated during model compilation, and arithmetic preserves generic value - types such as `BigFloat` instead of coercing model values to `Float64`. -- CompositeModel `ModelSpec(...; inputs=...)` accepts - `PreviousTimeStep(:input) => One(...)` or `Many(...)` for explicit lagged - dependencies. These bindings read the previous model timestep, use the - consumer status initialization before history exists, and are excluded from - same-timestep dependency edges so feedback loops can be compiled. -- CompositeModel `output_routing=(var=:stream_only,)` is honored by canonical writer - validation and same-object input inference. Stream-only outputs are excluded - from canonical ownership, but remain available in output streams and explicit - `inputs=(... One(application=:name), ...)` bindings. -- CompositeModel execution now refreshes dirty structural bindings between timesteps. - Objects created, removed, or reparented by a model update application target - sets, input carriers, call targets, writer validation, and scheduling before - the next timestep. -- Geometry-only changes refresh environment bindings at the next timestep - without rebuilding structural bindings. `Simulation` returns the final - compiled structural and environment state, including changes made during the - last timestep. -- Geometry-only environment invalidation is now object-scoped. Moving or - explicitly marking one organ dirty preserves unaffected compiled environment - bindings and rebinds only model applications targeting that object; - structural model changes still trigger a full rebuild. -- Added runtime lifecycle coverage for organ creation, pruning, plant-local - `RefVector` refresh, historical output retention for removed objects, and - movement between mock microclimate cells. -- CompositeModel root execution now uses compiled homogeneous target batches. Models, - statuses, input bindings, and environment bindings are - prebound, so dynamic dispatch happens once per batch instead of once per - object. Heterogeneous object overrides split into ordered concrete batches. -- Adds `Diagnostics.explain_execution_plan(scene_or_simulation)` and a zero-allocation - warmed 128-leaf inner-loop regression gate. -- Manual `ModelSpec(...; calls=...)` handles now use the public - vector-like `run_call!(context, name)` execute-all API, with - `call_targets(context, name)` followed by `run_call!(target)` for fine-grained control. -- Removed the unreleased intermediate authoring and runtime subsystem after - composite-model/object feature parity was established. -- Adds `objects_from_mtg(root; ...)` and `CompositeModel(mtg; ...)` so existing MTG - topology can be adapted once into the unified registry while preserving - node-derived identity, parent relations, labels, geometry, and existing - status objects. -- CompositeModel applications now sample global tabular meteorology at their compiled - `Dates.Period` clock. PlantMeteo reducers and windows from `environment_hint` are - honored; `Environment(; sources=...)` overrides the source while preserving - the reducer. Prepared samplers are shared, and one sampled row is cached per - application/timestep for all selected objects. - -## Downstream and Performance Validation - -The first complete remote XPalm performance artifact passed on 31 July 2026 in -[GitHub Actions run 30617676544](https://github.com/VirtualPlantLab/PlantSimEngine.jl/actions/runs/30617676544). -The Ubuntu 24.04 / Julia 1.12.1 single-threaded job resolved the four -path-developed repositories, then passed all four correctness assertions in -the complete 4,160-step profile. The correctness matrix took 12 minutes -10 seconds; the full job, including resolution and precompilation, took -16 minutes 55 seconds. - -The retained artifact is -`xpalm-full-performance-30617676544-1` (artifact id `8788421206`, 90-day -retention). It contains the resolved `Manifest.toml` and 363 CSV measurement -rows covering all 16 stages. Every output-retention mode reached the same -committed final state: step 4,160, 344 phytomers, LAI -`5.0587602356164405`, and FTSW `0.7991179101191218`. - -The CSV records these exact source revisions: - -- PlantSimEngine: `a715e2bf4407870f7dcae5fedaca7eab00f2a826` -- XPalm: `460d3b5161732a195517d5be9a4bdbb4cfc41846` -- PlantBiophysics: `b733e05032cde9b60e527cc2b33a472281c995fb` -- PlantGeom: `f53e5633da1a56d546c4a4433e6d1cd3a898ecf9` - -On that runner, the minimum complete-cycle measurements were 20.255 seconds -with no retained outputs, 22.492 seconds with the small request, 23.246 seconds -with the reference request, 61.324 seconds with all outputs, and 15.650 seconds -for the historical end-to-end helper. These runner-specific measurements are a -persisted comparison baseline, not a replacement for the faster local -acceptance-machine targets. - -## Compatibility Boundary - -The composite-model/object runtime and its MAESPA acceptance path are implemented. -Historical mapping APIs and the unreleased intermediate prototype were -removed. The design, implementation history, and completion evidence are -documented in: - -- `composite_model_design.md` -- `composite_model_implementation_plan.md` -- `composite_model_completion_audit.md` - -The completed public migration is: - -- replace historical tutorials with native composite-model/object tutorials where - long-term coverage is still valuable; -- model mappings should be described as model applications: - `ModelSpec(model; name=..., on=..., inputs=(...), calls=(...))`; -- `MultiScaleModel(...)` -> `ModelSpec(...; inputs=...)`. -- `dep(model)` remains the model-level trait for default dependency intent: - defaults can become `Input(...)` value bindings or `Call(...)` manual model - calls, and scenario-level `ModelSpec` configuration overrides them. -- model target scales -> `ModelSpec(...; on=...)` object selectors. -- `InputBindings(...)` -> source, policy, and window information on - `ModelSpec(...; inputs=...)`. -- `MeteoBindings(...)` and `MeteoWindow(...)` -> automatic environment - binding plus `Environment(...)` provider/source overrides. -- `ModelSpec(...; output_routing=...)` -> model-application output policy. -- `ScopeModel(...)` -> `ModelSpec(...; on=...)` plus selector scopes. -- `PreviousTimeStep(...)` remains supported as a temporal/cycle-breaking - marker in the unified object-address graph. -- explicit per-model environment wiring -> automatic environment resolver plus - cached environment bindings. - -Historical mapping examples, tests, and runtime files were removed after the -composite-model/object acceptance path reached feature parity. Migration information is -kept in this release-note handoff and the user-facing migration guide. - -## Migration Documentation Added - -- Added `docs/src/migration_composite_model.md` as the user-facing migration guide - from historical mappings to the composite-model/object API. -- Updated documentation navigation, home-page guidance, multiscale warnings, - and the canonical repository agent skill to direct new - scenarios toward `CompositeModel`, `Object`, `on`, `inputs`, `calls`, - `Updates`, `every`, and `Environment`. -- Replaced the documentation home-page quickstart with executable - composite-model/object examples. The page now introduces `CompositeModel`, `Object`, - `ModelSpec`, `on`, `inputs`, `every`, inferred same-object - bindings, multi-object `Many(...)` inputs, and manual `ModelSpec(...; calls=...)` syntax - before linking to the migration guide. -- Replaced the repository README examples with composite-model/object-first examples. - The README now introduces `CompositeModel`, `Object`, model applications, - multi-object `ModelSpec(...; inputs=...)`, and `ModelSpec(...; calls=...)`. -- Added a native composite-model/object quickstart page to the main documentation - navigation. It provides docs-tested examples for one-object model chaining, - inferred bindings, requested output retention, multi-object `ModelSpec(...; inputs=...)`, - reference carrier explanations, and manual `ModelSpec(...; calls=...)` syntax. -- Rewrote the model execution page as the current composite-model/object execution - guide. It now covers compilation, reference carriers, temporal `ModelSpec(...; inputs=...)`, - manual `ModelSpec(...; calls=...)`, `Updates(...)`, `ModelSpec(...; every=...)`, environment binding, - retained outputs, lifecycle invalidation, and migration translations for - historical mapping constructs. -- Rewrote the detailed first simulation tutorial to use the composite-model/object API. - It now introduces `CompositeModel`, `Object`, `ModelSpec`, `on`, `every`, - compiled applications, inferred same-object bindings, model outputs, and a - migration note for historical examples. -- Rewrote the quick examples page to use native composite-model/object snippets for - Beer light interception, degree-days/LAI/light coupling, biomass growth, and - retained `OutputRequest` exports. Historical mapping usage is confined to - migration records. -- Rewrote the standard model coupling, model switching, and coupling more - complex models tutorials around the composite-model/object API. These pages now show - inferred same-object value bindings, switching one `ModelSpec` application, - execution-plan explanations, and `ModelSpec(...; calls=...)` manual-call wiring. -- Removed legacy mapping transforms and their runtime implementations: - `MultiScaleModel`, `SameScale`, `TimeStepModel`, `InputBindings`, - `MeteoBindings`, `MeteoWindow`, and `ScopeModel`. -- Added a curated unified composite-model/object map to the public API page. diff --git a/docs/src/developers.md b/docs/src/developers.md index 519ac736b..b63e7a9dd 100644 --- a/docs/src/developers.md +++ b/docs/src/developers.md @@ -42,15 +42,42 @@ work and requires dedicated correctness tests before it becomes public. ### Documentation -Build the documentation from the repository root with: +The website uses Documenter and Bonito's static documentation writer. The docs +environment requires Julia 1.11 or newer; this does not change the Julia versions +supported by PlantSimEngine itself. + +Start Julia from `docs/` with that directory as the active project (agents use +Kaimon), then install +the docs dependencies and build without deploying: + +```julia +using Pkg +Pkg.instantiate() +ENV["PLANTSIMENGINE_DOCS_BUILD_ONLY"] = "true" +include("make.jl") +``` + +The docs environment resolves PlantSimEngine from the parent checkout and includes +the packages needed for the runnable examples and API reference. Build output is +written to `docs/build/`. The build also checks that exported pages, assets, and +Bonito session data resolve locally. `docs/check_static_export.jl` adjusts Bonito +5.2's site-relative links for this manual's nested pages and for version links in +pull-request previews; its assertions flag upstream changes that need review. +`docs/bonito_rendering.jl` preserves code blocks and tables returned by `@eval`; +it defers to Bonito if a later version supplies the missing document-root renderer. + +Serve the build directory over HTTP to inspect the theme, +search, and static examples: ```julia -julia --project=docs docs/make.jl +using LiveServer +LiveServer.serve(dir="build", launch_browser=true) ``` -The docs environment includes the extra packages needed for examples and API -documentation, such as `Documenter`, `CairoMakie`, `PlantMeteo`, and -`MultiScaleTreeGraph`. +The existing documentation job builds and deploys the static files through +Documenter, including pull-request previews. The website needs no running Julia +server. Browser interactions can inspect exported data; rerunning a Julia model +requires an execution backend. ### Benchmarks @@ -65,12 +92,11 @@ simulation = run!(model; steps=48, outputs=:none, performance=true) Diagnostics.explain_runtime_performance(simulation) ``` -The returned rows distinguish immutable-plan compilation, object-target -instantiation, lifecycle-buffer updates, steady-state execution, output -collection, and whole-initialization totals. Use these counters to establish -where work occurred, not as a microbenchmark. Timing instrumentation calls -`time_ns()` at runtime boundaries, so benchmark ordinary execution separately -with `performance=false` after warming the simulation. +The report separates time spent preparing the simulation, selecting objects, +updating after structural changes, running the models, and collecting outputs. +Use it to find which stage takes time. Measuring those stages also adds some +work, so measure normal execution separately with `performance=false` after +a first run has allowed Julia to compile the code. ## CI workflows @@ -86,6 +112,11 @@ If a change affects public APIs or execution behavior, check both `CI` and `Integration` before merging. Benchmark results are useful for regressions, but should be interpreted alongside the test results. +Downstream tests run the test suites of packages that use PlantSimEngine, such +as PlantBiophysics, against the proposed changes. If you maintain a package that +depends on PlantSimEngine, you can propose adding it to the integration workflow +through a pull request. + ## Graph Viewer Frontend The static viewer and HTTP editor share the React application under @@ -140,6 +171,20 @@ change. ## Documentation impact +The manual has two practical paths: **Couple models** for simulation users and +**Write models** for model authors. Add an example to the appropriate path and +link to deeper reference material only when the reader needs it. Prefer one +tested example that develops gradually over several parallel quickstarts. + +Describe current behavior in the user guides and API reference. Completed work +plans and handoff notes do not belong in the manual; keep lasting explanations +with the feature they describe. + +Documentation fixes are welcome through +[GitHub issues](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues) or a +pull request. A short report of a confusing example is useful even without a +proposed fix. + Changes in PlantSimEngine often require documentation updates beyond the page you were editing. @@ -164,7 +209,6 @@ were editing. ### Coverage gaps to keep in mind -Not every combination of weather structure, status shape, mapping layout, and -downstream usage is covered directly in PlantSimEngine. When changing the public -API or runtime semantics, treat downstream integration results as part of the -validation surface, not as optional extra signal. +PlantSimEngine's own tests cannot cover every weather format, object +configuration, and use in other packages. When changing public functions or +how simulations run, also run the tests of packages that depend on them. diff --git a/docs/src/documentation_improvement.md b/docs/src/documentation_improvement.md deleted file mode 100644 index 713c838f7..000000000 --- a/docs/src/documentation_improvement.md +++ /dev/null @@ -1,11 +0,0 @@ -# Help Improve The Documentation - -Good documentation is essential if PlantSimEngine is meant to stay usable for -both new users and contributors. - -If a page is unclear, incomplete, or out of date, the preferred way to report it -is to open an issue or submit a pull request on -[GitHub](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues). - -Documentation fixes do not need to be large. Small corrections, clarified -examples, and reports of missing release notes are all useful contributions. diff --git a/docs/src/guides/coupling.md b/docs/src/guides/coupling.md index 8e31fafc2..869b89953 100644 --- a/docs/src/guides/coupling.md +++ b/docs/src/guides/coupling.md @@ -1,78 +1,107 @@ # Coupling models -PlantSimEngine has three coupling mechanisms with different ownership: +Coupling means letting models work together. For example, a light model can +calculate the radiation that a growth model needs. The growth model then reads +that result as an input. -| Mechanism | Use it when | Who owns the operation? | +Choose how to connect your models from the calculation you need: + +| Connection | Example | How to set it up | |---|---|---| -| Value coupling | A consumer reads a producer's accepted value | The scenario declares `inputs`; the compiler transports references or streams | -| Hard call | A parent must choose when or how often a child executes | The parent declares `Call` and invokes `run_call!` | -| Adapter model | Unit, basis, temporal meaning, or aggregation changes | An ordinary model owns and tests the explicit conversion | - -Use `inputs` when a model reads a value produced by another application. A -unique same-object producer is inferred; cross-object sources should use an -explicit `One`, `OptionalOne`, or `Many` selector. Inspect the resolved -references with `Diagnostics.explain_bindings`. - -Use `calls` only when a parent algorithm owns child execution or iteration. -Use `run_call!(context, :name)` to execute every resolved target. Pass -`sampled_environment=value` to this bulk path when the caller already has one -model-facing environment for all targets. Use `call_model(context, :name)` to -inspect a singular dependency model without materializing a public target. For -selection, target status access, custom ordering, or distinct environments, -retrieve the vector-like collection with `call_targets(context, :name)` and -execute individual targets. Trial calls use `publish=false`; accepted state is -published once. -Nested calls inherit publication suppression, so a descendant cannot publish -inside an unpublished ancestor trial. `Diagnostics.explain_calls` and `Diagnostics.explain_schedule` -show call-only targets and ordering. - -`Diagnostics.explain_initialization(model)` classifies values as supplied, generated, -producer-bound, defaulted, required, or environment-bound before execution. +| Value coupling | Growth reads the radiation calculated by a light model | Connect the output to the input with `inputs` | +| Manual call, also called a hard dependency | An energy-balance model runs photosynthesis at several trial leaf temperatures | Declare `Call`, then use `run_call!` inside the energy-balance calculation | +| Adapter model | Radiation per square metre must become radiation per plant | Write a small model that performs the conversion | + +A **model application** is a model configured with `ModelSpec`: it has a name, +a choice of objects, and any settings needed for its inputs or timing. ## Value coupling -A consumer on the same object needs no scenario syntax when exactly one -canonical producer exists. Make cross-object intent explicit: +Suppose a growth model needs `absorbed_par`. If exactly one model on the same +object writes that variable, PlantSimEngine connects them automatically and +runs the light calculation first. When the value comes from another object, +describe where to find it in `ModelSpec(...; inputs=...)`. + +Use these selectors to choose how many objects supply a value: + +| Selector | Meaning | +|---|---| +| `One(...)` | Exactly one match is required; zero or several matches are errors | +| `OptionalOne(...)` | A match may be absent; use this only if your model can meaningfully handle that absence | +| `Many(...)` | Read several values, for example to add the respiration of all leaves | + +The `within` setting limits where PlantSimEngine looks. `Self()` means the +current object. `Subtree()` means that object and its descendants, such as a +plant and its organs. `SelfPlant()` means the plant instance to which the +current object belongs. `SceneScope()` searches the whole simulation. + +[Implement Cross-Object Values](@ref) gives a complete example: a plant model +reads respiration from its own leaves with `Many(...; within=Subtree())`. +The model then adds those values. Choosing `Many` does not perform the sum +for you. + +Normally, PlantSimEngine identifies which model writes an input and runs it +before the model that reads it. Sometimes you want to read a value already +stored in an object's `Status`, such as an initial soil-water reserve. Use +`from_status=true` for this case. + +That setting reads the current stored value directly. It does not look for a +model that should calculate it first. If you need to wait for a particular +calculation, name it with `after`, for example +`Many(...; var=:reserve, from_status=true, after=:plant_allocation)`. +Otherwise, the applications keep their order in the scenario. You cannot +combine `from_status=true` with `process`, `application`, `policy`, or `window`. -[Implement Cross-Object Values](@ref) is the executable example: a plant -consumer receives a `Many(...; within=Subtree())` collection from its own -leaves while PlantSimEngine preserves each source object's identity. +Use `Diagnostics.explain_bindings(model)` to see where each input comes from. +`Diagnostics.explain_initialization(model)` shows how starting values are +obtained, including values you supplied, defaults, and missing required inputs. -`One` is a contract: zero or multiple matches are errors. Use `OptionalOne` -only when absence has a scientific meaning, and `Many` when aggregation is -part of the consumer model. `within=Subtree()` searches descendants of the -current target; `within=Self()` selects only the current target; -`within=SelfPlant()` anchors repeated plant instances; and `SceneScope()` -is deliberately global. +## Manual calls -By default, an input selector also identifies applications that produce the -selected variable, and those producers are scheduled before the consumer. Use -`from_status=true` only when the input deliberately reads the objects' current -`Status` references independently of any producer. Declare that selector as -`Many(...; var=:reserve, from_status=true, after=:plant_allocation)`. +A model that controls another model's calculation is called a **controller**. +For example, an energy-balance controller can try different temperatures, +run photosynthesis at each temperature, and keep the result that satisfies +its energy-balance equation. -This is a same-step live-reference binding. It cannot be combined with -`process`, `application`, `policy`, or `window`. It does not infer a producer -edge; use `after=:application_id` when the state must be read or mutated after -a particular application. Otherwise, the scenario's application order is -preserved. +Declare the models to call with `Call` in the controller's `dep` method, or +with `ModelSpec(...; calls=...)` in the scenario. Then use: -## Manual calls +| What the controller needs to do | Function | +|---|---| +| Run all models selected by a named call | `run_call!(context, :leaf_energy)` | +| Choose individual models or objects to run | `call_targets(context, :leaf_energy)`, then `run_call!(target)` | +| Read a called model's type or parameters | `call_model(context, :leaf_energy)`; this requires exactly one match | -[Implement A Hard Dependency](@ref) is the executable parent/child example. -Inside a controller, iterate over `call_targets(context, :leaf_energy)`. Run -candidate states with `run_call!(target; publish=false)` and publish the -accepted state once with `publish=true`. A call-only target is excluded from -root scheduling, and an unpublished outer call suppresses publication by every -nested descendant. +Here a **target** is one selected model application on one object. If the +controller has already prepared the environmental values for every target, +pass them as `sampled_environment=value` to `run_call!`. Use individual +targets when each object needs different values. + +Trial calls use `publish=false`, the default. Their results are not saved as +accepted output samples for time-based connections or output history. Use +`publish=true` for the accepted calculation. This setting does not undo +changes to model state: the controller must handle any changes that should +be discarded after a trial. + +A model used only through calls runs when its controller calls it; it does +not also run independently. If a trial calls further models, those nested +calls cannot save accepted samples either. The same rule prevents a nested +controller from committing trial values to the environment. + +[Implement A Hard Dependency](@ref) walks through a complete example. +`Diagnostics.explain_calls(model)` lists the selected models and objects; +`Diagnostics.explain_schedule(model)` shows their execution order. ## Explicit adapters -Variable renaming only changes the local field name. It must never silently -convert molar to mass units, ground-area to plant-area basis, rates to totals, -or one carbon convention to another. Put that operation in a small, named -model with a contract on each side. The executable adapter shipped with the -agent skill converts radiation per unit ground area to radiation per plant: +Two variables can have the same name and still mean different things. For +example, radiation per square metre of ground cannot be used directly where +a model expects radiation per plant. Renaming the variable does not convert it. + +An **adapter** is a small model that performs such a conversion. Its +`VariableContract` declarations record the units and physical meaning before +and after the conversion. This example multiplies radiation per unit ground +area by the ground area assigned to a plant: ```@example coupling-adapter using PlantSimEngine @@ -105,21 +134,17 @@ simulation = run!(adapted) ) ``` -The producer-to-adapter binding matches `GROUND_PAR_CONTRACT`; the -adapter-to-consumer binding matches `PLANT_PAR_CONTRACT`. The conversion -parameter, equation, units, and bases are now visible and testable. Document -the scientific domain and validity limits explicitly; the fixture does not -invent them. Use the same pattern for temporal or carbon-basis conversions. - -Temporal policies currently leave contracts unchanged. In particular, -`Integrate(reducer)` with a duration-aware reducer computes an integral but -does not make a rate contract -compatible with a total contract. For a contracted rate-to-amount conversion, -perform the calculation in the adapter kernel and declare the different -contracts on its input and output. Accumulate varying rates at their producer -cadence or supply a correctly averaged rate before multiplying by duration. - -After compilation, inspect `Diagnostics.explain_bindings(compiled)` for source identity -and carrier type, `Diagnostics.explain_calls(compiled)` for call-only targets, and -`Diagnostics.explain_schedule(compiled)` for root execution order. These rows are the -supported diagnostic surface; compiled fields are internal. +The adapter reads radiation per ground area and writes radiation per plant. +The models on either side therefore receive the units they expect. You can +inspect and test the area parameter and the conversion equation separately. +For your own adapter, also explain when that conversion is scientifically +appropriate. + +Use the same approach to convert a rate to an amount. A constant rate can be +multiplied by its duration. If it varies, add its contributions at each update +or use the correct mean rate over the interval. + +Time settings such as `Integrate(reducer)` can calculate an integral, but +they do not change the variable's declared units or meaning. To connect a +declared rate to a model expecting an amount, perform that calculation in an +adapter and declare the rate as its input and the amount as its output. diff --git a/docs/src/guides/data/environment_inputs.md b/docs/src/guides/data/environment_inputs.md deleted file mode 100644 index abd2c9907..000000000 --- a/docs/src/guides/data/environment_inputs.md +++ /dev/null @@ -1,10 +0,0 @@ -# Weather And Environment Inputs - -An environment may be a constant named tuple, one tabular row, or regular -multi-row weather. Every row in a timed sequence needs a positive fixed -`duration`; inconsistent base durations and application substeps are rejected. - -Use `Environment(sources=...)` to map model-facing environment names to -provider columns. Values retain compatible user numeric types. Spatial -providers implement the same model-facing contract and refresh bindings after -object movement or geometry changes. diff --git a/docs/src/guides/data/forcing_observations.md b/docs/src/guides/data/forcing_observations.md index 0b1448d5b..630df2949 100644 --- a/docs/src/guides/data/forcing_observations.md +++ b/docs/src/guides/data/forcing_observations.md @@ -1,10 +1,85 @@ -# Forcing Observed Variables +# Use Observed Values In A Simulation -Supply a constant observed value in object status when it does not vary. For a -time-varying observation, use a small environment-driven source model that -publishes the canonical variable; downstream applications remain unchanged. +You can supply measured leaf area index (LAI) while calculating light +interception. This is useful for testing the light model independently of a +model that predicts LAI. Here LAI is m² leaf per m² ground, and incident PAR +is an energy flux in W m⁻² ground. -Replace a process for an entire template instance through instance overrides, -or use `Override` for one exceptional object. The replacement must implement -the same process and input/output contract. +## One fixed observation +Supply a constant LAI in `status`, where the canopy stores its values, and +use only the light model: + +```@example observed_lai +using PlantSimEngine, Dates, DataFrames +using PlantSimEngine.Examples + +fixed_model = CompositeModel( + Beer(0.6); + status=(LAI=2.0,), id=:canopy, scale=:Canopy, + environment=(Ri_PAR_f=100.0, duration=Day(1)), +) +fixed_simulation = run!(fixed_model; outputs=:all) +final_state(fixed_simulation).aPPFD +``` + +If you add a model that calculates LAI, it will replace this supplied value +when it runs. To keep the observed LAI fixed, use it without an LAI model. + +## A sequence of observations + +For observations that change over time, use a model that reads each +observation and supplies it as LAI. The small `ObservedLAI` model below only copies the value; +it performs no fitting, interpolation, or unit conversion. Include it from the +downloadable source to run the example: + +```@example observed_lai +include("observed_lai.jl") + +observations = DataFrame( + duration=fill(Day(1), 3), + measured_LAI=[1.0, 2.0, 3.0], + Ri_PAR_f=fill(100.0, 3), +) +model = CompositeModel( + ObservedLAI(), Beer(0.6); + id=:canopy, scale=:Canopy, environment=observations, +) +simulation = run!(model; steps=nrow(observations), outputs=:all) +rows = collect_outputs(simulation; sink=DataFrame) +filter(row -> row.variable == :LAI || row.variable == :aPPFD, rows) +``` + +```@example observed_lai +@assert final_state(simulation).LAI == 3.0 # hide +@assert count(==(:LAI), rows.variable) == 3 # hide +nothing # hide +``` + +PlantSimEngine passes LAI from `ObservedLAI` to `Beer` automatically: one model +supplies it and the other needs it on the same canopy. +To predict LAI instead, replace `ObservedLAI()` with `ToyLAIModel()` and supply +the thermal time that model requires. A change of model can change the inputs +you must provide; [compare alternatives](../../step_by_step/model_switching.md) +before making a replacement. + +## The observation model + +The complete [source file](observed_lai.jl) is short: + +```@eval +Main.DocsSources.section("docs/src/guides/data/observed_lai.jl", "struct ObservedLAI") +``` + +Before using real measurements, check their units, whether they refer to +leaf or ground area, their time stamps, and any missing values. This example +has one observation per day. If your measurements are less frequent, decide +how to fill the gaps: for example, interpolate between measurements or keep +the last measured value until the next one. Document that choice before +using the data. This approach supplies a measured input directly. It does +not perform data assimilation, which would use observations to estimate or +correct the model state and could account for measurement uncertainty. + +See [Collect and plot results](outputs_plotting.md) for displaying predictions +alongside observations and [Parameter fitting](../../working_with_data/fitting.md) +when the objective is to estimate model parameters. diff --git a/docs/src/guides/data/numerical_reliability.md b/docs/src/guides/data/numerical_reliability.md index 3874feb49..bfe9af580 100644 --- a/docs/src/guides/data/numerical_reliability.md +++ b/docs/src/guides/data/numerical_reliability.md @@ -1,19 +1,24 @@ # Numerical Reliability -Use exact assertions for deliberately exact integer/rational scenarios and -`isapprox` for floating-point scientific results. Splitting a computation -across objects may change reduction order without changing the model. - -PlantSimEngine preserves compatible numeric types through parameters, status, -carriers, meteorology, and streams. Avoid forced `Float64` conversion. For long -or ill-conditioned sums, use pairwise or compensated accumulation inside the -scientific model and test its error tolerance explicitly. - -## Choose the status representation - -A scenario may give its status values a different numeric representation when -it constructs a [`CompositeModel`](@ref). A type mapping is the shortest way to -convert every matching status value: +A small difference in a computed result can come from rounding. For example, +adding the same floating-point values in a different order can change the +last few digits. This can happen when you split a calculation across objects. +Use `isapprox` with a chosen tolerance to compare such results. Use exact +equality when the calculation is meant to be exact, such as an integer count. + +PlantSimEngine lets models use different numeric types for parameters, stored +values, weather data, and results. Avoid converting values to `Float64` unless +your calculation requires that precision. For sums that are sensitive to +rounding, consider pairwise summation (adding smaller groups first) or +compensated summation (tracking rounding losses). Implement the chosen method +in the scientific model and test its error against an appropriate tolerance. + +## Choose numeric types for stored values + +You can choose the numeric types used to store object values when you create +a [`CompositeModel`](@ref). For example, `Float32` uses less memory than +`Float64`, with less precision. A `type_promotion` rule converts all matching +status values: ```@example status_numeric_types using PlantSimEngine @@ -39,18 +44,18 @@ status = only(model_objects(model)).status ) ``` -Here the scalar `Float64` and the elements of the ordinary numeric array become -`Float32`. The integer is unchanged. Array conversion is element by element and -preserves the array shape. PlantSimEngine does not recursively inspect arbitrary -user structs or custom containers; map the complete container type or handle it -explicitly in `status_transform` when that is required. +Here `biomass` and each value in `cohort_masses` become `Float32`. +`cohort_count` remains an integer. Arrays keep their shape. PlantSimEngine +converts the elements of ordinary numeric arrays, but it does not look inside +every user-defined struct or custom container. To convert one of those, add a +rule for the whole container type or use `status_transform`, shown below. -Use `AbstractFloat => Float32` when all floating-point status values should be -converted, including types other than `Float64`. Avoid a broad -`Real => Float32` rule unless integer counts should also become floating-point -values. An exact source-type rule takes priority over an abstract rule. Rules -whose source types overlap without one being more specific are rejected during -model construction, so the result never depends on `Dict` iteration order. +Use `AbstractFloat => Float32` to convert all floating-point status values, +including types other than `Float64`. A broader `Real => Float32` rule also +converts integer counts, so use it only if that is intended. A rule for an +exact type takes priority over a rule for a broader type. If two rules match +and neither is more specific, PlantSimEngine rejects them when you create +the model. Their order in the dictionary does not decide which one wins. Use `status_transform` when the choice also depends on the variable name: @@ -66,43 +71,45 @@ model = CompositeModel( ) ``` -The transform receives `(variable, value)` and returns the value to store. It -runs before the general type mapping, so a value changed to another type by the -transform no longer matches the `Float64` rule above. It must be callable for -every status value that is materialized. If it throws, or if a mapped value -cannot be converted with `convert(Target, value)`, model construction stops -with the variable, original type, object when known, and initialization origin -in the error message. - -This policy applies only to values stored in object statuses: supplied values, -model input and output defaults, and status values of objects registered later -in the simulation. It does not convert model parameters or environment values. -The conversion happens when status storage is materialized or an object is -registered, not inside every model invocation. - -For a supplied `Status`, PlantSimEngine creates a new status reference only for -values that actually change. The supplied `Status` itself is not mutated, and -unchanged references are preserved where possible. Each `Object` must still own -its own `Status`; sharing one `Status` between objects is rejected. The stored -policy is also applied once to values introduced later by `register_object!` or -`add_organ!`. - -`Diagnostics.explain_initialization(model)` reports the declared, original, -transformed, and effective types, together with whether the precise transform -or the type mapping changed each materialized value. +`status_transform` receives the variable name and its value, then returns the +value to store. It runs before `type_promotion`, so a value it changes to +`MyNumericType` no longer matches the `Float64` rule above. The function must +handle every status value it receives, including values it should leave alone. +If the function fails, or a conversion with `convert(Target, value)` fails, +model construction stops. The error identifies the variable, its original +type, where its initial value came from, and the object when known. + +These settings apply to values stored on objects: supplied initial values, +model input and output defaults, and values on objects added later during +the simulation. Model parameters and environment values keep their types. +Conversion happens when status storage is created or a new object is added; +it is not repeated every time a model runs. + +If you supply a `Status`, PlantSimEngine leaves that original object unchanged. +It creates new storage for converted values and reuses existing references +where possible for unchanged values. Each `Object` must have its own `Status`; +sharing one `Status` between objects is rejected. The same conversion rules +apply once to values added later through `register_object!` or `add_organ!`. + +`Diagnostics.explain_initialization(model)` shows the type declared by the +model, the type of the supplied value, the type after `status_transform`, and +the final stored type. It also shows which conversion changed each value. !!! note - Model kernels still need to support the effective types. Keep status - computations generic and avoid constructing intermediate values as - `Float64` unless that precision is part of the scientific contract. + Your model's `run!` function must support the types you choose. Let its + calculations work with the input types, and avoid forcing intermediate + values to `Float64` unless the equations require that precision. ## Propagate uncertainty with particles [MonteCarloMeasurements.jl](https://github.com/baggepinnen/MonteCarloMeasurements.jl) -is an optional package and is not a PlantSimEngine dependency. A precise -`status_transform` can initialize selected inputs and outputs as particles, -while the general mapping converts the remaining floating-point status values. -For example: +is an optional package that you install separately. It represents an uncertain +number as a collection of possible values, called **particles**. Calculations +on those particles show how uncertainty in an input affects an output. + +Use `status_transform` to give selected inputs and outputs this representation. +The `type_promotion` rule can still convert the other floating-point values. +This small example squares two possible values of `x`, 0.9 and 1.1: ```julia using PlantSimEngine @@ -144,14 +151,14 @@ uncertain_result = final_state(simulation).y (mean=pmean(uncertain_result), standard_deviation=pstd(uncertain_result)) ``` -Both `x` and the initial storage for `y` are particles, so assigning the -particle result preserves its uncertainty. The unrelated `ordinary` status is -still converted to `Float32`. Model parameters would need their own generic -types if they also have to carry uncertainty. +Both `x` and the initial value of `y` use `Particles`, so `y` can store the +uncertain result. The separate `ordinary` value becomes `Float32`. If you +also want uncertain model parameters, define the model so its parameter +fields accept those types. ## Test the expected tolerance -Changing the floating-point representation can change rounding and reduction -order. Compare scientific results with an explicit tolerance appropriate for -the chosen representation. Test exact values only when exactness is an intended -part of the model contract. +Changing numeric types can change rounding and the order in which values are +added. Choose a comparison tolerance that makes sense for both the precision +and the scientific calculation. Test exact equality only when the model is +intended to produce an exact result. diff --git a/docs/src/guides/data/observed_lai.jl b/docs/src/guides/data/observed_lai.jl new file mode 100644 index 000000000..6d45678bd --- /dev/null +++ b/docs/src/guides/data/observed_lai.jl @@ -0,0 +1,11 @@ +# A measured-value alternative to ToyLAIModel, used by forcing_observations.md. +struct ObservedLAI <: PlantSimEngine.Examples.AbstractLai_DynamicModel end + +PlantSimEngine.inputs_(::ObservedLAI) = NamedTuple() +PlantSimEngine.outputs_(::ObservedLAI) = (LAI=0.0,) +PlantSimEngine.environment_inputs_(::ObservedLAI) = (measured_LAI=0.0,) + +function PlantSimEngine.run!(::ObservedLAI, status, environment, constants, context) + status.LAI = environment.measured_LAI + return nothing +end diff --git a/docs/src/guides/data/outputs_plotting.md b/docs/src/guides/data/outputs_plotting.md index 55139df24..3bceb1135 100644 --- a/docs/src/guides/data/outputs_plotting.md +++ b/docs/src/guides/data/outputs_plotting.md @@ -1,63 +1,144 @@ # Collecting And Plotting Outputs -Run a model with `outputs=:all` or an explicit `OutputRequest`, then call -`collect_outputs(sim)` for ordinary analysis. Rows identify application, -object, variable, timestep/time, and value, so repeated processes cannot -overwrite one another. Convert the rows to a `DataFrame`, filter by -application/object/variable, group, and plot. Use `final_state(sim)` when only -the latest values are needed. - -Runs default to `outputs=:none`. Use `outputs=:all` only when complete stream -history is intentional; selected requests are the memory-safe choice for large -composite models. Raw rows have the stable columns `timestep`, `time`, `application_id`, -`object_id`, `variable`, and `value`. Requested/resampled rows additionally -identify `scale` and `process`. A temporal request emits `missing` when its -policy cannot produce a value for a scheduled output time. -`time` is expressed in model base-step coordinates; application clock metadata -is reported by `Diagnostics.explain_schedule(simulation)`. Values retain their concrete -types, so unit-bearing model outputs remain unit-bearing in collected rows. - -Each publication snapshots its value, including arrays and nested mutable -values. Updating a model's live status later does not rewrite earlier samples. -`final_state` also returns an independent snapshot; use `model_status` when -you intend to access the live state. - -`OutputRequest` controls requested retention or resampling. Dependency streams -may also be retained for runtime correctness. Use -`Diagnostics.explain_output_retention(sim)` to see why each stream exists. Removed objects -retain accepted historical rows. +Plot absorbed light through a day, then compare two canopies with different +leaf area indices. This page uses the existing `Beer` model, so you can focus +on running a simulation and analysing its results. The radiation values are +illustrative, not observations from an experiment. + +The [tutorial installation](../../prerequisites/installing_plantsimengine.md) +includes DataFrames for tables and CairoMakie for plots. + +## Run and plot one canopy + +Supply thirteen hourly PAR fluxes, from 06:00 to 18:00, in W m⁻² of ground. +The canopy has 2 m² of leaves per m² of ground throughout this example. ```@example collect-output -using Dates -using DataFrames -using PlantSimEngine - -PlantSimEngine.@process "docs_output_counter" verbose = false -struct DocsOutputCounter <: AbstractDocs_Output_CounterModel end -PlantSimEngine.inputs_(::DocsOutputCounter) = NamedTuple() -PlantSimEngine.outputs_(::DocsOutputCounter) = (value=0,) -PlantSimEngine.run!(::DocsOutputCounter, status, environment, constants, context) = - (status.value += 1) - -model = CompositeModel(DocsOutputCounter(); environment=(duration=Hour(1),)) -simulation = run!( - model; - steps=3, +using Dates, DataFrames, CairoMakie, PlantSimEngine +using PlantSimEngine.Examples + +incident_par = [0.0, 50, 150, 300, 500, 650, 700, 650, 500, 300, 150, 50, 0] +weather = [(Ri_PAR_f=par, duration=Hour(1)) for par in incident_par] +model = CompositeModel( + Beer(0.6); + id=:canopy, scale=:Canopy, + status=(LAI=2.0,), environment=weather, +) +simulation = run!(model; steps=length(weather), outputs=:all) +rows = collect_outputs(simulation; sink=DataFrame) +light = rows[rows.variable .== :aPPFD, :] +first(light, 3) +``` + +`sink=DataFrame` asks for a DataFrame; this is already the default if you +leave out `sink`. Each row records one variable for one object at one time, +and identifies which model application produced it. +`aPPFD` is absorbed PAR in μmol m⁻² of ground s⁻¹. The `time` column uses +simulation steps rather than clock hours, with the first record at 1. In +this example each step lasts one hour and the first record is at 06:00, so +`6 + (time - 1)` gives the hour of day. Use your weather data's actual dates +and durations when they follow a different timetable. + +```@example collect-output +light.hour_of_day = 6 .+ (light.time .- 1) +figure_one = Figure(size=(740, 380), fontsize=16) +axis_one = Axis(figure_one[1, 1], + xlabel="Hour of day", + ylabel="Absorbed PAR\n(μmol m⁻² ground s⁻¹)", + xticks=6:2:18, +) +scatterlines!(axis_one, light.hour_of_day, light.value; + color=:seagreen, linewidth=2.5, markersize=7) +@assert nrow(light) == length(incident_par) +@assert first(light.value) == last(light.value) == 0.0 +figure_one +``` + +With fixed leaf area, absorption follows the supplied radiation. This curve +shows a mean flux for each hourly record. To calculate the total absorbed +over an interval, multiply each flux by its duration in seconds and add the +amounts. See [different model cadences](../../journeys/users/cadences.md) for +models that run at different intervals. + +## Keep two canopies separate + +Apply the same model to two independent canopies. Only their LAI differs. +An application name such as `:light` identifies this configured use of `Beer`. + +```@example collect-output +two_canopies = CompositeModel( + Object(:open_canopy; scale=:Canopy, status=Status(LAI=1.0)), + Object(:dense_canopy; scale=:Canopy, status=Status(LAI=3.0)); + applications=(ModelSpec(Beer(0.6); name=:light, on=Many(scale=:Canopy)),), + environment=weather, +) +comparison = run!(two_canopies; steps=length(weather), outputs=:all) +comparison_rows = collect_outputs(comparison; sink=DataFrame) +comparison_light = comparison_rows[ + (comparison_rows.application_id .== :light) .& (comparison_rows.variable .== :aPPFD), :] +comparison_light.hour_of_day = 6 .+ (comparison_light.time .- 1) + +figure_two = Figure(size=(740, 380), fontsize=16) +axis_two = Axis(figure_two[1, 1], + xlabel="Hour of day", + ylabel="Absorbed PAR\n(μmol m⁻² ground s⁻¹)", + xticks=6:2:18, +) +for series in groupby(comparison_light, [:application_id, :object_id]) + sort!(series, :time) + scatterlines!(axis_two, series.hour_of_day, series.value; + label=string(first(series.object_id)), linewidth=2.5, markersize=6) +end +axislegend(axis_two; position=:lt, framevisible=false) +@assert nrow(comparison_light) == 2 * length(incident_par) +figure_two +``` + +The denser canopy absorbs more PAR per unit ground area under the same +incoming light. Grouping by application and object keeps the two curves +separate. Filtering only by variable and drawing one line would incorrectly +join different objects. + +## Retain only the outputs you need + +`outputs=:all` is convenient for these small examples. Larger simulations +can save selected variables with `OutputRequest`. Here, the new run keeps +only the light result requested from the two canopies: + +```@example collect-output +selected_simulation = run!( + two_canopies; + steps=length(weather), outputs=OutputRequest( - One(scale=:Scene), - :value; - name=:counter, - application=:docs_output_counter, + Many(scale=:Canopy), :aPPFD; + name=:absorbed_light, application=:light, ), ) -rows = collect_outputs(simulation, :counter; sink=nothing) -table = DataFrame(rows) -@assert table.value == [1, 2, 3] -table +selected = collect_outputs(selected_simulation, :absorbed_light; sink=DataFrame) +@assert nrow(selected) == 2 * length(incident_par) +first(selected, 4) ``` -For plotting, filter the table first and map `time` to the horizontal axis and -`value` to the vertical axis. Group by `application_id` and `object_id` before -drawing lines; grouping by variable alone can accidentally connect different -objects. CairoMakie and other plotting packages consume the resulting columns -without any PlantSimEngine-specific adapter. +A new `run!` starts a fresh timeline. Use `step!` or `continue!` when you want +to extend an existing simulation instead. Runs default to `outputs=:none`; +`final_state(simulation)` remains available when you only need the latest +values. + +PlantSimEngine may also keep past values because another model needs them, +even if you did not request those values for analysis. When memory use +matters, `Diagnostics.explain_output_retention(simulation)` explains why +each time series is being stored. + +## Reading the result tables + +The basic result table has the columns `timestep`, `time`, `application_id`, +`object_id`, `variable` and `value`. Tables produced by an `OutputRequest` +also identify `scale` and `process`. Requests that combine values over time +or sample them at new times can return `missing` if there is not enough +saved history. Check when the model ran and when the simulation started +before interpreting a missing result as a gap in the weather observations. + +Saved values, including arrays, record the result at that time. Later changes +do not rewrite earlier rows, and removing an organ does not delete its past +results. Compatible numerical types are preserved, including values with +attached physical units when your model uses them. diff --git a/docs/src/guides/extensions/environment_backends.md b/docs/src/guides/extensions/environment_backends.md index 4c157dc09..8859197a0 100644 --- a/docs/src/guides/extensions/environment_backends.md +++ b/docs/src/guides/extensions/environment_backends.md @@ -1,94 +1,104 @@ # Environment Backend Extensions -This page is for package authors who connect a meteorology, canopy-layer, -voxel, grid, or other spatial provider to PlantSimEngine. Simulation users -normally configure an existing backend with `Environment(...)` and do not need -this protocol. - -## The boundary - -An extension backend subtypes -`PlantSimEngine.EnvironmentAPI.AbstractEnvironmentBackend` and extends -functions in `PlantSimEngine.EnvironmentAPI`. Keep the concrete backend and -handle types in the extension package. They do not belong in PlantSimEngine's -root namespace. +An **environment backend** connects a source of weather or spatial data to +PlantSimEngine. It may provide weather records, canopy layers, a grid, or +voxels (three-dimensional cells). This page explains how to write one. To use +an existing backend in a simulation, start with +[Understand Environments](../../journeys/users/environments.md). + +## Define a backend + +Define your backend as a subtype of +`PlantSimEngine.EnvironmentAPI.AbstractEnvironmentBackend` and extend +functions in `PlantSimEngine.EnvironmentAPI`. Define its types in your +extension package, including the **handle** type. A handle stores the location +or data needed to read the environment for one model on one object. For +example, it might contain the canopy layer used by a leaf. PlantSimEngine +keeps this handle so it does not need to find that layer on every step. The required methods are: - `base_step_seconds(backend)`: duration of one base step; - `get_nsteps(backend)`: available number of steps; -- `bind_environment(backend, object, context, config)`: compile one opaque - handle for an application/object pair; -- `sample(backend, handle, variable, time)`: read committed state. - -Implement `environment_variables(backend)` when the variable names can be -enumerated cheaply. PlantSimEngine then validates model environment inputs -while compiling. - -Mutable or structurally indexed backends add only the capabilities they need: - -- `sample(backend, handle, trial_state, variable, time)` for transient trial - states supplied to `run_call!`; -- `commit_environment!(backend, handle, accepted_state, time)` for accepted - state; -- `update_index!(backend, changed_entities, removed_object_ids)` when topology - or geometry changes require a spatial-index refresh. Initial compilation - supplies all entities; later refreshes supply only the structural delta. +- `bind_environment(backend, object, context, config)`: create the handle for + one model application on one object; +- `sample(backend, handle, variable, time)`: read a value from the stored, + accepted environment state. + +Implement `environment_variables(backend)` if you can list the available +variable names without an expensive calculation. PlantSimEngine can then +check that the required names exist when it prepares the simulation. + +Add these methods if your backend needs to support trials, saved changes, +or changes to the plant structure: + +- `sample(backend, handle, trial_state, variable, time)`: read from a trial + environment supplied to `run_call!`, without changing the stored environment; +- `commit_environment!(backend, handle, accepted_state, time)`: save accepted + environment values; +- `update_index!(backend, changed_entities, removed_object_ids)`: update how + objects are found in space after a structure or geometry change. The first + call supplies all objects; later calls supply only the changes. [`ToySpatialEnvironment`](@ref) is the small, tested implementation used by the user journeys. -## Compile routing into the handle +## Find each object's data once -`bind_environment` receives the target `Object`, an -`EnvironmentAPI.EnvironmentContext`, and the payload configured with -`Environment(...)`. Resolve geometry, layer, voxel, provider, and commit sink -there. Return a concrete handle containing everything later sampling and -committing need. +`bind_environment` receives the `Object` that will use the environment, an +`EnvironmentAPI.EnvironmentContext`, and the settings from `Environment(...)`. +Use them to find where this object reads its values and, if needed, where it +saves changes. For example, find the leaf's voxel or canopy layer here. Return +a concrete handle containing everything needed for later reads and writes. -PlantSimEngine caches that handle. The hot `sample` methods receive it directly, -so they should not search the object registry or repeat spatial routing. +PlantSimEngine stores that handle and passes it directly to `sample` each time. +To keep repeated reads fast, avoid searching all objects or recalculating +their locations in `sample`. `EnvironmentContext` contains application id, object id, scale, and process; -runtime status is deliberately absent. +it does not include the object's current status values. -A controller that reads one provider and writes another can encode both routes -in its handle. For example, the scenario may configure +A controller that reads one data source and writes to another can store both +locations in its handle. For example, the scenario may configure `Environment(provider=:forcing, sink=:canopy)`, while the backend decides what those names mean. -## Trial and commit semantics +## Try values, then save accepted changes -Transient sampling and committing are separate backend operations: +Trying a value and saving it are separate operations: -1. a controller passes its typed trial state to +1. A controller passes a trial environment to `run_call!(context, name; environment=trial_state, publish=false)`; -2. PlantSimEngine invokes the transient `sample` overload through each target's - already-compiled handle; -3. the controller accepts a state and calls +2. PlantSimEngine calls the trial version of `sample` using each target's + stored handle, so each target reads the trial at its own location. +3. The controller accepts a solution and calls `commit_environment!(context, accepted_state)`; -4. PlantSimEngine validates the caller's `environment_outputs_` declaration, - then invokes the backend commit through the caller's handle; -5. the controller publishes accepted called-model outputs explicitly with - `publish=true`. +4. PlantSimEngine checks that `environment_outputs_` allows the controller to + change those variables, then calls the backend's commit method using the + controller's handle. +5. The controller runs the called models with `publish=true` to record their + accepted outputs. -The model-facing `commit_environment!(context, state)` is root API. The -backend-facing method belongs to `PlantSimEngine.EnvironmentAPI`; extension -packages should qualify it when adding methods. +Model code calls `PlantSimEngine.commit_environment!(context, state)`. Your +backend extends the separate function +`PlantSimEngine.EnvironmentAPI.commit_environment!`; use that full name when +defining its method in an extension package. -## Refresh and diagnostics +## Update locations and check the results -PlantSimEngine calls `update_index!` once per distinct spatial backend before -binding or rebinding affected targets. Geometry changes invalidate the affected -handles; structural changes can also change the set of bound targets. +Before creating or updating affected handles, PlantSimEngine calls +`update_index!` once for each spatial backend. Moving an object or changing +its geometry requires an updated handle. Adding, removing, or reparenting +objects can also change which objects a model runs on. -Use these public checks instead of reading compiler fields: +Use these functions to inspect your backend: -- `validate_environment_inputs(model)` checks declared variables; +- `validate_environment_inputs(model)` checks that required variables exist; - `Diagnostics.explain_environment_bindings(model)` reports each application/object handle and geometry source; - `Diagnostics.explain_environment(simulation)` reports the active backend, variables, step count, and base-step duration. -Backend tests should cover at least two objects with distinct handles, -committed and transient sampling, rejected undeclared commits, and handle -refresh after movement or geometry changes. +Test at least two objects that need different local values. Check that your +backend reads both stored and trial values correctly, rejects writes to +undeclared variables, and updates handles when objects move or their geometry +changes. diff --git a/docs/src/guides/graph_visualizer_editor.md b/docs/src/guides/graph_visualizer_editor.md index 7917a3989..b36b04800 100644 --- a/docs/src/guides/graph_visualizer_editor.md +++ b/docs/src/guides/graph_visualizer_editor.md @@ -4,16 +4,17 @@ CurrentModule = PlantSimEngine # Visualize And Edit A CompositeModel -The CompositeModel graph shows how model applications, objects, and compiled value -bindings fit together before a simulation runs. Use the static visualizer when -you want an inspectable HTML artifact, and the interactive editor when you want -browser actions to update a Julia [`CompositeModel`](@ref). +The graph shows which models run on which objects and how values pass between +them. For example, you can follow LAI from the model that calculates it to the +light model that uses it. Use the viewer to explore and share a graph, or the +editor to change your [`CompositeModel`](@ref) from the browser. ## A Small CompositeModel -This example applies three toy models to one plant object. The compiler infers -the same-object `TT_cu` and `LAI` bindings from the declared input and output -names. +This example applies three teaching models to one plant object. The +thermal-time model supplies `TT_cu` to the LAI model, which supplies `LAI` to +the light model. PlantSimEngine connects them using their matching input and +output names. ```@example graph_viewer using PlantSimEngine @@ -39,23 +40,24 @@ embeds it below. ```@raw html - ``` -The default **Applications** projection groups all concrete executions of one -application into one card. Use **Objects** to inspect topology and **Executions** -to inspect concrete `(application, object)` pairs. Search, diagnostics, -initialization, selectors, parameters, and resolved edge details remain -available in the static viewer. The topology projection includes model, -template, and instance containers; selecting an instance or object subtree scopes the -application and execution projections until the filter is cleared. +Use the three views to explore the simulation: + +- **Applications** shows one card for each configured use of a model, even + when it runs on many leaves or plants. +- **Objects** shows the plant structure and groups of objects. +- **Executions** shows each model application on each object separately. + +Select a card or connection to inspect its parameters, inputs, starting +values, and any problems found. Selecting a plant or a branch of the structure +filters the other views to those objects. Clear the filter to see the whole +simulation again. These controls also work in a saved, read-only viewer. ## Write A Static Viewer @@ -66,7 +68,7 @@ server: path = GraphEditor.write_model_graph_view("model-graph.html", model) ``` -The output bundles the graph payload, JavaScript, and CSS in one HTML file. It +The output includes the graph data and viewer code in one HTML file. It can be opened locally or embedded in Documenter documentation. A downstream package can generate the file from `docs/make.jl` and place it under `docs/src/assets`: @@ -80,13 +82,13 @@ GraphEditor.write_model_graph_view( ``` Then embed it from a Markdown page with an HTML `iframe`. The graph is -read-only, but its projection controls, search, inspector, and diagnostics are +read-only, but its views, search, details panel, and error reports are interactive in the browser. ## Start The Editor -The mutable editor is an optional package extension activated by HTTP.jl. Add -HTTP once to the environment that will launch the editor: +The editor needs the optional HTTP.jl package to communicate with Julia. Add +HTTP once to the project where you will use the editor: ```julia using Pkg @@ -103,9 +105,9 @@ session = GraphEditor.edit_graph(model) ``` The default browser opens automatically. The returned session also prints its -URL and shutdown command. Julia remains authoritative: browser edits are sent -as semantic commands, applied transactionally to a candidate CompositeModel, compiled, -and returned as a fresh graph state. +URL and shutdown command. When you make an edit, the browser sends it to +Julia. Julia checks the proposed change before accepting it and sends the +updated graph back to the browser. Inspect the current result or stop the server with: @@ -119,10 +121,10 @@ Call `GraphEditor.edit_graph()` without a CompositeModel to start from an empty ## Templates And Several Plants -A template is a reusable set of already coupled applications. Mounting the same -template twice creates two instance-local application sets. Unqualified selectors -remain inside their own plant, so a model in `plant_a` does not accidentally read -values from `plant_b`. +A template is a reusable set of connected models. Applying the same template +to two plants gives each plant its own set of calculations. By default, the +models look for inputs within their own plant, so a model in `plant_a` does +not accidentally read values from `plant_b`. ```julia using Dates @@ -159,15 +161,16 @@ session = GraphEditor.edit_graph( ) ``` -The **Add instance** wizard can mount a catalog template on an existing unclaimed -root and its descendants, or create a minimal root and mount the template in one -transaction. Preview the claimed subtree and resolved application targets before -committing. Unmounting removes the applications but keeps the object subtree. +Use **Add instance** to apply a template to an existing root object and its +descendants, provided they are not already part of another instance. You can +also create a new root and apply the template in one operation. Preview the +objects and model applications before accepting. Removing the template from +an instance removes its applications but keeps the objects. Catalog templates are presets. The first edit to a mounted preset creates a -model-local replacement shared by all instances that currently use it. The original +replacement within this simulation, shared by all instances that currently use it. The original preset remains available when adding another instance. Template application names -are fixed because they are part of the template contract. +cannot be changed; they identify the applications within the template. ## Overrides @@ -185,13 +188,14 @@ plant_b = ObjectInstance( ) ``` -The editor offers the same operation at instance or object scope. Julia checks that -the replacement implements the same process and variable contract. +The editor can replace a model for a whole plant instance or for an individual +object. Julia checks that the replacement describes the same process and has +compatible inputs, outputs, and other requirements. ## Environment Catalogs And Routing -Environment values remain in Julia. Give the editor a named catalog rather than -serializing backends to the browser: +Give the editor names for the environment sources it can use. The browser +shows these names; the weather data and other environment objects stay in Julia: ```julia session = GraphEditor.edit_graph( @@ -204,14 +208,15 @@ session = GraphEditor.edit_graph( ) ``` -The scene environment can be replaced from this catalog. Each application can use -the scene backend or a catalog backend and can configure `provider`, model-facing -input-to-source mappings, `sink`, and backend-specific typed options. The editor -shows `environment_hint(model)` and the effective compiled bindings read-only, then -asks Julia to validate the candidate routing before it is committed. +You can choose a new environment for the whole simulation or for one model +application. The settings include the source to read (`provider`), any +variable-name translations, and the destination for accepted updates (`sink`). +Other options depend on the environment source. The editor shows the model's +defaults from `environment_hint(model)` and its current environment +connections. Julia checks a proposed change before accepting it. -Application cadence and temporal windows use `Dates.Second`, `Dates.Minute`, -`Dates.Hour`, or `Dates.Day`. Whole-scene targeting is also explicit: +Model time steps and time windows use `Dates.Second`, `Dates.Minute`, +`Dates.Hour`, or `Dates.Day`. To select objects across the whole scene, `SceneScope()` must be selected deliberately. Omitting the scope keeps a template application local to each mounted instance. @@ -219,17 +224,17 @@ application local to each mounted instance. The editor supports: -- model objects, metadata, status initialization, and parent topology; -- model applications, constructor parameters, target selectors, and cadence; -- explicit value bindings, hard calls, output routing, and update ordering; -- template catalogs, transactional instance mounting, shared template edits, and overrides; -- named scene and application environment backends, providers, sources, and sinks; -- dependency cycles through an explicit `PreviousTimeStep` break action; -- undo, redo, temporary recovery autosaves, and readable Julia CompositeModel scripts. +- objects, their labels and starting values, and their place in the structure; +- models, their parameters, which objects they run on, and their time steps; +- input connections, calls between models, saved outputs, and update order; +- templates, plant instances, and model replacements; +- environment sources and destinations for the scene or individual models; +- feedback loops, by choosing an input that should read the previous step; +- undo, redo, recovery files, and saving the simulation setup as Julia code. -Application target and binding dialogs can ask Julia to preview the concrete -objects selected by a declaration. This is important for `Many`, relative -scopes such as `SelfPlant`, and composite models containing several plant instances. +When selecting objects or connecting inputs, preview the matching objects +before applying the change. This helps check selections such as `Many` and +`SelfPlant`, especially when the simulation contains several plants. ## Models From Other Packages @@ -245,34 +250,36 @@ using HTTP session = GraphEditor.edit_graph(model) ``` -The `+` buttons next to ports use exact declared variable names only. For an +The `+` buttons next to inputs and outputs search by exact variable name. For an input named `LAI`, the editor lists loaded models whose `outputs_` contains `LAI`. For an output named `LAI`, it lists models whose `inputs_` contains `LAI`, as well as compatible applications already present in the CompositeModel. This is -a composition aid, not a scientific compatibility inference. +a way to find possible connections. You still need to check the units and +physical meaning of the values. When the CompositeModel is saved as Julia code, required package imports are emitted for the model types used by the CompositeModel. ## Invalid And Cyclic Composite Models -Simulation compilation remains strict, but graph compilation preserves as much -structure as possible and attaches diagnostics. This lets the editor display -incomplete selectors, missing initialization, ambiguous writers, and cycles. +The editor can display an incomplete simulation and show its problems, even +when it cannot run yet. These include missing starting values, selections +that do not identify the intended objects, several models trying to set the +same output, and circular dependencies. -Cycle edges are shown in red. The break workflow asks which consumer input -should read its previous accepted timestep value and asks for initial values -when the affected target objects do not already provide one. The action changes -the application input policy for every target selected by that application. +Connections in a circular dependency are shown in red. To break a loop, choose +which input should read the previous step's value. The editor also asks for +starting values if the objects do not have them. This change applies to every +object selected by that model application. !!! warning - `PreviousTimeStep` changes model semantics. It disconnects the selected - input from current-step producers during one run step. Use it only when that - lag and its initialization value are scientifically intentional. + `PreviousTimeStep` changes the calculation: the model reads an older value + instead of the value calculated at the current step. Use it only when this + delay and the starting value make sense for your scientific model. ## Saving And Recovery -The **Save** action writes readable Julia code whose final binding is +The **Save** action writes readable Julia code ending with `model = CompositeModel(...)`. Once a path is selected, every successful edit rewrites that file. The editor also keeps a temporary recovery file and lists recent CompositeModel scripts in **Open**. @@ -286,12 +293,12 @@ source = Authoring.scenario_source( ) ``` -This is editable scenario code. It is distinct from -`Authoring.compiled_model_source(model)`, which exposes the resolved execution -plan for inspection and is not a second scheduler. +Use this code to edit or share the simulation setup. +`Authoring.compiled_model_source(model)` provides a more detailed view of how +PlantSimEngine will run the calculations. -Generated code is best effort for arbitrary Julia values and external runtime -resources. Templates and instances are written inline. Named environment values are +Some Julia values and external resources cannot be recreated automatically +from a saved script. Templates and instances are written into the script. Named environment values are referenced through a `scenario_environments` named tuple, and the generated header lists the keys that must be supplied when reopening the file: diff --git a/docs/src/guides/modelers/port_existing_model.md b/docs/src/guides/modelers/port_existing_model.md index b12231b21..dc51bb18b 100644 --- a/docs/src/guides/modelers/port_existing_model.md +++ b/docs/src/guides/modelers/port_existing_model.md @@ -1,147 +1,148 @@ # Port an existing model -Start from the scientific calculation and separate four concerns: immutable -parameters, object state, environment forcing, and produced values. The -`run!` method should remain a readable account of one target and one -timestep, while PlantSimEngine owns object selection, scheduling, and value -transport. +Start from a calculation you already understand and test it before moving it. +Identify its fixed parameters, the values that change during a simulation, +the environmental data it needs, and the results it calculates. Keep the +equation unchanged while giving each quantity a clear place. -## A complete small kernel +## Begin with an existing calculation -This pedagogical model grows leaf area index from temperature. Its numerical -values illustrate the interface only; they are not a calibrated plant model. +This small teaching function computes a new leaf area index from its current +value and a linear temperature response. The coefficients are arbitrary; +this is not a calibrated growth model. It represents one update over a fixed +interval. ```@example port-existing-model -using Dates -using PlantSimEngine +using Dates, Test, PlantSimEngine -PlantSimEngine.@process "docs_lai_growth" verbose=false +old_lai_step(lai, temperature, response) = lai + response * temperature +expected = old_lai_step(1.0f0, 10.0f0, 0.02f0) +expected +``` + +Before porting a real model, record its units, time interval, assumptions, +and expected results. If it calculates a rate, check how that rate becomes +an amount: for example, where a daily growth rate is multiplied by the +number of days. + +## Map each quantity to its role + +| Quantity | Role in this example | Place in PlantSimEngine | +|---|---|---| +| Response coefficient | Fixed parameter for one update | Model field | +| Current LAI | Current leaf area per ground area | `status.lai` | +| Air temperature | Environmental input, degrees Celsius | `environment.T` | +| New LAI | Result of this update | `status.lai_next` | +The complete declarations are: + +```@example port-existing-model +@process "docs_lai_growth" verbose=false struct DocsLAIGrowth{T} <: AbstractDocs_Lai_GrowthModel - rate::T + response::T end PlantSimEngine.inputs_(::DocsLAIGrowth) = (lai=Required(Real),) PlantSimEngine.outputs_(model::DocsLAIGrowth) = ( - lai_next=zero(model.rate), + lai_next=zero(model.response), ) PlantSimEngine.environment_inputs_(model::DocsLAIGrowth) = ( - T=zero(model.rate), + T=zero(model.response), ) PlantSimEngine.environment_outputs_(::DocsLAIGrowth) = NamedTuple() +``` +`Required` means the simulation must supply the current LAI. The output and +environment declarations use the parameter's numerical type. A real model +should reuse its package's existing process where appropriate; see +[New process or new model?](@ref). + +## Preserve the physical meanings + +Both LAI values describe leaf area per unit ground area. Temperature is in +degrees Celsius. We record these meanings with `VariableContract`, which +also describes whether each variable is a current value, a rate, or a total: + +```@example port-existing-model const DOCS_LAI_CONTRACT = VariableContract( - unit=:m2_leaf_per_m2_ground, - basis=:ground, - temporal=:instantaneous, - aggregation=:state, - extent=:intensive, + unit=:m2_leaf_per_m2_ground, basis=:ground, temporal=:instantaneous, + aggregation=:state, extent=:intensive, ) const DOCS_TEMPERATURE_CONTRACT = VariableContract( - unit=:degree_celsius, - basis=:air, - temporal=:instantaneous, - aggregation=:state, - extent=:intensive, + unit=:degree_celsius, basis=:air, temporal=:instantaneous, + aggregation=:state, extent=:intensive, ) - PlantSimEngine.variable_contracts_(::DocsLAIGrowth) = ( lai=DOCS_LAI_CONTRACT, lai_next=DOCS_LAI_CONTRACT, T=DOCS_TEMPERATURE_CONTRACT, ) +``` +Here `temporal=:instantaneous` and `aggregation=:state` describe current +values. `extent=:intensive` means that adding values from two objects does +not give their combined value: two air temperatures, for example, cannot +be added to obtain the temperature of both objects together. + +These descriptions help check that connected models interpret a variable in +the same way. They do not convert values or prove that the equation is +scientifically valid. + +## Keep the calculation readable + +The function now reads from the declared locations and assigns the result: + +```@example port-existing-model function PlantSimEngine.run!( - model::DocsLAIGrowth, - status, - environment, - constants, - context, + model::DocsLAIGrowth, status, environment, constants, context, ) - status.lai_next = status.lai + model.rate * environment.T + status.lai_next = status.lai + model.response * environment.T return nothing end ``` -The struct contains only fixed parameters. Status fields contain values that -can change between timesteps. The environment contains sampled forcing. -`VariableContract` records scientific meaning at coupling boundaries without -wrapping the numerical values. - -Keep parameter and status types generic. `Required(Real)`, -`zero(model.rate)`, and a parametric model field allow compatible values such -as `Float32`, measurements with uncertainty, or automatic-differentiation -numbers. Do not convert inputs to `Float64` inside the kernel. +Use helpers for substantial equations, reused calculations, or numerical +algorithms. Keep a short equation visible rather than splitting every +arithmetic step into a separate function. -## Test before composing - -Call the kernel directly first: +## Compare with the original before composing ```@example port-existing-model growth = DocsLAIGrowth(0.02f0) status = Status(lai=1.0f0, lai_next=0.0f0) -PlantSimEngine.run!( - growth, - status, - (T=10.0f0,), - nothing, - nothing, -) -(lai_next=status.lai_next, value_type=typeof(status.lai_next)) +PlantSimEngine.run!(growth, status, (T=10.0f0,), nothing, nothing) +@test status.lai_next == expected +@test status.lai_next isa Float32 +@test Authoring.validate_model(growth; strict=true).valid +status.lai_next ``` -Then exercise initialization, environment binding, and scheduling through the -ordinary runtime: +Then check the ordinary simulation path with the same inputs: ```@example port-existing-model -model = CompositeModel( +scenario = CompositeModel( growth; status=(lai=1.0f0,), environment=(T=10.0f0, duration=Day(1)), ) - -validation = Authoring.validate_model(growth; strict=true) -@assert validation.valid -initialization = Diagnostics.explain_initialization(model) -simulation = run!(model) -@assert final_state(simulation).lai_next == 1.2f0 -final_state(simulation) +result = final_state(run!(scenario)).lai_next +@test result == expected +result ``` -These levels separate a scientific-equation error from a model-contract error -and a scenario-binding error. Continue with -[Model repository layout and tests](@ref) for the full test pyramid. - -## Keep the scientific narrative visible - -Prefer one continuous kernel that can be read from inputs to outputs. Extract a -helper only when it is: - -- a named scientific equation worth testing or citing separately; -- reused by several model implementations; -- an iterative or numerical algorithm that would obscure the process - equation; or -- a measured optimization whose details should be isolated. - -Do not split every arithmetic line into a helper. Conversely, if users need to -replace a subprocess independently, implement that subprocess as its own -PlantSimEngine model instead of hiding it in a helper or a large -`variant` branch. - -Reset instantaneous outputs before an early return, keep timestep-varying state -out of the model struct, and finish `run!` with `return nothing`. Model code -should not search the object graph or infer its own timestep; declare those -requirements through ports, selectors, hard calls, and traits. - -## Porting checklist - -1. Identify fixed parameters, status inputs, environment inputs, outputs, and - mutable state. -2. Decide whether independently replaceable subprocesses need separate models. -3. Replace implicit defaults and sentinels with `Required(T)` or a - scientifically meaningful `Default(value)`. -4. Declare units, basis, temporal meaning, aggregation, and extent with - `VariableContract` where values are coupled. -5. Convert hidden calls into a declared `Call` only when the parent must own - child execution. -6. Test the kernel, then a minimal composition, before a full scenario. +This example computes a single new value. For repeated updates, decide +explicitly how that value becomes the next input; see +[State, History, And Repeated Updates](@ref). + +## Extend only what your model needs + +Keep values that change over time in each object's status and fixed +parameters in the model. Preserve the numerical types your model supports +rather than converting every value to `Float64`. If an output describes the +current step, assign it every time the model runs, including when a condition +ends the calculation early. Otherwise, an old result may be mistaken for +today's result. + +If users need to replace one part of the calculation or run it at a different +frequency, make that part a separate model. Use [Coupling models](@ref) for its connections and +[Model repository layout and tests](@ref) for broader validation. diff --git a/docs/src/guides/modelers/repository_and_tests.md b/docs/src/guides/modelers/repository_and_tests.md index b236eecf7..e52b3ec6d 100644 --- a/docs/src/guides/modelers/repository_and_tests.md +++ b/docs/src/guides/modelers/repository_and_tests.md @@ -1,11 +1,10 @@ # Model repository layout and tests -A model package should make process ownership, alternative hypotheses, and -validation levels visible from the directory tree. The exact hierarchy may -follow domains or plant scales, but keep one file per concrete model and group -alternatives under their shared process. +Organize a model package so a colleague can find the equation, its alternative +hypotheses, and the evidence used to test it. A small package can start with +one model file and one test file, then grow as needed. -## Recommended layout +## Group alternatives by scientific process ```text src/ @@ -30,87 +29,88 @@ docs/src/models/ └── growth.md ``` -Use `process.jl` only when this package owns the process declaration. If a -dependency already declares the process, import and subtype its abstract model -type rather than declaring a second identity. - -This convention retains the useful pattern from -`PlantBiophysics/src/processes//`, where alternatives such as FvCB and -constantA live beside their shared process. XPalm similarly makes process -identity and alternatives visible through files such as `0-process.jl`, -`rue.jl`/`rue_ftsw.jl`, and `Q10.jl`/`Q10_BP.jl`. Keep the invariant—one shared -process identity and one readable file per hypothesis—but prefer the explicit -name `process.jl` over the historical ordering prefix `0-process.jl`. These -packages are design references, not moving dependencies of this tutorial or -its tests. - -Keep includes and exports explicit in the package module. A process page should -compare the available implementations side by side: assumptions, ports, -`VariableContract`s, parameters, domain of validity, references, and scientific -validation status. Put incomplete experiments outside the public `src/` -include path, or mark their maturity unambiguously. - -Large scenario assemblies deserve named fragments by domain or scale, for -example `leaf_applications(parameters)`, `plant_applications(parameters)`, -and `soil_applications(parameters)`. These functions return ordinary -`ModelSpec` collections; they do not introduce another scenario runtime. - -## Test pyramid - -Test failures are easiest to interpret when each level adds one responsibility: - -1. **Schema and contracts:** inspect `inputs_`, `outputs_`, - `environment_inputs_`, `environment_outputs_`, and `variable_contracts_`. -2. **Direct kernel:** call `run!` on a minimal `Status` and sampled environment. -3. **One-object composition:** check defaults, inferred same-object bindings, - and scheduling. -4. **Explicit coupling:** test renamed, cross-object, `Many`, temporal, and - hard-call inputs used by the model. -5. **Diagnostics:** assert the intended application, source, carrier, call, - writer, and schedule rows. -6. **Scenario regression:** compare a small scientifically interpretable - scenario with a trusted result. -7. **Generic numerics and performance:** exercise supported numeric types and - allocation-sensitive organ loops. - -The first two levels should remain small enough to run after every model edit: +Use `process.jl` only when this package declares a new process. If another +package already declares it, import that package's abstract process type. +Keep one readable file per hypothesis. List the files to include and the +names users can import in `MyModels.jl`. + +A process page should compare the alternatives: equations, assumptions, +required data, units, parameters, references, and the conditions under which +each model has been tested. Label teaching models and unfinished experiments +clearly. + +## Test from the equation outward + +Each level answers a different question: + +| Check | Question it answers | +|---|---| +| Direct equation test | Does the implementation reproduce a known calculation? | +| Declaration check | Are required inputs, outputs, and physical meanings explicit? | +| Small simulation | Can the model obtain its inputs and run on the intended object? | +| Coupled scenario | Does it interact correctly with the other models used in this study? | + +Start with the biomass example from +[Implement a basic model](@ref): ```@example repository-tests -using Test -using PlantSimEngine -using PlantSimEngine.Examples - -model = ToyDevelopmentModel(0.5f0) -@test keys(PlantSimEngine.inputs_(model)) == (:TT, :stress) -@test keys(PlantSimEngine.outputs_(model)) == (:growth,) -@test isempty(PlantSimEngine.environment_inputs_(model)) -@test isempty(PlantSimEngine.environment_outputs_(model)) - -status = Status(TT=8.0f0, stress=0.75f0, growth=0.0f0) -PlantSimEngine.run!(model, status, nothing, nothing, nothing) -@test status.growth == 3.0f0 -@test status.growth isa Float32 - -composite = CompositeModel(model; status=(TT=8.0f0,)) -simulation = run!(composite) -@test final_state(simulation).growth == 4.0f0 +using Dates, Test, PlantSimEngine +include(joinpath( + pkgdir(PlantSimEngine), "skills", "plantsimengine", + "assets", "minimal-model.jl", +)) +using .MinimalModelExample + +model = RadiationUseEfficiency(1.5f0) +status = Status(intercepted_par=10.0f0, biomass_increment=0.0f0) +PlantSimEngine.run!(model, status, NamedTuple(), nothing, nothing) +@test status.biomass_increment == 15.0f0 +@test status.biomass_increment isa Float32 +@test Authoring.validate_model(model; strict=true).valid + +scenario = CompositeModel( + model; status=(intercepted_par=10.0f0,), timestep=Day(1), +) +@test final_state(run!(scenario)).biomass_increment == 15.0f0 ``` -A green full-scenario test does not replace the kernel test: it usually cannot -show whether an error came from the equation, a contract, object selection, or -the scenario data. Likewise, a direct kernel test does not prove that -cross-object bindings or lifecycle behavior compile correctly. - -## Review checklist for a new hypothesis - -- The concrete type subtypes the intended existing process. -- Parameters are immutable and generic where the mathematics permits. -- Every status and environment read is declared. -- Every written status field is declared as an output. -- Connected scientific variables have complete, matching contracts. -- The main `run!` reads as a continuous scientific calculation. -- Alternative models do not hide behind a mode flag. -- Direct, composition, coupling, and generic-numeric tests cover the model's - actual responsibilities. -- Documentation states what is measured, tested, proposed, or still - scientifically unvalidated. +These small checks test the equation first, then test how the simulation +supplies its inputs and runs it. +For a scientific model, add edge cases and a trusted reference calculation +or dataset. Agreement with the reference needs a numerical tolerance +appropriate to the calculation. + +## Add checks for the features you use + +If a model reads values from other objects, check that it uses the intended +objects. If coupled models run at different frequencies, check what happens +when each one updates. For a growing plant, check results before and after +organs are added or removed. For a model that tries several solutions, test +both rejected trials and the results it finally accepts. + +Use `Diagnostics` to inspect the relevant connections and schedules, then +assert the scientific relationship you intend to preserve. For example, +check that a plant total uses its own leaves and excludes a neighbouring +plant's leaves. + +Exercise the numerical types your model supports. Measure performance where +large organ counts or repeated calls matter; keep such benchmarks separate +from equation checks. See [Numerical Reliability](@ref) and the +[benchmarking guidance](../../developers.md). + +## Review a new hypothesis + +Before sharing a model, check that: + +- it belongs to the intended process; +- its inputs, outputs, units, and timing are documented, including whether + each value is per organ, per plant, or per unit area; +- its equation and fixed parameters are easy to find; +- each object's changing state stays separate; +- direct tests and the relevant coupled tests pass; +- scientific validation and remaining uncertainty are stated. + +When a simulation setup becomes long, group the `ModelSpec` definitions into +functions for leaf, plant, and soil processes, for example. Have those +functions return the `ModelSpec` values so readers can still see which +models are used and how they are connected. diff --git a/docs/src/guides/modelers/stateful_models.md b/docs/src/guides/modelers/stateful_models.md index cc6b59ffb..dc33988ba 100644 --- a/docs/src/guides/modelers/stateful_models.md +++ b/docs/src/guides/modelers/stateful_models.md @@ -1,11 +1,156 @@ # State, History, And Repeated Updates -Object `Status` is current state, not timestep storage. Use -`PreviousTimeStep(:x)` for a one-step lag, or keep a model-owned ring buffer -when the algorithm requires deeper history. Accepted output streams provide -simulation history. +A model may need yesterday's value or a short memory of earlier values. +Keep that changing memory in each object's `Status`. The model itself holds +fixed parameters and may be shared by many objects. -Several writers to one canonical variable are rejected unless the application -declares `Updates`. Iterative trial execution belongs to `calls`; use -`publish=false` until a state is accepted. +These are different needs: +| Need | Where it belongs | +|---|---| +| Current state used by the next calculation | The object's `Status` | +| A previous value from a model output | An explicit `PreviousTimeStep` input | +| Internal memory needed by an algorithm | Declared state fields in each object's `Status` | +| A record to plot or analyse after the run | Retained simulation outputs | + +## Example: a mean of three daily observations + +Suppose we want the mean of today's soil-water fraction and the two preceding +daily observations: + +**mean = (today + previous observation + older observation) / 3** + +All three observations are dimensionless fractions. This example shows how +each soil object keeps its own past observations. It does not model plant +water stress. + +```@example object_memory +using Dates, Test, PlantSimEngine + +@process "docs_three_day_mean" verbose=false +struct DocsThreeDayMean <: AbstractDocs_Three_Day_MeanModel end + +PlantSimEngine.inputs_(::DocsThreeDayMean) = ( + water_fraction=Required(Real), +) +PlantSimEngine.outputs_(::DocsThreeDayMean) = ( + previous_fraction=0.0, + older_fraction=0.0, + mean_fraction=0.0, +) +PlantSimEngine.environment_inputs_(::DocsThreeDayMean) = NamedTuple() +PlantSimEngine.environment_outputs_(::DocsThreeDayMean) = NamedTuple() +``` + +The two memory fields are outputs because this model updates them. Their +initial values must represent observations before the first simulated day. +Each object can supply different initial values. The `VariableContract` +descriptions below record that the observations are soil-water fractions, +while the result is a mean of three daily samples. + +```@example object_memory +const FRACTION_SAMPLE = VariableContract( + unit=:fraction, basis=:soil_water, temporal=:instantaneous, + aggregation=:state, extent=:intensive, +) +const FRACTION_MEAN = VariableContract( + unit=:fraction, basis=:soil_water, temporal=:three_daily_samples, + aggregation=:mean, extent=:intensive, +) +PlantSimEngine.variable_contracts_(::DocsThreeDayMean) = ( + water_fraction=FRACTION_SAMPLE, + previous_fraction=FRACTION_SAMPLE, + older_fraction=FRACTION_SAMPLE, + mean_fraction=FRACTION_MEAN, +) + +function PlantSimEngine.run!( + ::DocsThreeDayMean, status, environment, constants, context, +) + status.mean_fraction = + (status.water_fraction + status.previous_fraction + status.older_fraction) / 3 + status.older_fraction = status.previous_fraction + status.previous_fraction = status.water_fraction + return nothing +end +``` + +Calculate the mean before shifting the memory: reversing that order would +use today's observation twice. + +## Check the calculation directly + +```@example object_memory +model = DocsThreeDayMean() +sample = Status( + water_fraction=0.6, previous_fraction=0.3, older_fraction=0.3, + mean_fraction=0.0, +) +PlantSimEngine.run!(model, sample, nothing, nothing, nothing) +@test sample.mean_fraction ≈ 0.4 +@test sample.previous_fraction == 0.6 +@test sample.older_fraction == 0.3 +sample.mean_fraction +``` + +## Keep two objects' histories independent + +Here the observations stay constant during the example. A real simulation +would read each day's value from a dataset or another model. + +```@example object_memory +dry = Object( + :dry_soil; scale=:Soil, + status=Status(water_fraction=0.6, previous_fraction=0.3, older_fraction=0.3), +) +wet = Object( + :wet_soil; scale=:Soil, + status=Status(water_fraction=0.9, previous_fraction=0.9, older_fraction=0.9), +) +scenario = CompositeModel( + dry, wet; + applications=(ModelSpec(model; name=:water_mean, on=Many(scale=:Soil)),), + environment=(duration=Day(1),), +) +@test Authoring.validate_model(model; strict=true).valid + +simulation = run!(scenario; outputs=:all) +day_one = ( + dry=final_state(simulation, :dry_soil).mean_fraction, + wet=final_state(simulation, :wet_soil).mean_fraction, +) +@test day_one.dry ≈ 0.4 +@test day_one.wet ≈ 0.9 + +step!(simulation) +day_two = ( + dry=final_state(simulation, :dry_soil).mean_fraction, + wet=final_state(simulation, :wet_soil).mean_fraction, +) +@test day_two.dry ≈ 0.5 +@test day_two.wet ≈ 0.9 +(day_one=day_one, day_two=day_two) +``` + +Both objects use the same model. Their separate status fields keep the dry +soil's earlier observations from affecting the wet soil's mean. If an +algorithm stores earlier values in an array, give each object its own array +as well. An array stored in the shared model would mix the objects' histories. + +## Delays, repeated calls, and output history + +Use `PreviousTimeStep` when an input should read another model's accepted +result from the previous time step. The +[model execution reference](../../model_execution.md) shows how to declare +this input. If several models deliberately update the same variable, use +`Updates` to set their order; see [Control Advanced Execution](@ref). + +A trial call with `publish=false` does not save its result as an accepted +output sample. It can still change values in `status`, and those changes +are not automatically undone. A model that tries several solutions must +decide which changes to keep. Update a history like the one above once per +accepted observation, so rejected trials do not enter the mean. + +Use [Collecting And Plotting Outputs](@ref) to retain and analyse a result +series. Keeping outputs and maintaining a model's own short memory serve +different purposes. diff --git a/docs/src/guides/multiscale/concepts.md b/docs/src/guides/multiscale/concepts.md index 9d201c6e4..3c0296ed9 100644 --- a/docs/src/guides/multiscale/concepts.md +++ b/docs/src/guides/multiscale/concepts.md @@ -1,32 +1,39 @@ # How Multiscale Composite Models Execute -One application executes once for every object selected by its -`ModelSpec(...; on=...)` selector. State belongs to the object, while topology -and labels belong to the scenario. -`Self()` is the current object, `SelfPlant()` is its plant-instance root, and -`SceneScope()` is model-wide. Cardinality wrappers decide whether zero, one, -or many matches are valid. +An **application** is a model configured with `ModelSpec`: it says where the +model runs and where its inputs come from. For example, +`ModelSpec(model; on=Many(scale=:Leaf))` runs that model once on each leaf. +Each leaf keeps its own values in `Status`. You define the objects, their +labels, and their parent relationships when building the simulation. -More objects mean more qualified streams. Removing an object stops future -execution but preserves its accepted historical samples. +Selectors choose objects by these labels and relationships. `Self()` means +the object whose model is currently running. `SelfPlant()` limits a search +to that object's plant, starting from the top of its structure. +`SceneScope()` allows the search to include the whole simulation. Wrap a +selection in `One`, `OptionalOne`, or `Many` to require exactly one match, +allow zero or one, or accept a collection. -Canonical selector patterns are: +Common choices are: | Relationship | Pattern | | --- | --- | | application targets every leaf | `ModelSpec(model; on=Many(scale=:Leaf))` | -| input from this same object | omit `inputs` when the producer is unique | +| input from this same object | omit `inputs` when exactly one model supplies the matching output | | input from one ancestor | `One(Ancestor(scale=:Plant))` | | input from this plant's leaves | `Many(scale=:Leaf, within=SelfPlant())` | | input from shared soil | `One(scale=:Soil, within=SceneScope())` | | optional named organ | `OptionalOne(name=:fruit, within=SelfPlant())` | -`Self()` always means the current target object. It never implicitly means the -model, process, species, or plant. Prefer object IDs and labels for identity, -and use `Scope(name)` only when the model explicitly defines that scope. +For a model running on a leaf, `Self()` means that leaf, not its plant or its +species. Use object IDs and labels to select specific objects or groups. +`Scope(name)` refers to a named search area that you must define in the +simulation before using it. -One application produces a separate stream for every selected object and -output variable. Stream keys also include application identity, so repeated -applications of the same process cannot overwrite each other. Use -`Diagnostics.explain_applications`, `Diagnostics.explain_objects`, and `Diagnostics.explain_bindings` to -verify target and source multiplicities before a long run. +Saved results identify the application, object, and variable. Each leaf's +history therefore stays separate, including when you use the same process +more than once. Removing an organ stops its future calculations but keeps +the results already saved for it. + +Before a long run, use `Diagnostics.explain_objects` to check the plant +structure, `Diagnostics.explain_applications` to check where models run, and +`Diagnostics.explain_bindings` to check where they read their inputs. diff --git a/docs/src/guides/multiscale/from_one_object.md b/docs/src/guides/multiscale/from_one_object.md deleted file mode 100644 index 3ebfa4ca1..000000000 --- a/docs/src/guides/multiscale/from_one_object.md +++ /dev/null @@ -1,10 +0,0 @@ -# From One Object To A Multiscale CompositeModel - -First run all models on one object with the concise `CompositeModel(models...; -status=...)` constructor. Then move organ-specific applications to leaf -objects and aggregate their outputs on a plant with `Many(..., -within=SelfPlant())` or an instance-local selector. - -Compare collected, application-qualified outputs with `isapprox`. Exact bitwise -identity is not generally a valid requirement after changing reduction order. - diff --git a/docs/src/guides/multiscale/import_mtg.md b/docs/src/guides/multiscale/import_mtg.md index 70f7e2b2b..4190ab2b6 100644 --- a/docs/src/guides/multiscale/import_mtg.md +++ b/docs/src/guides/multiscale/import_mtg.md @@ -1,10 +1,80 @@ -# Importing An MTG +# Import A Plant From An MTG -`objects_from_mtg(root)` converts MTG topology and labels into ordinary model -objects. `CompositeModel(root; applications=...)` performs the same adaptation and then -uses the normal CompositeModel compiler. The MTG is an input representation, not a -second runtime. +A MultiScaleTreeGraph (MTG) stores a plant's organs and their relationships. +Use it when you already have a measured or generated architecture. The models +and value connections are the same as in [One multiscale plant](../../journeys/users/one_plant.md); +the MTG supplies the objects and records which organ each one belongs to. -For growth, prefer `add_organ!`: it creates the MTG node, applies the model's -status policy by default, attaches status, and registers the corresponding -object. +Install `MultiScaleTreeGraph` in your project to run this example. We create a +small MTG here so no external data file is needed: + +```@example import_mtg +using PlantSimEngine, MultiScaleTreeGraph, DataFrames +using PlantSimEngine.Examples + +root = Node(NodeMTG("/", :Plant, 1, 0)) +leaf_1 = Node(root, NodeMTG("/", :Leaf, 1, 1)) +leaf_2 = Node(root, NodeMTG("/", :Leaf, 2, 1)) +leaf_1[:carbon_biomass] = 50.0 +leaf_2[:carbon_biomass] = 100.0 +nothing # hide +``` + +The `/` links describe leaves as components at a finer scale than the plant; +this reduced architecture omits stems and petioles. For an existing MTG file, replace these lines with +`root = read_mtg("my_plant.mtg")`. Inspect its symbols first: this example uses +`:Plant` and `:Leaf`, but your file may use different names. + +## Choose which attributes become simulation state + +PlantSimEngine imports each node's ID and parent automatically. By default, +it uses the MTG symbol, such as `:Leaf`, as the object's `scale` label. +It does **not** automatically copy numerical attributes into `Status`, +where models read and store their values. The function below chooses the +initial values to import: each leaf's carbon biomass in this example. + +```@example import_mtg +initial_status(node) = MultiScaleTreeGraph.symbol(node) == :Leaf ? + Status(carbon_biomass=node[:carbon_biomass]) : Status() + +model = CompositeModel( + root; + status=initial_status, + applications=( + ModelSpec(ToyLeafSurfaceModel(0.02); + name=:leaf_surface, on=Many(scale=:Leaf)), + ModelSpec(ToyPlantLeafSurfaceModel(); + name=:plant_surface, on=One(scale=:Plant), + inputs=(leaf_surfaces=Many( + scale=:Leaf, within=Subtree(), + application=:leaf_surface, var=:surface, + ),)), + ), +) + +DataFrames.select(DataFrame(Diagnostics.explain_objects(model)), :id, :scale, :parent) +``` + +The teaching leaf model uses carbon biomass in g C and a specific leaf area +of 0.02 m² per g C. It gives leaf areas of 1 and 2 m², whose sum is 3 m²: + +```@example import_mtg +simulation = run!(model; outputs=:all) +plant_area = final_state(simulation, One(scale=:Plant)).surface +@assert plant_area ≈ 3.0 # hide +plant_area +``` + +## Keep the link to the MTG when the plant grows + +`CompositeModel(root; ...)` keeps the relationship between MTG nodes and +simulation objects. Use `object_id(model, leaf_1)` to find the object for a +node. When you create an organ with `add_organ!`, PlantSimEngine reuses your +`initial_status` function to set its initial values. The new node must have +the attributes this function reads, or the function must supply suitable +initial values itself. +See [Growth within a time step](../../tutorials/growing_plant/part1_growth.md). + +Use `objects_from_mtg(root; status=initial_status)` when you only want a +list of `Object`s to assemble yourself. It does not keep the node-to-object +lookup needed to find nodes or create new organs through the MTG later. diff --git a/docs/src/guides/multiscale/manual_calls.md b/docs/src/guides/multiscale/manual_calls.md index edf8f73e3..db49c70b2 100644 --- a/docs/src/guides/multiscale/manual_calls.md +++ b/docs/src/guides/multiscale/manual_calls.md @@ -1,36 +1,45 @@ # Manual Calls Across Objects -Declare parent-owned execution with -`ModelSpec(model; calls=(:name => One(...),))` or a `Many(...)` selector. In -the kernel, execute every resolved target with `run_call!(context, :name)`. -The returned `CallTargets` collection is always vector-like, including for -`One` and `OptionalOne`. +Some calculations need to control when another model runs. For example, a +plant model may need to run its leaf models several times while solving an +energy balance. Declare the models it can call with +`ModelSpec(model; calls=(:name => One(...),))`, using `Many(...)` to select +several objects. Inside its `run!` function, call +`run_call!(context, :name)` to run all the selected models. The returned +`CallTargets` is a collection, even when `One` or `OptionalOne` selects a +single object. -Use the narrowest execution path that matches the algorithm: +Choose how to make the call according to what your calculation needs: - `run_call!(context, :name; sampled_environment=environment)` executes all - targets directly through cached typed batches. Prefer it when the caller has - already sampled one model-facing environment for every target. -- `call_model(context, :name)` returns the concrete model for a call that - resolves to exactly one target. It is useful when dispatch or model - parameters must be inspected before the bulk call. + selected models with the same environmental values. Use it when you have + already prepared the values each model needs. PlantSimEngine groups these + calls for efficient execution. +- `call_model(context, :name)` returns the model when the call selects exactly + one target. Use it to inspect the model's type or parameters before running + the calculation. - `call_targets(context, :name)` followed by `run_call!(target)` supports - object selection, custom ordering, target status inspection, or a different - sampled environment per target. + running selected objects individually. Use it to choose their order, + inspect their values, or supply different environmental values to each one. -`environment=trial_state` has different semantics from -`sampled_environment=value`. The former is a transient backend state that each -target samples through its compiled environment handle. The latter is already -in the model-facing form and is forwarded without sampling. +The two environment keywords serve different purposes. +`environment=trial_state` supplies a trial version of the environment, from +which PlantSimEngine retrieves the conditions at each selected object. +`sampled_environment=value` supplies the environmental variables directly in +the form the model reads, so no further sampling occurs. -A target used only by calls is absent from root scheduling. Trial calls default -to `publish=false`; publish only an accepted execution. +A model used only through these calls does not also run independently from +the simulation schedule. Calls default to `publish=false`, so trial results +are not saved in the output history. Use `publish=true` for the accepted +calculation. ## Initialize a newly registered object -Use `Initializer`, not an ordinary manual `Call`, when the target application -must remain in the root schedule but a creator needs to run it once on a new -object after its normal slot already passed: +Suppose a leaf model has already run for this timestep and a growth model +then creates a new leaf. The growth model can use `Initializer` to run that +leaf model once on the new leaf. The leaf model still runs normally from the +simulation schedule on other timesteps. Declare the initializer in the +growth model's `calls`, then pass the new object to `run_initializer!`: ```julia creator = ModelSpec( @@ -58,74 +67,105 @@ function PlantSimEngine.run!(::GrowthModel, status, environment, constants, cont end ``` -Initializer selectors follow the ordinary contextual-scope rules. A call from -a plant object defaults to `Self()`, so a creator targeting a new descendant -must state `within=Subtree()` explicitly. A scene creator may instead use -`within=SceneScope()` when the target is scene-wide. - -The target application must use `on=Many(...)`, an explicit `application=`, -and exactly the caller's cadence and phase. It remains root-scheduled and owns -its canonical outputs. The compiler orders it before the creator and orders -the execution owners of same-step consumers after the creator. That owner is -the consumer itself for an ordinary scheduled application, the root hard-call -owner for a manual callee, or the consumer's creator when it is another -initializer target. If both calls belong to the same creator, its kernel must -invoke the initializers in dependency order; there is no meaningful self-edge -to impose that intra-kernel order. Targeted newborn -execution supports the global environment, canonical local outputs, -non-temporal inputs, and `PreviousTimeStep` inputs, including canonical input -sources written through another application's `outputs_to`. It rejects nested -calls, distributed or stream-only outputs on the initializer target itself, -other temporal policies, mixed manual ownership, multiple initializer owners, -and any overlapping local or distributed canonical writer for the target's -outputs. Each initialized output must have one canonical writer; `Updates` -ordering cannot make a later writer safe because targeted execution occurs -inside the creator's kernel. - -Only direct, non-temporal downstream consumers may observe the initialized -output later in that same step. `run_initializer!` deliberately publishes no -mid-step stream sample, so the compiler rejects downstream `HoldLast` windows, -`Interpolate`, `Integrate`, `Aggregate`, and `PreviousTimeStep` bindings that -could consume an initializer target's newborn output. This is distinct from a -`PreviousTimeStep` input *used by the initializer itself*, whose newborn -fallback is supported. This first initializer contract does not admit a -temporal downstream binding at all. When later history is required, publish -the value from a distinct scheduled application and consume that application's -history on a later timestep. - -An initializer binding stores only its statically validated application -identity. It does not collect pre-existing target objects or build cached -execution batches; `run_initializer!` resolves only the explicit newborn. - -`run_initializer!` accepts exactly one object added by the current pure -addition event, mutates its canonical local status without adding a mid-step -output-history sample, and returns that canonical `Status`. A second call for -the same application/object pair is an error. The pair is reserved before the -model runs, so a failed initializer remains marked and cannot be retried after -an unknown partial mutation in the same lifecycle event. Existing, reparented, -foreign, or refresh-fallback targets are also errors. Use ordinary `Call` and -`run_call!` for trial execution or repeated controller-owned calls. +By default, a call from a plant searches `Self()`, the plant object itself. +Set `within=Subtree()` to find a new leaf below it. A model that creates +objects anywhere in the scene can instead use `within=SceneScope()`. + +### Scheduling and supported inputs + +Name the target application explicitly with `application=`. That application +must select objects with `on=Many(...)` and run at exactly the same interval +and phase as the creator. The phase is the offset at which the repeating +schedule starts. + +PlantSimEngine schedules the target application before the creator. For +models that need its new output in the same step, it schedules the relevant +calculation after the creator: + +| How the reading model runs | What must run after the creator | +|---|---| +| Directly from the simulation schedule | The reading model itself | +| Through hard calls | The scheduled controller at the top of its call chain | +| As another initializer target | That target's creator | + +If one creator calls two initializers and the second needs the first's +output, the creator must call them in that order inside its `run!` function. +PlantSimEngine cannot reorder statements inside your function. + +An initializer supports the global environment and writes the new object's +own status values. These are its **canonical outputs**: the current values +other models normally read, as opposed to saved output history. It may read +current inputs or use `PreviousTimeStep`, including inputs supplied to the +object by another application's `outputs_to`. + +The following restrictions apply to the target application: + +- It cannot make nested calls, write to other objects through `outputs_to`, + or produce outputs marked `stream_only`. +- Its input time policies are limited to `PreviousTimeStep`; it cannot use + `HoldLast`, `Interpolate`, `Integrate`, or `Aggregate`. +- It cannot also be owned by an ordinary manual call or by a second creator. +- No other application may write its canonical outputs, either locally or + through `outputs_to`. `Updates` does not relax this restriction: the + initializer runs inside its creator, outside the target's normal slot. + +### Reading initialized values + +Other models can read the new values directly later in the same timestep. +They cannot read them through a time policy: `run_initializer!` does not add +a sample to the output history partway through a step. PlantSimEngine +therefore rejects downstream `HoldLast`, `Interpolate`, `Integrate`, +`Aggregate`, and `PreviousTimeStep` connections to an initializer's output. +This restriction applies to those connections altogether, not just to the +first step. + +There is a distinction between an initializer **reading** a +`PreviousTimeStep` input, which is supported with a fallback for the new +object, and another model trying to read the initializer's **output** through +`PreviousTimeStep`, which is not supported. If you need output history, have +a separate scheduled application publish the value and read that +application's history on a later timestep. + +### Initialize each new object once + +`run_initializer!` runs only on the new object you pass to it. The declaration +identifies and checks the application in advance; it does not build a +collection of existing objects to run. + +The call changes the new object's `Status` and returns it, without saving an +extra history sample. It accepts exactly one object created during the +current addition event, and that event must contain only additions. Existing +objects, reparented objects, objects from another simulation, or objects that +require a full structural refresh first are rejected. + +You may initialize a given application/object pair only once. PlantSimEngine +marks the pair before running the model, so if the model fails after changing +some values, you cannot retry it in the same event. Use ordinary `Call` and +`run_call!` when you need trial calculations or repeated calls. ## Compiled plans and changing objects -The call declaration is compiled once with the scenario. Its call name, -applications, selector, multiplicity, ordering, and execution batches remain -fixed during the simulation. Ordinary calls therefore do not resolve selectors -or rebuild public target wrappers in their execution loop. - -Objects may still be created, removed, or reparented during growth. At the -structural refresh barrier, PlantSimEngine updates only the affected resolved -target buffers. Later applications in the same timestep see the new targets; -applications that already ran are not repeated. The following ordinary -timestep returns to the cached execution path. - -`call_targets(context, name; objects=newborn)` can build a targeted partial -view without crossing that barrier only while the pending lifecycle delta is a -pure addition. If the same event also removes or reparents an object, the -manual-call API performs the full binding and environment refresh before it -resolves the requested objects. This preserves current topology membership but -has the cost of a mid-kernel refresh and consumes the pending dirty state. -`run_initializer!` is stricter: it rejects such a mixed structural event. - -Explicit target cadence must match the caller. A target without an explicit -cadence inherits the caller's invocation timing. +When preparing the simulation, PlantSimEngine checks each call declaration +and prepares how it will execute. The call name, selected applications, +selector rules, `One`/`Many` requirement, execution order, and model groups +stay fixed. Ordinary calls reuse this preparation instead of searching for +objects again every time they run. + +The objects themselves may still be added, removed, or reparented during +growth. After the model making a structural change finishes, PlantSimEngine +updates the affected object lists. Applications later in the same timestep +use the updated lists; applications that already ran are not repeated. On +the next timestep, calls reuse the updated preparation. + +To call a newly created object before that update, +`call_targets(context, name; objects=newborn)` can select it directly if the +pending changes only add objects. If the same event also removes or +reparents an object, this call first updates all affected model connections +and environment lookups. This ensures that selection uses the current plant +structure, but the extra work takes place inside your model's `run!` +function, and those pending changes are then marked as processed. +`run_initializer!` is stricter: it rejects events that mix additions with +removal or reparenting. + +If the called model declares its own execution interval, it must match the +caller's. Otherwise it follows the caller's timing. diff --git a/docs/src/guides/multiscale/value_coupling.md b/docs/src/guides/multiscale/value_coupling.md index ff75ba093..7b5118e12 100644 --- a/docs/src/guides/multiscale/value_coupling.md +++ b/docs/src/guides/multiscale/value_coupling.md @@ -1,19 +1,31 @@ # Coupling Values Across Objects -- `One(...)` requires exactly one source. -- `OptionalOne(...)` accepts zero or one. -- `Many(...)` supplies a stable object-ID ordered carrier. - -Use `var=` to rename a source and `application=` to distinguish repeated -processes. Homogeneous many-source values use a `RefVector`; heterogeneous -values use an object-aware reference carrier. Inspect both through -`Diagnostics.input_carrier`, `Diagnostics.input_value`, and `Diagnostics.explain_bindings`, not internal fields. +To read values from other objects, describe which objects supply the input: + +- `One(...)` requires exactly one source object, such as the plant to which + a leaf belongs. +- `OptionalOne(...)` allows zero or one source object. +- `Many(...)` supplies a collection, such as the areas of all leaves on a + plant, ordered by object ID. + +Set `var=` when the source variable has a different name from the input. +Set `application=` when you need to specify which model application supplies +the value, for example when using the same process more than once. + +PlantSimEngine shares these values by reference: the receiving model reads +the current source values without copying them. A collection with the same +value type throughout uses `RefVector`; one with different types uses +`ObjectRefVector`. These collections are called **input carriers** in the +diagnostics. Use `Diagnostics.input_value` to read the values, +`Diagnostics.input_carrier` to inspect their container, and +`Diagnostics.explain_bindings` to see where they come from. ## Keep identities aligned with values -A model that only reduces or broadcasts over a `Many` input can keep using the -ordinary status field. When a model must associate a value with the object that -owns it, request the identity-aware view from the current `RunContext`: +If a model only needs to sum or multiply the values in a `Many` input, use +the input's `status` field as usual. If it also needs to know which leaf or +other object each value belongs to, call `bound_input` using `context`, the +information PlantSimEngine passes to each `run!` call: ```julia function PlantSimEngine.run!(model, status, environment, constants, context) @@ -28,24 +40,23 @@ function PlantSimEngine.run!(model, status, environment, constants, context) end ``` -`BoundMany` wraps the same live `RefVector` or heterogeneous carrier already -installed in `status.irradiance`; it does not copy values or identities. -Positions follow compiled `ObjectId` order and have no botanical meaning. -Identity lookup is unambiguous when written as -`irradiance[ObjectId(:leaf_12)]`; integer indexing remains positional. +The returned `BoundMany` gives access to both values and their object IDs, +without copying either. Its values are the same ones available through +`status.irradiance`. Their order follows `ObjectId`, not the position of an +organ on the plant. Use `irradiance[ObjectId(:leaf_12)]` to read a named leaf's +value, or an integer index to read a position in the collection. -Obtain the view during each model invocation. Lifecycle refresh keeps the -current view aligned when possible and may replace it after insertion, -removal, or reparenting, so model code must not cache a `BoundMany` across a -lifecycle barrier. +Call `bound_input` each time the model runs. PlantSimEngine may replace the +collection after an object is added, removed, or moved to a different parent, +so do not store it in your model for later calls. ## Publish one computation to many objects -Some models execute once on a scene or plant but compute one value per organ. -A light model is the typical example: the scene application owns the -calculation and cadence, while each leaf owns its local irradiance values. -Declare that relationship with `outputs_to`, then publish the solver result by -object identity: +Some models run once for a scene or plant but compute one value per organ. +For example, a light model may calculate illumination for the whole scene +and then store each leaf's irradiance on that leaf. Declare these +destinations with `outputs_to`, and use object IDs to assign each result to +the right leaf: ```julia PlantSimEngine.@process "scene light" verbose = false @@ -75,10 +86,11 @@ function PlantSimEngine.run!( end ``` -Here `solve` is an adapter around the scene solver. It returns any -Tables.jl-compatible value with an `object_id` column and the declared result -columns, for example `incident_par` and `absorbed_par`. Rows may arrive in any -order because `assign_outputs!` maps them to destinations by `ObjectId`. +Here `solve` calls your scene light calculation and returns its results as a +table supported by Tables.jl, such as a `DataFrame`. The table needs an +`object_id` column and one column for each declared output, for example +`incident_par` and `absorbed_par`. Rows may be in any order: +`assign_outputs!` uses `ObjectId` to put each result on the right leaf. Declare the destinations on the scene application: @@ -99,12 +111,12 @@ light_application = ModelSpec( ) ``` -Inside the kernel, `targets.columns.incident_par` and -`targets.columns.absorbed_par` are the live destination carriers. -`object_ids(targets)` is the aligned, read-only identity view. Direct -positional writes are appropriate only when the producing algorithm is already -using that exact identity order; identified external results should go through -`assign_outputs!`. +Inside `run!`, `targets.columns.incident_par` and +`targets.columns.absorbed_par` give direct access to the selected leaves' +values. `object_ids(targets)` lists their IDs in the same order; this list +cannot be modified. Write directly by position only if your calculation +already uses that exact order. For a separate result table with its own IDs, +use `assign_outputs!` to match the rows to leaves. ## Consume those values normally @@ -142,13 +154,13 @@ applications = ( ) ``` -The compiler knows that `:scene_light` owns `:absorbed_par` on each selected -leaf. It binds the leaf input and schedules the scene writer before the leaf -consumer even though the consumer appears first in the tuple. No per-leaf copy -model, `from_status=true`, or manual `after=:scene_light` declaration is -needed. +PlantSimEngine knows that `:scene_light` supplies `:absorbed_par` for each +selected leaf and that `:leaf_assimilation` needs it. It connects the two and +runs the light calculation first, even though the assimilation model appears +first in the tuple. You do not need an extra model to copy the light values +or an `after=:scene_light` instruction to set their order. -## Assignment contract +## Rules for assigning results `assign_outputs!` supports two public forms: @@ -157,39 +169,43 @@ assign_outputs!(targets, result_table; id=:object_id) assign_outputs!(targets, result_ids, result_columns) ``` -The first accepts any Tables.jl-compatible column or row table. The second -accepts an `AbstractVector` of IDs and a `NamedTuple` of columns, avoiding the -table adapter on a stable columnar path. Both forms use the same rules: +The first accepts any row or column table supported by Tables.jl. The second +takes an `AbstractVector` of IDs and a `NamedTuple` of value columns, which +is useful when your solver already returns separate arrays. Both forms use +the same rules: | Result content | Behavior | |---|---| | One row for every current destination | Required | -| Unknown, duplicate, extra, or missing IDs | Rejected before mutation | +| Unknown, duplicate, extra, or missing IDs | Rejected before any destination value changes | | Every variable declared by `OutputTo` | Required | | Additional columns such as solver metadata | Ignored | -| Source columns overlapping destination storage | Rejected, except exact-order self-assignment of the same column | +| Result columns sharing memory with destination columns | Rejected, except assigning a column to itself in exactly the same order | -Only `coverage=:exact` is supported. A filtered, abscised, or non-geometrized -organ must therefore be handled deliberately by the scene adapter or excluded -by the destination selector; PlantSimEngine never silently retains an old -value or substitutes zero for a missing result. +Only `coverage=:exact` is supported: you must supply one result for every +selected object. If the light solver skips an organ because it has no +geometry or has been removed from its scene, decide how to handle it. Either +return an appropriate value or exclude that organ from the destination +selector. PlantSimEngine will report a missing result instead of keeping an +old value or substituting zero. ## Reuse stable columns efficiently -PlantSimEngine caches the result-row permutation by the identity of the ID -column. Reusing the same ID vector promises that its IDs and order remain -unchanged; mutate only the result value columns in place. Replace the ID vector -when membership or ordering changes. A lifecycle refresh invalidates this -cache automatically, and the next invocation rebuilds it against the refreshed -destinations. - -Homogeneous destination values use typed `RefVector` columns and the stable -exact-order path can run without allocations after compilation. If selected -statuses hold different concrete value types, PlantSimEngine falls back to an -`ObjectRefVector` and converts against each destination reference. The public -API is identical, but the homogeneous representation is the performance path -to prefer for large per-organ assignments. - -Like `BoundMany`, an `OutputTargets` view belongs to the current invocation and -lifecycle generation. Obtain it from `RunContext` each time rather than storing -it in the model. +PlantSimEngine remembers how the result rows match the destination objects. +You can reuse the same ID vector to avoid repeating this work, but its IDs +and their order must remain unchanged. Update only the value columns. If +the objects or their order change, provide a new ID vector. After an object +is added, removed, or reparented, PlantSimEngine automatically rebuilds the +match on the next call. + +When all destination values have the same concrete Julia type, PlantSimEngine +uses `RefVector` columns. With a stable ID order that already matches the +destinations, assignments can run without new memory allocations after +compilation. If the destinations hold different types, PlantSimEngine uses +`ObjectRefVector` and converts each value to its destination type. Both use +the same API; keeping types consistent is preferable when assigning results +to many organs. + +Call `output_targets` each time your model runs, just as with `bound_input`. +Do not store the returned `OutputTargets` in the model: the selected objects +may change as the plant grows. diff --git a/docs/src/guides/multiscale/visualizing_structure.md b/docs/src/guides/multiscale/visualizing_structure.md index abb2acf14..9f90bbd67 100644 --- a/docs/src/guides/multiscale/visualizing_structure.md +++ b/docs/src/guides/multiscale/visualizing_structure.md @@ -1,6 +1,64 @@ -# Visualizing Composite model Structure +# Visualize Plant Structure -Use `Diagnostics.explain_objects`, `Diagnostics.explain_scopes`, and `Diagnostics.explain_instances` to -obtain stable rows for plotting. Draw nodes by object ID and edges from parent -to child; color by scale, species, or instance. Keep simulation visualization -outside model kernels so model code remains independent of topology packages. +A structure diagram helps check which organs belong to which plant. A model +dependency diagram answers a different question: which calculation supplies +which input. Use the [graph viewer](../graph_visualizer_editor.md) for model +dependencies, and object parent links for plant structure. + +## Draw the parent links + +This small example needs `DataFrames` and `CairoMakie` in your project. It +draws one plant with two leaves. `Diagnostics.explain_objects` lists the +objects and their parents so we can draw the connections: + +```@example structure_plot +using PlantSimEngine, DataFrames, CairoMakie + +model = CompositeModel( + Object(:plant; scale=:Plant, kind=:plant), + Object(:leaf_1; scale=:Leaf, parent=:plant), + Object(:leaf_2; scale=:Leaf, parent=:plant), +) +rows = Diagnostics.explain_objects(model) +select(DataFrame(rows), :id, :scale, :parent) +``` + +The coordinates below are chosen for a readable diagram. They are not organ +positions or a reconstructed 3D plant. + +```@example structure_plot +positions = Dict(:plant => (0.0, 0.0), + :leaf_1 => (-1.0, 1.0), :leaf_2 => (1.0, 1.0)) +fig = Figure(size=(620, 320)) +ax = Axis(fig[1, 1]; title="One plant, two leaves", aspect=DataAspect()) + +for row in rows + x, y = positions[row.id] + if !isnothing(row.parent) + px, py = positions[row.parent] + lines!(ax, [px, x], [py, y]; color=:gray55, linewidth=2) + end + color = row.scale == :Plant ? :sienna : :seagreen + scatter!(ax, [x], [y]; color, markersize=22) + text!(ax, x, y; text=string(row.id), offset=(0, 16), align=(:center, :bottom)) +end +limits!(ax, -1.6, 1.6, -0.3, 1.6) +hidedecorations!(ax) +hidespines!(ax) +save("plant-structure.svg", fig) # hide +nothing # hide +``` + +![](plant-structure.svg) + +For a larger structure, choose a tree-layout algorithm or positions from your +geometry data. Keep object IDs as the link between results, geometry, and +labels. After growth or pruning, call `Diagnostics.explain_objects(model)` +again to draw the current structure. Saved simulation results still include +the history of removed organs. + +When using plant templates, `Diagnostics.explain_instances(model)` identifies +the object at the top of each plant's structure. Use +`Diagnostics.explain_scopes(model)` to check the search areas used to select +objects. The drawing code is separate from the process models, so you can +run the same simulation with or without a visualization. diff --git a/docs/src/guides/time/advanced_time_environment.md b/docs/src/guides/time/advanced_time_environment.md index 1b1087749..cb9a4ac12 100644 --- a/docs/src/guides/time/advanced_time_environment.md +++ b/docs/src/guides/time/advanced_time_environment.md @@ -1,17 +1,81 @@ -# Advanced Time And Environment Configuration - -Disambiguate a producer with an explicit selector containing `application`, -`var`, and `within`. Put temporal `policy` and `window` on that input. Configure -environment source renaming and reducers with `Environment`; scenario values -override model-level `environment_hint` entries. - -Use `Diagnostics.explain_bindings`, `Diagnostics.explain_environment_bindings`, and -`Diagnostics.explain_schedule` to inspect the final source, reducer, window, cadence, and -clock origin. All periods that require seconds must be fixed `Dates` periods; -`Month(1)` is intentionally rejected. - -The simulation advances on a fixed base step. `ModelSpec(...; every=...)` -requires a positive integer multiple of that step, including for subsecond -periods. Choose a finer common base step when cadences do not fit: hourly and -90-minute applications need a base step of 30 minutes or finer. The scheduler -does not insert intermediate or adaptive steps automatically. +# Choose Compatible Time Steps + +Use this page when a simulation rejects how often you want a model to run, +or when several models need different time steps. To choose how those models +share values between updates, start with +[Different model cadences](../../journeys/users/cadences.md). + +## Find a common base step + +The simulation advances by a fixed interval, called the **base step**. Set it +with the environment's `duration`. A model's `every` value must be a positive +whole number of base steps. PlantSimEngine does not add smaller steps for you. + +| Model cadences | A suitable base step | +|:--|:--| +| Every hour and every day | One hour | +| Every hour and every 90 minutes | 30 minutes | +| Every 250 ms and every second | 250 ms | + +A smaller step may also work, but increases the number of simulation steps. +Choose one that suits the equations and your weather data. If you need values +between measurements, choose how to estimate them. If you need less frequent +values, choose how to combine the measurements, for example by averaging. +Changing `duration` alone does not calculate these values. + +## Example: hourly and 90-minute sampling + +Two simple models read temperature at different intervals. Both run at the +start of the simulation, then one runs every hour and the other every +90 minutes: + +```@example compatible_steps +using PlantSimEngine, Dates, DataFrames +using PlantSimEngine.Examples + +model = CompositeModel( + Object(:hourly; scale=:Sensor, name=:hourly), + Object(:ninety_minutes; scale=:Sensor, name=:ninety_minutes); + applications=( + ModelSpec(ToyEnvironmentReaderModel(); name=:hourly, + on=One(name=:hourly), every=Hour(1)), + ModelSpec(ToyEnvironmentReaderModel(); name=:ninety_minutes, + on=One(name=:ninety_minutes), every=Minute(90)), + ), + environment=(T=20.0, duration=Minute(30)), +) +simulation = run!(model; steps=7, outputs=:all) +rows = collect_outputs(simulation; sink=DataFrame) +combine(groupby(rows, :application_id), nrow => :samples) +``` + +The seven time points cover 0 to 3 hours. The hourly reader records four +results, and the other records three. Both record their first result at +time zero. + +```@example compatible_steps +@assert count(==(:hourly), rows.application_id) == 4 # hide +@assert count(==(:ninety_minutes), rows.application_id) == 3 # hide +nothing # hide +``` + +## Check when models run and where inputs come from + +Use these tables to check the configuration: + +- `Diagnostics.explain_schedule(model)` shows when each model starts and how + often it runs. +- `Diagnostics.explain_bindings(model)` shows which model supplies each input + and how earlier values are used, including the rule and time window. +- `Diagnostics.explain_environment_bindings(model)` shows the weather or + spatial data each model reads and how values are combined over time. + +Setting `every` replaces the model's default cadence from `timespec`. If you +leave the cadence to the environment's base step, the model can check it with +`timestep_hint`. If you set `every` yourself, you must check that the equations +support that interval. + +Fixed periods such as `Day(1)` are supported. Calendar months vary in length, +so `Month(1)` is rejected. A time window looks back over its specified +duration. For example, `Day(1)` does not automatically mean the preceding +midnight-to-midnight day. diff --git a/docs/src/guides/time/hourly_daily_weekly.md b/docs/src/guides/time/hourly_daily_weekly.md index 775241252..555cc2e95 100644 --- a/docs/src/guides/time/hourly_daily_weekly.md +++ b/docs/src/guides/time/hourly_daily_weekly.md @@ -1,66 +1,119 @@ # Hourly, Daily, And Weekly Models -An hourly leaf application publishes rates. A daily plant application -integrates them over a day, and a weekly application consumes the daily -amounts. Each application remains a normal `ModelSpec`; only its `every` -value and input policy differ. - -Runtime dependency streams are retained because consumers need them. Output -resampling is independent: create named `OutputRequest`s for hourly, daily, -and weekly analysis, then compare `Diagnostics.explain_schedule` sample counts with rows -from `collect_outputs`. - -The following reduced example checks the important physical contract: two -leaf rates are integrated independently for 24 hourly samples and then summed -on their plant. Rates are per second, so the expected amount is -`(1 + 2) × 24 × 3600 = 259200`. The default `Integrate()` sums samples without -duration weighting; the explicit reducer below supplies the physical integral. +Compare daily and weekly water uptake from the same hourly leaf rates. The +rates below are deliberately constant teaching values: 1 and 2 mg of water +per leaf per second. They show how to calculate totals over different time +intervals; they do not predict plant water demand. + +To calculate each total, multiply the hourly rates by the duration they +represent, then add the two leaves' amounts over a day or a week. Both totals +use the hourly values directly. This avoids counting the same water twice +by adding daily totals whose periods might overlap. + +## Load the two equations + +The reusable [teaching models](teaching_models.jl) return a supplied rate and +add supplied amounts. Their definitions are included at the end of this page; +load them now to configure this simulation. + +```@example hourly-daily +using Dates, DataFrames, PlantSimEngine +include(joinpath(pkgdir(PlantSimEngine), "docs", "src", "guides", "time", "teaching_models.jl")) +using .TeachingTimeModels +``` + +## Choose update intervals and time windows + +`every` says how often a model runs; `window` says how far back it looks for +input values. Hourly, daily and weekly durations all fit an hourly base step. +The function passed to `Integrate` multiplies each rate by the duration it +represents, in seconds. This converts mg s⁻¹ into mg before the plant adds +the leaf amounts. ```@example hourly-daily -using Dates -using PlantSimEngine - -PlantSimEngine.@process "docs_hourly_flux" verbose = false -PlantSimEngine.@process "docs_daily_total" verbose = false -struct DocsHourlyFlux <: AbstractDocs_Hourly_FluxModel end -struct DocsDailyTotal <: AbstractDocs_Daily_TotalModel end -PlantSimEngine.inputs_(::DocsHourlyFlux) = (rate=Required(Float64),) -PlantSimEngine.outputs_(::DocsHourlyFlux) = (flux=0.0,) -PlantSimEngine.run!(::DocsHourlyFlux, status, environment, constants, context) = - (status.flux = status.rate) -PlantSimEngine.inputs_(::DocsDailyTotal) = (fluxes=Required(Vector{Float64}),) -PlantSimEngine.outputs_(::DocsDailyTotal) = (total=0.0,) -PlantSimEngine.run!(::DocsDailyTotal, status, environment, constants, context) = - (status.total = sum(status.fluxes)) +integrate_rate = Integrate((values, durations_seconds) -> sum(values .* durations_seconds)) model = CompositeModel( Object(:plant; scale=:Plant), - Object(:leaf_1; scale=:Leaf, parent=:plant, status=Status(rate=1.0)), - Object(:leaf_2; scale=:Leaf, parent=:plant, status=Status(rate=2.0)); + Object(:leaf_1; scale=:Leaf, parent=:plant, status=Status(rate_mg_s=1.0)), + Object(:leaf_2; scale=:Leaf, parent=:plant, status=Status(rate_mg_s=2.0)); applications=( - ModelSpec(DocsHourlyFlux(); name=:hourly, on=Many(scale=:Leaf), every=Hour(1)), + ModelSpec(HourlyWaterRate(); name=:hourly, on=Many(scale=:Leaf), every=Hour(1)), ModelSpec( - DocsDailyTotal(); - name=:daily, - on=One(scale=:Plant), - inputs=( - :fluxes => Many( - scale=:Leaf, within=Subtree(), application=:hourly, var=:flux, - policy=Integrate((values, durations_seconds) -> sum(values .* durations_seconds)), window=Day(1), - ), - ), + SumWaterAmounts(); name=:daily, on=One(scale=:Plant), + inputs=(amounts_mg=Many( + scale=:Leaf, within=Subtree(), application=:hourly, + var=:water_rate_mg_s, policy=integrate_rate, window=Day(1), + ),), every=Day(1), ), + ModelSpec( + WeeklyWaterAmount(); name=:weekly, on=One(scale=:Plant), + inputs=(amounts_mg=Many( + scale=:Leaf, within=Subtree(), application=:hourly, + var=:water_rate_mg_s, policy=integrate_rate, window=Week(1), + ),), + every=Week(1), + ), ), - environment=[(duration=Hour(1),) for _ in 1:25], + environment=[(duration=Hour(1),) for _ in 1:169], ) -simulation = run!(model; steps=25) -@assert only(object.status.total for object in model_objects(model) - if object.id == ObjectId(:plant)) == 259200.0 + +simulation = run!(model; steps=169, outputs=:all) +rows = collect_outputs(simulation; sink=DataFrame) +totals = rows[in.(rows.application_id, Ref((:daily, :weekly))), + [:timestep, :application_id, :variable, :value]] +totals ``` -A weekly consumer uses the same pattern with `every=Week(1)` and a -seven-day window over the daily application. Sum daily amounts with -`Integrate()`; integrate rates per second with the duration-aware reducer -shown above. Choose `Aggregate(reducer)` for states or observations whose physical meaning -is a mean, minimum, maximum, or custom statistic. +Both totals are calculated at step 1, when only one hour of values is +available: `(1 + 2) × 3600 = 10800 mg`. This first result does not represent +a complete day or week. The daily total is calculated again at steps 25, 49, +and so on; the weekly total is calculated again at step 169. + +```@example hourly-daily +first_daily = only(totals[(totals.application_id .== :daily) .& (totals.timestep .== 1), :value]) +full_day = only(totals[(totals.application_id .== :daily) .& (totals.timestep .== 25), :value]) +full_week = only(totals[(totals.application_id .== :weekly) .& (totals.timestep .== 169), :value]) +@assert first_daily == 3 * 3600 +@assert full_day == 3 * 24 * 3600 +@assert full_week == 3 * 7 * 24 * 3600 +(startup_mg=first_daily, daily_mg=full_day, weekly_mg=full_week) +``` + +Each window looks back over its specified duration. It does not automatically +start at midnight or at the beginning of a calendar week. Each model's cadence +must be a whole number of base steps; choose a smaller common step if needed. +Calendar months and timesteps that change during a run are not supported. + +`Integrate()` without a function only adds values. Use it when the values +already represent amounts, and check that the selected window includes each +intended amount once. For rates, multiply by duration as above. Use +`Aggregate(reducer)` to calculate a mean or another statistic, supplying your +calculation as the `reducer` function. + +## Scientific contracts and outputs + +These teaching models do not declare `VariableContract`s, which describe a +variable's units and physical meaning. The rules for combining values over +time do not change these declarations. If your models declare a rate contract +on one side and an amount contract on the other, connect them through a small +model that performs the conversion and declares both meanings. See +[Coupling models](../coupling.md). + +PlantSimEngine keeps the earlier values needed for each input window. Choose +separately which results to save for your own analysis: see +[Collecting And Plotting Outputs](../data/outputs_plotting.md). Check the +schedule to find how many daily or weekly results to expect, including the +first partial result. + +## Teaching model source + +These simple equations are shared with the [cadence tutorial](../../journeys/users/cadences.md). +They copy each leaf's supplied rate and add the converted leaf amounts. The +weekly model uses a different output name so the plant can store both totals. + +```@eval +using Markdown, PlantSimEngine +Markdown.MD([Markdown.Code("julia", read(joinpath(pkgdir(PlantSimEngine), "docs", "src", "guides", "time", "teaching_models.jl"), String))]) +``` diff --git a/docs/src/guides/time/multirate_concepts.md b/docs/src/guides/time/multirate_concepts.md deleted file mode 100644 index 40f5fe700..000000000 --- a/docs/src/guides/time/multirate_concepts.md +++ /dev/null @@ -1,13 +0,0 @@ -# Understanding Model Cadence - -`ModelSpec(...; every=Dates.Period)` sets application cadence. Without -`every`, an application uses `timespec(model)` when non-default and otherwise -the environment base step. `timestep_hint` validates a scientifically -acceptable range; it does not silently change cadence. - -Temporal input policies have different physical meanings: `HoldLast` samples -the latest state, `Aggregate` reduces observations, and `Integrate()` sums -values over a window. To integrate rates per second, use a duration-aware -reducer: `Integrate((values, durations_seconds) -> sum(values .* durations_seconds))`. `PreviousTimeStep` deliberately breaks a same-step -cycle. Windows are rolling fixed-duration windows. Civil-day or -previous-complete-calendar-period alignment is not a supported public feature. diff --git a/docs/src/guides/time/teaching_models.jl b/docs/src/guides/time/teaching_models.jl new file mode 100644 index 000000000..abbd73513 --- /dev/null +++ b/docs/src/guides/time/teaching_models.jl @@ -0,0 +1,48 @@ +module TeachingTimeModels + +using PlantSimEngine + +export HourlyWaterRate, SumWaterAmounts, WeeklyWaterAmount + +PlantSimEngine.@process "teaching_water_rate" verbose=false +PlantSimEngine.@process "teaching_water_amount" verbose=false +PlantSimEngine.@process "teaching_weekly_water_amount" verbose=false + +"""Publish a supplied constant uptake rate, in mg of water per leaf per second.""" +struct HourlyWaterRate <: AbstractTeaching_Water_RateModel end + +PlantSimEngine.inputs_(::HourlyWaterRate) = (rate_mg_s=Required(Real),) +PlantSimEngine.outputs_(::HourlyWaterRate) = (water_rate_mg_s=0.0,) + +function PlantSimEngine.run!(::HourlyWaterRate, status, environment, constants, context) + status.water_rate_mg_s = status.rate_mg_s + return nothing +end + +"""Add already converted water amounts, in mg, from the selected sources.""" +struct SumWaterAmounts <: AbstractTeaching_Water_AmountModel end + +PlantSimEngine.inputs_(::SumWaterAmounts) = (amounts_mg=Required(AbstractVector{<:Real}),) +PlantSimEngine.outputs_(::SumWaterAmounts) = (water_amount_mg=0.0,) + +function PlantSimEngine.run!(::SumWaterAmounts, status, environment, constants, context) + status.water_amount_mg = sum(status.amounts_mg) + return nothing +end + +"""Keep a separately named weekly total, in mg of water per plant.""" +struct WeeklyWaterAmount <: AbstractTeaching_Weekly_Water_AmountModel end + +PlantSimEngine.inputs_(::WeeklyWaterAmount) = (amounts_mg=Required(AbstractVector{<:Real}),) +PlantSimEngine.outputs_(::WeeklyWaterAmount) = (weekly_water_mg=0.0,) + +function PlantSimEngine.run!(::WeeklyWaterAmount, status, environment, constants, context) + status.weekly_water_mg = sum(status.amounts_mg) + return nothing +end + +# These constant-rate teaching models isolate temporal sampling. Their variable +# contracts are deliberately undeclared: the pages explain the explicit adapter +# required when a contracted rate is converted to a contracted amount. + +end # module diff --git a/docs/src/index.md b/docs/src/index.md index 9e747f6d1..000860d22 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -2,124 +2,212 @@ CurrentModule = PlantSimEngine ``` -# PlantSimEngine - -[![Build Status](https://github.com/VirtualPlantLab/PlantSimEngine.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/VirtualPlantLab/PlantSimEngine.jl/actions/workflows/CI.yml?query=branch%3Amain) -[![Coverage](https://codecov.io/gh/VirtualPlantLab/PlantSimEngine.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/VirtualPlantLab/PlantSimEngine.jl) -[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) -[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl) -[![DOI](https://zenodo.org/badge/571659510.svg)](https://zenodo.org/badge/latestdoi/571659510) -[![JOSS](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09/status.svg)](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09) - -```@contents -Pages = ["index.md"] -Depth = 4 -``` +```@setup home +using PlantSimEngine, PlantMeteo, Dates, DataFrames, CairoMakie +using PlantSimEngine.Examples -## Overview - -`PlantSimEngine` is a Julia framework for building soil-plant-atmosphere -simulations from small process models. A modeler writes reusable kernels with -`inputs_`, `outputs_`, optional dependency traits, and `run!`. A simulation -author then assembles those kernels on objects in a `CompositeModel`. - -The public scenario API has one application-construction form: - -```julia -ModelSpec( - model; - name=:application, - on=Many(scale=:Leaf), - inputs=(...), - calls=(...), - every=Dates.Hour(1), - environment=Environment(...), - output_routing=(...), - updates=Updates(...), +# The bundled file contains daily radiation totals; Beer expects mean fluxes. +meteo_day = read_weather( + joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), + :Ri_SW_f => (x -> x .* 1e6 ./ 86_400) => :Ri_SW_f, + :Ri_PAR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_PAR_f, + :Ri_NIR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_NIR_f; + duration=Dates.Day, ) +canopy = CompositeModel( + ToyDegreeDaysCumulModel(), ToyLAIModel(), Beer(0.6); + environment=meteo_day, +) +canopy_sim = run!(canopy; steps=length(meteo_day), outputs=:all) +canopy_out = collect_outputs(canopy_sim; sink=DataFrame) +lai = canopy_out[canopy_out.variable .== :LAI, :value] +appfd = canopy_out[canopy_out.variable .== :aPPFD, :value] +tt_cu = canopy_out[canopy_out.variable .== :TT_cu, :value] +seconds_per_day = Dates.value.(Second.(meteo_day[:duration])) +absorbed_par_day = appfd .* seconds_per_day ./ 1e6 + +canopy_figure = Figure(size=(720, 490), fontsize=16) +ax_lai = Axis(canopy_figure[1, 1], ylabel="LAI (m² m⁻²)") +lines!(ax_lai, tt_cu, lai, color="#156f64", linewidth=2.5) +ax_par = Axis(canopy_figure[2, 1], + xlabel="Growing degree days since sowing (°C d)", + ylabel="Absorbed PAR\n(mol m⁻² d⁻¹)", +) +lines!(ax_par, tt_cu, absorbed_par_day, color="#b46237", linewidth=2) +save("home-canopy.svg", canopy_figure) + +include(joinpath(pkgdir(PlantSimEngine), "skills", "plantsimengine", "assets", "alternative-model.jl")) +using .AlternativeModelExample +linear = LinearCarbonGain(0.2) +saturating = SaturatingCarbonGain(10.0, 5.0) +@assert Authoring.compare_models(linear, saturating).override_compatible + +function carbon_response(process_model, light) + model = CompositeModel(process_model; + id=:plant, scale=:Plant, kind=:plant, + status=(absorbed_par=light,), + ) + final_state(run!(model)).carbon_gain +end +light_values = collect(0.0:1.0:50.0) +linear_gain = [carbon_response(linear, light) for light in light_values] +saturating_gain = [carbon_response(saturating, light) for light in light_values] +@assert all(isfinite, linear_gain) && all(isfinite, saturating_gain) +@assert first(linear_gain) == first(saturating_gain) == 0.0 +comparison_figure = Figure(size=(760, 400), fontsize=16) +ax_response = Axis(comparison_figure[1, 1], + xlabel="Absorbed PAR (mol photons plant⁻¹ d⁻¹)", + ylabel="Carbon gain (g C plant⁻¹ d⁻¹)", +) +lines!(ax_response, light_values, linear_gain; + label="Linear response", color="#156f64", linewidth=3) +lines!(ax_response, light_values, saturating_gain; + label="Saturating response", color="#b46237", linewidth=3) +axislegend(ax_response; position=:lt, framevisible=false) +save("home-model-comparison.svg", comparison_figure) ``` -### Models And Applications - -A model is a reusable implementation of a process. A model application is one -configured use of that model in a simulation: it gives the use a name, selects its -target objects, and configures its inputs, calls, timestep, and environment. - -| Concept | Meaning | -|:--|:--| -| Process | The biological or physical operation, such as light interception | -| Model | An implementation of that process, such as `Beer` | -| Application | One configured use of a model in a `CompositeModel` | -| Target | An object on which that application executes | - -One application can target many objects. The same model can also be used in -several named applications with different parameters, selectors, or cadence. -During compilation, PlantSimEngine resolves each application into its concrete -`(application, object)` executions. - -This means the same model can be reused on one object, many leaves, several -plant species, a shared soil object, or a scene energy-balance solver -without changing the model implementation. - -## Why PlantSimEngine? - -- **Modular models**: each process model can be developed, tested, calibrated, - and replaced independently. -- **Explicit coupling**: `ModelSpec(...; inputs=...)` declares value - dependencies, while `calls=...` gives iterative parent solvers manual - control over hard model calls. -- **Object-based multiscale composite models**: scales are labels on objects, so a plant - can be described as plants, axes, internodes, leaves, roots, voxels, or any - topology the model requires. -- **Multirate execution**: use `every=Dates.Hour(1)` or - `every=Dates.Day(1)`, with temporal policies such as `Integrate()` or - `HoldLast()` in the same model. -- **Automatic environment binding**: global weather and spatial microclimate - backends are bound through `Environment(...)`, model `environment_inputs_`, and - explicit accepted-state commits with `commit_environment!`. -- **Performance-oriented internals**: selectors and bindings are compiled - before the timestep loop, same-rate inputs use references when possible, and - homogeneous object batches are specialized. -- **Generic values**: status, model parameters, meteorology, and outputs can - carry units, automatic-differentiation values, uncertainty wrappers, or other - compatible Julia types. - -## Installation - -To install the package, enter Julia package mode by pressing `]` in the REPL, -then run: - -```julia -add PlantSimEngine +# From process models to plant simulations + +PlantSimEngine connects and runs models of plant processes such as light +interception, photosynthesis and growth. You choose the equations, using +[existing model packages](#Scientific-models-and-further-reading) or writing +your own. PlantSimEngine manages their +connections, execution order, time steps and simulation outputs in Julia. + +You can represent a whole crop canopy, individual plants, or their organs. +**You choose the level of detail; 3D geometry is optional.** Small, testable +models and clear reports on their connections also support +[AI-assisted model development](agent_skill.md). + +For scientific equations, explore packages such as +[PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl), for plant +biophysical processes, and [XPalm](https://github.com/PalmStudio/XPalm.jl), for +oil-palm growth. Their documentation describes the models, assumptions and +supported package versions. + +## See what you can build + +These examples show two ways to represent a plant system. The canopy curves +are calculated when this documentation is built, using teaching models and a +full year of weather. The 3D image illustrates an explicit organ structure. + +```@raw html +
+
+ Teaching simulation: leaf area index rises and falls over the season, while absorbed light responds to both canopy development and weather. +
A crop canopy over a season. Connect thermal time, leaf area index (LAI) and light interception without describing individual leaves. Couple models for a canopy →
+
+
+ Static illustration of a plant with a stem, branches and individual leaves in three dimensions. +
A plant described by its organs. Apply models to leaves and combine their outputs at plant level. This is an illustrative 3D structure, not the output of the canopy example. Connect organ and plant models →
+
+
``` -Use it from Julia with: +For plant–environment interactions, the +[MAESPA-style example](journeys/users/maespa_synthesis.md) combines two species, +leaf exchanges, soil water and daily growth. It is an advanced teaching +example of coupling these processes, rather than a validated reproduction of +MAESPA. + +## Compare a different hypothesis + +What happens if carbon gain stops increasing in proportion to absorbed light? +Here, the same small simulation is run with a linear response and then a +saturating response. Only the carbon-gain model changes. Both models declare +the same inputs, outputs and units, so PlantSimEngine can check whether +one can replace the other. + +![Two teaching models predict different carbon gains from the same absorbed light: a linear response and a saturating response.](home-model-comparison.svg) + +The coefficients are illustrative. These curves demonstrate how to compare +model formulations; they are not calibrated predictions for a crop or species. +The models come from the [examples supplied for model authors and AI agents](agent_skill.md). +Follow the [model replacement guide](step_by_step/model_switching.md) to try +alternatives and check whether their inputs require different connections. + +## Build and change simulations with confidence + +- **Keep equations separate from the scenario.** Write a process model once, + then choose which plants or organs use it, its parameters and its connections. + [Reuse models across several plants](journeys/users/several_plants.md). +- **Combine different time steps.** Connect hourly exchanges and daily growth, + stating when values should be accumulated, averaged or held between updates. + [Connect hourly and daily models](journeys/users/cadences.md). +- **Follow changes in plant structure.** Add or remove organs during a + simulation and let PlantSimEngine update the affected model connections. + [Model a changing structure](journeys/users/structure_changes.md). +- **Inspect what is connected.** Find the source of an input, inspect the + execution order and diagnose missing or ambiguous connections. + [Explore a model graph](guides/graph_visualizer_editor.md). +- **Control interactions that need iteration.** For example, a canopy solver + can repeatedly call leaf models until an energy balance converges, then + record the accepted result. [Control iterative calculations](guides/multiscale/manual_calls.md). +- **Run repeated simulations efficiently.** PlantSimEngine prepares model + connections before the time loop and reuses them during execution. This + avoids resolving those connections again at every time step, including when + models run on many organs. + [Read about the design and performance evidence](introduction/why_plantsimengine.md). + +## Work with an AI coding agent + +An **AI coding agent** is software that can read and edit code and run tests +with your development tools. PlantSimEngine is designed to support this way +of working: models expose their inputs and outputs, and can declare units and +other scientific conventions. Tools report model compatibility, missing inputs +and simulation connections. A versioned +**agent skill** provides instructions and tested examples for the installed +package. These give an agent concrete information to implement, inspect and +check a proposed model or coupling. You guide the scientific assumptions and +validate the equations, parameters and results. + +[Set up an agent for PlantSimEngine](agent_skill.md), or use the same +[model descriptions and checks](API/model_catalog.md) directly from Julia. + +## Choose your starting point + +| Your next step | What you will do | +|:--|:--| +| [Couple existing models](journeys/users/one_object.md) | Start with three teaching models, supply weather, run a simulation and read its results. | +| [Write a process model](journeys/modelers/basic_model.md) | Implement an equation, declare its inputs and outputs, test it and use it in a simulation. | +| [Understand how the pieces fit together](journeys/users/mental_model.md) | Learn the few ideas shared by both workflows, before reading detailed configuration. | -```julia -using PlantSimEngine -``` +The examples introduce Julia as it is needed. If you are new to the language, +start with [installation](prerequisites/installing_plantsimengine.md) and +[Julia basics](prerequisites/julia_basics.md). -## Quickstart: One CompositeModel Object +## A small simulation in Julia -This example runs three existing toy models on one object: +The canopy example above connects three existing models: temperature drives +thermal time, thermal time drives LAI, and LAI and radiation determine absorbed +photosynthetically active radiation (PAR). The phenology and LAI models are +teaching examples, not a calibrated crop model. -1. `ToyDegreeDaysCumulModel` computes daily thermal time. -2. `ToyLAIModel` consumes cumulative thermal time and computes LAI. -3. `Beer` consumes LAI and meteorology to compute absorbed PAR. +First follow the [installation instructions](prerequisites/installing_plantsimengine.md) +to get the package version used by this manual and the tutorial dependencies. -The model kernels are unchanged; the model application layer says where they -run. Since no `every` is specified, these applications use the daily -cadence of `meteo_day`. +Read the weather supplied with PlantSimEngine. This file stores daily radiation +totals in MJ m⁻² d⁻¹; the three conversions below give the mean fluxes in +W m⁻² required by the light-interception model. -```@example readme +```@example home using PlantSimEngine, PlantMeteo, Dates, DataFrames using PlantSimEngine.Examples meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); + joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), + :Ri_SW_f => (x -> x .* 1e6 ./ 86_400) => :Ri_SW_f, + :Ri_PAR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_PAR_f, + :Ri_NIR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_NIR_f; duration=Dates.Day, ) +nothing # hide +``` + +Choose the models and run the full weather year: +```@example home model = CompositeModel( ToyDegreeDaysCumulModel(), ToyLAIModel(), @@ -127,169 +215,39 @@ model = CompositeModel( environment=meteo_day, ) -sim = run!(model; steps=30, outputs=:all) -out = collect_outputs(sim; sink=DataFrame) -first(out, 6) +simulation = run!(model; steps=length(meteo_day), outputs=:all) +results = collect_outputs(simulation; sink=DataFrame) +nothing # hide ``` -`ToyLAIModel` does not know where `TT_cu` comes from, and `Beer` does not know -where `LAI` comes from. The compiler infers the unambiguous same-object -bindings from each model's declared inputs and outputs: - -```@example readme -select( - DataFrame(Diagnostics.explain_bindings(model)), - :application_id, - :input, - :source_application_ids, - :carrier_kind, - :copy_semantics, -) -``` - -The outputs can be plotted like any other tabular result: +The thermal-time model supplies the LAI model, which supplies the light +model. PlantSimEngine connects them using their matching input and output +names. The result table contains their outputs over time. The +[step-by-step tutorial](journeys/users/one_object.md) explains these connections +and shows how to continue a simulation; the +[plotting guide](guides/data/outputs_plotting.md) explains how to display results. -```@example readme -using CairoMakie +## Scientific models and further reading -lai = out[out.variable .== :LAI, :value] -appfd = out[out.variable .== :aPPFD, :value] -tt_cu = out[out.variable .== :TT_cu, :value] +PlantSimEngine provides the simulation tools. Model packages provide equations, +parameters and their scientific validation. Examples of packages using +PlantSimEngine include: -fig = Figure(resolution=(800, 600)) -ax = Axis(fig[1, 1], ylabel="LAI (m² m⁻²)") -lines!(ax, tt_cu, lai, color=:mediumseagreen) +- [PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl), for plant + biophysical processes such as photosynthesis, stomatal conductance and energy balance. +- [XPalm](https://github.com/PalmStudio/XPalm.jl), for oil-palm growth and development. -ax2 = Axis(fig[2, 1], xlabel="Cumulated growing degree days since sowing (°C)", ylabel="aPPFD (mol m⁻² d⁻¹)") -lines!(ax2, tt_cu, appfd, color=:firebrick1) -fig -``` - -## Multi-Object Inputs - -Use `ModelSpec(...; inputs=...)` when a model needs values from selected objects. Here the -scene LAI model reads live references to all plant surfaces in the scene: - -```@example readme -plant_scene = CompositeModel( - Object(:scene; scale=:Scene, kind=:scene), - Object(:plant_1; scale=:Plant, kind=:plant, parent=:scene, - status=Status(surface=12.0)), - Object(:plant_2; scale=:Plant, kind=:plant, parent=:scene, - status=Status(surface=8.0)); - applications=( - ModelSpec(ToyLAIfromLeafAreaModel(100.0); name=:scene_lai, on=One(scale=:Scene), inputs=(:plant_surfaces => Many( - scale=:Plant, - within=SceneScope(), - var=:surface, - ),)), - ), -) +Their documentation describes the models available, their assumptions and +supported package versions. To choose an approach, read +[Why PlantSimEngine?](introduction/why_plantsimengine.md). For a published +application and its validation, see the +[PlantBiophysics paper](https://doi.org/10.1093/insilicoplants/diaf021). -plant_sim = run!(plant_scene) -scene_status = final_state(plant_sim, One(scale=:Scene)) -scene_status -``` - -The same `Many(...)` selector would be plant-local if the consumer ran on a -plant and used `within=Subtree()`. This is the same mechanism used for plant -allocation models that sum their own leaves, scene models that aggregate all -plants, and microclimate solvers that select objects inside one environment -cell. - -When a selector reads a value produced by another model application, prefer -`application=...` to identify the concrete producer. A process name describes -the reusable scientific contract; an application name identifies the mounted -producer in this scenario. This matters as soon as several applications -implement the same process or publish the same variable on different objects. - -## Manual Calls For Iterative Solvers - -Use `ModelSpec(...; calls=...)` when a parent model must directly run another model, for -example a scene energy-balance solver that iterates leaf temperatures until -convergence: - -```julia -ModelSpec(SceneEnergyBalance(); name=:scene_energy, on=One(scale=:Scene), calls=(:leaf_energy => Many( - kind=:plant, - scale=:Leaf, - within=SceneScope(), - application=:energy_balance, - ), - :soil => One( - kind=:soil, - scale=:Soil, - within=SceneScope(), - application=:soil_water, - ),), every=Hour(1)) -``` - -The same rule applies to manual calls: scenario wiring should select the -concrete callee application with `application=...`. Model authors use process -requirements in `dep(model)` when they declare generic dependencies, because -they cannot know the application names that a user will choose later. - -Inside `run!`, use `run_call!(context, :leaf_energy)` to execute every target and -receive a vector-like collection. Pass `sampled_environment=value` to the same -bulk call when the parent has already sampled one environment for all targets. -Use `call_model(context, :leaf_energy)` when a singular call's concrete model -must guide an iterative algorithm. Reserve `call_targets` and -`run_call!(target; publish=false)` for selection, custom ordering, target status -inspection, or different per-target environments. Publish the accepted state -once, so temporal outputs and mutable environment writes are recorded exactly -once. - -## Where To Go Next - -- [A mental model](journeys/users/mental_model.md) introduces the seven ideas - used throughout the framework without configuration details. -- [Couple models on one object](journeys/users/one_object.md) is the first - executable journey and runs a coupled simulation over many timesteps. -- [Run the coupling on several objects](journeys/users/several_objects.md) - introduces stable object identity and `Many`. -- [Implement a basic model](journeys/modelers/basic_model.md) is the canonical - executable path for parameters, ports, contracts, a direct kernel test, and - runtime composition. -- [Public API](API/API_public.md) lists the composite-model/object constructors, - selectors, lifecycle hooks, and explanation helpers. -- [Model traits](model_traits.md) explains `inputs_`, `outputs_`, `dep`, - `timespec`, `output_policy`, and `environment_inputs_`. -- [Migration guide](migration_composite_model.md) covers upgrades from earlier - PlantSimEngine releases. - -## Performance - -PlantSimEngine keeps model kernels close to regular Julia functions while the -runtime handles dependency scheduling, object selection, temporal aggregation, -and environment sampling. On an M1 MacBook Pro, toy daily simulations run in -hundreds of microseconds, and PlantBiophysics.jl models using PlantSimEngine -have been measured much faster than equivalent implementations in typical -scientific scripting languages. - -For performance-sensitive composite models, inspect the supported structured -explanations: - -```julia -Diagnostics.explain_bindings(model) -Diagnostics.explain_schedule(model) -Diagnostics.explain_execution_plan(model) -``` +PlantSimEngine is open source under the MIT license. For questions or feedback, +[open an issue](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues) +or join the [Virtual Plant Lab discussion](https://fspm.discourse.group/c/software/virtual-plant-lab). -These helpers expose resolved objects, carriers, copy/reference semantics, -application clocks, and homogeneous execution batches. - -## Ask Questions - -If you have questions or feedback, [open an issue](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues) -or ask on [discourse](https://fspm.discourse.group/c/software/virtual-plant-lab). - -## Projects That Use PlantSimEngine - -- [PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl) -- [XPalm](https://github.com/PalmStudio/XPalm.jl) - -## Make It Yours - -PlantSimEngine is distributed under the MIT license. If you develop a package -or model suite that uses it and want it listed here, please open a pull request -or contact the maintainers. +[![Build Status](https://github.com/VirtualPlantLab/PlantSimEngine.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/VirtualPlantLab/PlantSimEngine.jl/actions/workflows/CI.yml?query=branch%3Amain) +[![Coverage](https://codecov.io/gh/VirtualPlantLab/PlantSimEngine.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/VirtualPlantLab/PlantSimEngine.jl) +[![DOI](https://zenodo.org/badge/571659510.svg)](https://zenodo.org/badge/latestdoi/571659510) +[![JOSS](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09/status.svg)](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09) diff --git a/docs/src/introduction/why_julia.md b/docs/src/introduction/why_julia.md index 892421fc7..21766ea0f 100644 --- a/docs/src/introduction/why_julia.md +++ b/docs/src/introduction/why_julia.md @@ -1,94 +1,52 @@ # The choice of using Julia -PlantSimEngine is implemented in Julia. It arose from a particular combination of [needs and requirements](why_plantsimengine.md) that Julia addresses effectively. - -Other modelling frameworks, FSPMs and crop models are -often- written in combinations of Java, C++, Python, or Fortran. Given that Julia isn't the language many researchers (and developers!) are most familiar with yet, this page provides a short explanation of the reasoning behind that language choice. Another nice resource is [this discourse post](https://fspm.discourse.group/t/why-is-julia-meant-for-fspm/175) by Alejandro Morales Sierra, the creator and maintainer of Virtual Plant Lab. - -## From research to real-world applications - -PlantSimEngine was originally a goal-oriented framework. Its features arose -and continue to evolve- out of necessity for more and more complex simulation setups. - -While PlantSimEngine primarily helps researchers prototype and test their models efficiently, we consistently work with the vision of making it suitable for real-world applications. Our goal is to build a bridge between academic plant modeling and practical field applications. Ideally, researchers should be able to develop and refine their models in a comfortable environment, and these models could eventually be deployed in production environments. - -This vision of dual-purpose functionality drives our focus on performance optimization. We aspire for the models you develop to be useful beyond academic papers, potentially serving reliably in production environments where efficiency and accuracy are crucial. Julia's strong performance characteristics support this vision in ways other languages would struggle to match. - -PlantSimEngine aims to balance scientific rigor with developer productivity, with the long-term goal of ensuring that models can be deployed at scale. Julia provides an environment where researchers can express complex mathematical concepts directly in code with good performance potential, creating a pathway for these models to potentially reach practical implementation. - -## PlantSimEngine's constraints - -### Performance - -While computers have gained several orders of magnitude of power and memory over the past few decades, to the point where many prior performance bottlenecks have vanished, performance can still be a limiting factor. - -Simulating multiple processes with user-provided variables over many plants with tens of thousands of leaves requires a lot of computation. Using a higher-level language such as Python or R would not lead to adequate simulation times. - -In fact, part of the initial motivation to commit to Julia happened after porting [a model](https://github.com/VEZY/DynACof.jl) from R to Julia and getting several orders of magnitude difference in performance 'out-of-the-box'. Seeing computations that previously took minutes suddenly completing in seconds was quite convincing (see also [this benchmark](https://vezy.github.io/PlantBiophysics-paper/notebooks_performance_Fig5_PlantBiophysics_performance/) showing a difference of 5 orders of magnitude). - -Julia, with its well-designed 'Just-ahead-of-time' compilation model and its flexibility allowing to do some lower-level optimisation, doesn't suffer from the limitations one would encounter by using only Python or R. - -### Flexibility, ease of use - -PlantSimEngine was also developed with a few goals in mind, one of them being to make hypothesis testing quite easy. It is currently difficult to validate FSPM, crop model or ecophysiological hypotheses in many existing frameworks due to their rigid structure or steep learning curve. - -Similarly, when developing a full-featured FSPM, there might be a need to test different models for a specific process, or to switch a model for a more complex one. API and language ease of use is as much of a factor as automated model coupling in keeping these changes smooth. - -### Packages destined to be used by a wider community - -As mentioned earlier, PlantSimEngine is intended for a wide audience. Only few of them are expected to have a strong development background. Many other potential users might be researchers more well-versed in ecophysiology or plant architecture and only know a little bit of Python, Matlab or R. Reducing friction for these users is paramount. - -Open-source libraries/packages, ease of installation and low entry barrier also factor in the decision. - -### Modularity and flexibility while retaining performance - -One approach could be to combine, say, Python, with a more performant language such as C++ or Fortran. The slower but flexible language being used for prototyping, and when performance is required, some chunks are reimplmented in the other language. - -This fits the performance constraint, but has a few caveats. - -### Low developer bandwidth - -And of course, budget, time and resources are a concern. The more autonomous researchers and modelers are, and the less specialist developer/engineering resources are required, the easier it is for the project to keep evolving. - -## Comparison - -### The Two-Language Problem - -Combining two different languages requires a lot of language expertise, with constant knowledge refreshing, as one might only occasionally work with and debug with the lower-level language. Or more engineering resources. - -Speed of iteration is also lost whenever performance is a concern, which happens often in our context. However modular and easy-to-use a language like Python might be, whenever it's time to switch to a low-level language, development speed will slow down. - -Julia effectively solves this problem. While it might be a little harder to learn than Python, and require extra knowledge to properly make use of its flexibility and performance capabilities, it leads to a smoother development experience. - -Everything can be done using Julia exclusively, so there is no need to learn two languages. No need to interface between them. Iteration speed doesn't suddenly grind to a halt if a low-level implementation is needed. A competent researcher-developer can move seamlessly from prototype to production, while still being able to focus on modeling and the actual plant side of things. - -![Language usage comparison for different ML packages (source: https://pde-on-gpu.vaw.ethz.ch/lecture1/)](../www/l1_flux-vs-tensorflow.png) -(Language usage comparison for different ML packages; source: https://pde-on-gpu.vaw.ethz.ch/lecture1/) - -It seems we aren't the only ones to find Julia a good tool for our job. Other niches where Julia is gaining traction tend to be other computationally heavy areas with much active research, such as machine learning and climate modeling - areas where this balance of expressivity and performance is equally valuable. - -### A good balance in terms of accessibility - -Another argument in favour of Julia is that one of the aims for PlantSimEngine is to be easy-to-use for researchers wishing to test hypothesis, or reproduce results from other papers. Scientific reproducibility is greatly enhanced when the barrier to running and modifying simulations is lowered. - -Many researchers are not developers by trade or heart, and a Java-only or C++-only implementation, on top of the earlier points, would not be accessible enough and would not gain much traction. - -Julia, while less ubiquitous than other languages in research circles, resembles Python and R and is more beginner-friendly than Java or C++. It is easier for a Python user to learn to use a simple Julia package than a C++ one. - -Users will also find it easier to quickly implement new models without the potential hurdle of a low-level implementation, or some language interfacing also being required. The prototyping phase doesn't require a subsequent performance tuning phase. - -### Ease of environment setup - -Similarly, Julia's language and package installation is -mostly- fairly straightforward and requires little additional knowledge. - -The package manager is built directly into the language, making dependency management straightforward. This is particularly important for reproducible scientific workflows, where consistent environments are crucial. - -### Downsides acceptable - -While very practical for a 'researcher-developer', Julia is of course far from being the perfect language in every discipline. It is massive in terms of features, has a heavy runtime, is more involved to learn and master quickly compared to Python, has a few hurdles for beginners, some quirks that can be awkward for developers, tools that aren't fully mature, no clear 'recommended' workflow, and so on. - -The cost for switching may not be worth it in many other circumstances. However, several of these downsides, while very relevant for embedded systems, or game development, are much less relevant regarding PlantSimEngine. And others can be mitigated with, hopefully, adequate learning resources and documentation. - -## Conclusion - -For PlantSimEngine's specific requirements—balancing performance with flexibility, enabling rapid iteration while maintaining computational efficiency, and providing an accessible interface for both researchers and field practitioners—Julia represents a suitable choice. The language allows us to build an ecosystem where plant modeling can advance through collaborative, efficient, and scientifically rigorous development while delivering real-world value through production deployments. - -While no language solution is perfect, Julia's combination of features makes it well-suited to the challenges of modern plant modeling and simulation, both in research and practical applications. We're optimistic about the possibilities it offers for the future of plant modeling. +PlantSimEngine uses Julia so that researchers can write process equations, +assemble simulations, inspect results, and improve computational performance +in the same language. This supports the model-development workflow described +in [Why PlantSimEngine?](why_plantsimengine.md). + +## Keep equations and their implementation close + +A process model contains a Julia function whose inputs, state, and parameters are +explicit. You can read its calculations, call it directly in a small test, +and reuse it in a larger simulation. Optional +[Unicode names](https://docs.julialang.org/en/v1/manual/unicode-input/) can keep +symbols close to the notation in a paper, while descriptive names make their +meaning clear. The [model-author tutorial](../journeys/modelers/basic_model.md) +shows a complete example. + +Julia also lets numerical code work with different compatible value types. +For example, a model can preserve `Float32` values or carry uncertainty through +an optional numerical package when its operations support those types. See +[numerical reliability](../guides/data/numerical_reliability.md) for the +requirements and examples. + +## Prototype, measure, and improve in one language + +You can begin with a readable implementation and use Julia's timing, +profiling, and type-inspection tools to find where optimization is useful. +Keeping the model in Julia makes it possible to maintain the same tests while +improving its implementation. + +Performance depends on the algorithm, how data are stored, how much memory +must be created, and how much work the simulation requests. The first run can +also take longer while Julia prepares the code for execution. Measure that +first run separately from repeated runs. +Julia's [performance guide](https://docs.julialang.org/en/v1/manual/performance-tips/) +explains these distinctions. PlantSimEngine's +[benchmarking guidance](../developers.md) adds the costs of scenario +initialization, structural updates, and output collection. + +## Share the software environment with the experiment + +Julia's package manager supports a separate environment for each project. +Its `Project.toml` lists the packages the project needs, and its `Manifest.toml` +records the exact versions used. Sharing these files, the Julia version, model code, and +input data helps others recreate an experiment. See the official +[environment guide](https://pkgdocs.julialang.org/v1/environments/) and +[PlantSimEngine installation](../prerequisites/installing_plantsimengine.md). + +Learning Julia still takes time, especially its type system and package +workflow. Start with [Julia basics](../prerequisites/julia_basics.md), then +[run one coupled simulation](../journeys/users/one_object.md). You can learn +the model-author tools when your research requires a new equation or process. diff --git a/docs/src/introduction/why_plantsimengine.md b/docs/src/introduction/why_plantsimengine.md index 6813f1051..d9796b8a5 100644 --- a/docs/src/introduction/why_plantsimengine.md +++ b/docs/src/introduction/why_plantsimengine.md @@ -1,110 +1,154 @@ # Why PlantSimEngine? -PlantSimEngine was developed to address fundamental limitations in existing plant modeling tools. This framework emerged from the need for a system that could efficiently handle the complex dynamics of the soil-plant-atmosphere continuum while remaining accessible to researchers and practitioners from diverse disciplines. - -## The Current Landscape of Plant Modeling - -Plant modeling has evolved significantly over the years, with different tools making different design tradeoffs to address specific research needs. These tools generally fall into three categories, each with their own strengths and limitations: - -### Monolithic Systems - -Systems like APSIM[^1], GroIMP[^2], AMAPStudio[^3], Helios[^4], and CPlantBox[^5] offer comprehensive functionality but present certain tradeoffs: - -These systems provide robust, well-tested frameworks with established scientific validity, but their large, complex codebases can be challenging to navigate and modify without extensive programming expertise. - -Their comprehensive architecture offers a wealth of integrated features but may require adaptation when implementing novel approaches that don't align with their predefined frameworks. - -They excel at specific types of simulations but may require additional engineering effort for seamless multi-scale simulations and model coupling across the soil-plant-atmosphere continuum. - -These platforms typically require dedicated engineering resources for maintenance and extension, with research teams often needing specialized technical staff to implement new models. - -### Distributed Systems - -Platforms like OpenAlea[^6] and Crops in Silico[^7] offer different advantages and tradeoffs: - -These systems provide accessible interfaces (often in Python) that prioritize ease of use and flexibility, making them approachable for many researchers, though they may require performance optimization for large-scale simulations. - -Their modular nature facilitates component reuse and integration, while sometimes requiring proficiency in multiple programming languages for extending computational backends. - -They support diverse modeling paradigms but may involve a longer iteration cycle between design, implementation, and performance tuning compared to more specialized tools. - -While offering flexibility, implementing complex models often requires significant developer time, especially when optimizing performance using lower-level languages. - -### Architecture-Focused Tools - -Tools like AMAPSim[^8] make specific design choices that benefit certain applications: - -These systems excel in their focused domains (such as structural modeling of plants) while requiring integration with other tools for comprehensive studies of plant physiology and environmental responses. - -Their implementation in languages like C++ or Java delivers excellent performance but represents a tradeoff in terms of accessibility for researchers without expertise in these languages. - -They provide sophisticated functionality in their target domains but may require additional work for rapid hypothesis testing and model prototyping across diverse aspects of plant science. - -## The PlantSimEngine Solution - -PlantSimEngine brings together innovative ideas to address these various tradeoffs, offering a unique combination of features: - -### Automatic Model Coupling - -**Seamless Integration:** PlantSimEngine leverages Julia's multiple-dispatch capabilities to automatically compute the dependency graph between models. This allows researchers to effortlessly couple models without writing complex connection code or manually managing dependencies. - -**Intuitive Multi-Scale Support:** The framework naturally handles models operating at different scales—from organelle to ecosystem—connecting them with minimal effort and maintaining consistency across scales. - -### Flexibility with Precision Control - -**Effortless Model Switching:** Researchers can switch between different component models using a simple syntax without rewriting the underlying model code. This enables rapid comparison between different hypotheses and model versions, accelerating the scientific discovery process. - -**Fine-Grained Model Control:** PlantSimEngine allows users to fix parameters, force variables to match observed values, or select simpler models for specific processes. This flexibility helps reduce overall system complexity while maintaining precision where it matters most. - -**Adaptive Scalability:** The same framework efficiently supports both simple prototypes for single-plant studies and complex ecosystem simulations, scaling computational resources appropriately to the problem at hand. - -### Outstanding Performance - -**High-Speed Computation:** Benchmarks demonstrate operations completing in hundreds of nanoseconds, making PlantSimEngine suitable for computationally intensive applications. For example, the [PlantBiophysics.jl implementation is over 38,000 times faster](https://vezy.github.io/PlantBiophysics-paper/notebooks_performance_Fig5_PlantBiophysics_performance/) than equivalent implementations in R. - -**Computational Efficiency:** Julia's just-ahead-of-time compilation and native support for parallelism ensure that optimizations made during prototyping directly transfer to larger-scale applications, eliminating the need for reimplementation in a different language for performance gains. - -### Developer Efficiency - -**Reduced Implementation Time:** PlantSimEngine leverages Julia's dynamic language features while maintaining the performance of statically-compiled languages. This significantly reduces the time researchers spend implementing and optimizing models. - -**Modular Building Blocks:** The component-based architecture allows models to be built as unit components that can be stacked like building blocks to create complex systems. This modularity dramatically increases code reuse and reduces redundant implementation efforts. - -**No Engineering Overhead:** Unlike monolithic systems that require dedicated engineering teams or distributed platforms that need backend optimization, PlantSimEngine enables domain scientists to independently develop high-performance models without specialized programming expertise. - -**Rapid Prototyping to Production:** The same code used for quick prototyping can transition directly to production-scale simulations without rewriting, eliminating the traditional gap between exploratory research and application. - -## Key Innovations - -PlantSimEngine's approach to plant modeling represents a paradigm shift in how scientists can build and use models: - -- **Uniform API:** Standardized interfaces make it easy to define new processes and component models, reducing the cognitive load on researchers. - -- **Automatic Dependency Resolution:** The system automatically determines the relationships between different models and processes, eliminating the need for manual coupling. - -- **Concrete Batched Execution:** The model compiler groups compatible object - targets into concrete execution batches. A public parallel or distributed - executor is not currently provided; parallel execution remains planned work - that requires explicit correctness and independence guarantees. - -- **Flexible Model Integration:** The ability to easily combine models from different sources and at different scales facilitates more comprehensive and realistic simulations. - -- **User-Centric Design:** Emphasizing usability ensures that researchers with varied programming backgrounds can effectively engage with the system. - -By offering solutions to the various tradeoffs present in existing modeling approaches, PlantSimEngine enables researchers to focus more on scientific questions and less on technical implementation details, accelerating the pace of discovery in plant science, agronomy, and related fields. - -[^1]: Holzworth, D. P. et al. APSIM – Evolution towards a new generation of agricultural systems simulation. Environmental Modelling & Software 62, 327-350 (2014). - -[^2]: Hemmerling, R., Kniemeyer, O., Lanwert, D., Kurth, W. & Buck-Sorlin, G. The rule-based language XL and the modelling environment GroIMP illustrated with simulated tree competition. Funct. Plant Biol. 35, 739 (2008). - -[^3]: Griffon, S., and de Coligny, F. AMAPstudio: An editing and simulation software suite for plants architecture modelling. Ecological Modelling 290 (2014): 3‑10. . - -[^4]: Bailey, R. Spatial Modeling Environment for Enhancing Conifer Crown Management. Front. For. Glob. Change 3, 106 (2020). - -[^5]: Schnepf, A., Leitner, D., Landl, M., Lobet, G., Mai, T. H., Morandage, S., Sheng, C., Zörner, M., Vanderborght, J., & Vereecken, H. CPlantBox: A whole-plant modelling framework for the simulation of water- and carbon-related processes. in silico Plants, 63 (2018). - -[^6]: Pradal, C. et al. OpenAlea: A visual programming and component-based software platform for plant modeling. Funct. Plant Biol. 35, 751-760 (2008). - -[^7]: Marshall-Colon, A. et al. Crops In Silico: Generating Virtual Crops Using an Integrative and Multi-Scale Modeling Platform. Frontiers in Plant Science 8 (2017). . - -[^8]: Barczi, J.-F., Rey, H., Caraglio, Y., Reffye, P. de, Barthélémy, D., Dong, Q. X., & Fourcaud, T. AmapSim: A Structural Whole-plant Simulator Based on Botanical Knowledge and Designed to Host External Functional Models. Annals of botany, 101(8), 1125-1138 (2008). +PlantSimEngine helps you build plant simulations from process models that you +can inspect, test, reuse, and replace. You choose the scientific equations, +the plants, organs or other entities they describe, and the exchanges between +them. The engine connects their inputs and outputs and runs the resulting +simulation in Julia. + +This is useful when your research question requires a particular combination +of processes or assumptions: + +- **Crop modelling:** assemble development, light interception, biomass, or + water-balance processes at the resolution your question needs. Start with + [a coupled simulation for a canopy](../journeys/users/one_object.md). +- **Canopy ecophysiology:** connect weather, local conditions and organ processes, + including calculations that must iterate together. The + [MAESPA-style synthesis](../journeys/users/maespa_synthesis.md) demonstrates + how these calculations can work together, using teaching models. +- **Functional–structural plant modelling:** apply processes to organs, + connect their results to the plant, and update the structure during growth. + Start with [one multiscale plant](../journeys/users/one_plant.md). + +The scientific models, parameter sets, input data, and validation for your +species or experiment come from your own work or model packages such as +[PlantBiophysics.jl](https://github.com/VEZY/PlantBiophysics.jl). PlantSimEngine +provides the tools for connecting and running them. + +## Compare hypotheses without rewriting the whole simulation + +A process can have several model implementations. For example, you may want +to compare two biomass-production equations or introduce water limitation +into a previously radiation-driven model. Each implementation keeps its own +parameters and equations; the scenario specifies where it runs and how it +receives inputs. + +Replacement depends on the model's interface: the values it needs and produces, +and what those values mean. The new model must provide the outputs other +models need, and its own inputs must be available. A variable contract records +information such as units, whether a quantity is per plant or per unit area, +and whether it is a rate or an accumulated amount. The same variable name +alone is insufficient. Moving from a quantity per unit ground area to a total +per plant, for example, needs an explicit conversion. + +To replace a model only for selected plants, its inputs, outputs, and other +requirements must match the original model. A replacement that needs an extra +input, such as soil water content, requires changes to the simulation setup. See +[model compatibility and replacement](../step_by_step/model_switching.md). + +Model authors can read each equation together with its inputs and outputs. +Researchers assembling models can see which equations and assumptions were +chosen in the simulation setup. Both can test a component +before investigating its behaviour in the full system. + +## Choose the representation that answers your question + +An object can represent a leaf, a plant, a canopy layer, a soil compartment, +or another entity you define. You can work with one object, several objects, +or a hierarchy imported from a multiscale tree graph. Geometry is optional. +Different models can be applied to different selections of these objects. + +The same process equation can be reused over compatible objects while the +scenario handles their selection and connections. A plant-level model can, +for example, read values from its own leaves. The modeller decides how to combine these values, for example by summing leaf +areas, and supplies any required area, mass, or time conversion. +Changing resolution also requires checking the assumptions and validity of +the chosen models. See [value coupling across objects](../guides/multiscale/value_coupling.md). + +When organs appear, disappear, or move within the plant structure, +PlantSimEngine updates the affected model selections and connections. This lets +growth change which organs contribute to a plant-level calculation while +retaining their identities and historical outputs. Follow +[Modify Plant Structure](../journeys/users/structure_changes.md). + +## Connect different time steps and control scientific iteration + +Canopy exchange may run hourly while development runs daily. Each model +can run at its own time step, with explicit rules for reading values produced +at another time step. The appropriate averaging, accumulation, +or rate-to-amount conversion is a scientific choice. The +[cadence tutorial](../journeys/users/cadences.md) makes those choices explicit. + +Some calculations also need a controller: an energy-balance algorithm may +call gas-exchange models repeatedly while finding an accepted leaf temperature. +Explicit model calls let the controller manage that iteration and record the +accepted result once. See [advanced execution](../journeys/users/advanced_execution.md). + +## Understand what the simulation will do + +The `Authoring` and `Diagnostics` interfaces expose model declarations, +missing inputs, the sources of values, execution order, local environmental +conditions, and which results are saved. You can inspect why a particular leaf +receives a value, which model supplies it, and when it is updated. The +[graph viewer](../guides/graph_visualizer_editor.md) provides another view of +how the models are connected. + +These reports help separate a coupling problem from a problem in an equation +or its assumptions. Declared units and physical meanings help reveal incompatible connections; +scientific validation still needs suitable observations, reference results, +and tests. See the [model authoring API](../API/API_public.md) and +[model testing guide](../guides/modelers/repository_and_tests.md). + +## Keep repeated simulations practical + +PlantSimEngine prepares model selections and connections before repeated +execution, avoids copying input values where possible, and processes groups +of similar objects together. Model equations remain ordinary Julia +calculations whose performance can be measured and improved. + +There is application-level performance evidence: the +[2025 PlantBiophysics.jl paper](https://doi.org/10.1093/insilicoplants/diaf021) +reports a median of 5.3 microseconds for one leaf and one time step of its +coupled energy-balance, photosynthesis, and stomatal-conductance benchmark. +That result concerns the implementations, versions, inputs, and hardware used +in the study. For your scenario, measure initialization, repeated execution, +structural changes, and saving results separately using the +[benchmarking guidance](../developers.md). A public parallel or distributed +executor remains [planned work](../planned_features.md). + +## AI-assisted model development + +An AI coding agent is software that can read and edit code and run tests with +your development tools. Small process models, explicit inputs and outputs, +declared units, and reports on model connections give it concrete information +to read and check. An agent can help draft a model, compare declared +interfaces, assemble a scenario, inspect its connections, and run tests with +the tools available in your development environment. + +PlantSimEngine provides a versioned [AI agent skill](../agent_skill.md), a +[catalog of available models](../API/model_catalog.md), and the same authoring tools +used by people. You supply the coding agent and its execution environment. +Model assumptions, physical conversions, supporting references, and scientific +validation remain the responsibility of the researcher. Begin with +[Implement a basic model](../journeys/modelers/basic_model.md) to see the +complete model, an independent equation test, and its use in a simulation. + +## How this fits among plant-modelling tools + +Modularity and multiscale modelling have a substantial history. +[APSIM](https://docs.apsim.info/docs/development/software/interfaces) supports +replaceable model interfaces; +[DSSAT](https://dssat.net/frontpage/) combines crop models with data and +experimental workflows; +[OpenAlea](https://openalea.readthedocs.io/en/latest/packages/modelling.html) +provides components, multiscale structures, and plant-geometry tools; and +[GroIMP](https://grogra.de/) integrates FSPM modelling and visualisation. +[Cropbox](https://doi.org/10.1093/insilicoplants/diac021) also uses Julia and +dependency analysis for declarative crop modelling. + +PlantSimEngine's contribution is the combination described here: readable +process equations, explicit inputs and outputs, a choice of how to represent +plants, different time steps, controlled iteration, changing structures, and +calculations you can inspect. It is a useful fit when you want to develop or assemble +that scientific model combination yourself, while keeping its choices visible +and its components independently testable. diff --git a/docs/src/journeys/modelers/basic_model.md b/docs/src/journeys/modelers/basic_model.md index 8b9be91a1..d2c07c063 100644 --- a/docs/src/journeys/modelers/basic_model.md +++ b/docs/src/journeys/modelers/basic_model.md @@ -1,165 +1,171 @@ # Implement a basic model -**New concept:** the complete one-step model boundary: process identity, -parameters, ports, scientific contracts, and a readable five-argument kernel. -This page uses the tested canonical fixture shipped with the PlantSimEngine -skill, first directly and then through the ordinary runtime. +This teaching example describes daily biomass production as: -Before creating a type, follow [New process or new model?](@ref). The example -below is one hypothesis for the `biomass_production` process. Its coefficients -are pedagogical, not a calibrated crop model. +**biomass increment = radiation-use efficiency × intercepted radiation** -## Read the complete model +For an efficiency of 1.5 g dry matter per mol of photons and 10 mol of +intercepted photons per plant, the result is 15 g dry matter per plant. +These values show how to write a model; they are not a calibrated crop model. -This is the complete, copyable source shipped with the package. The model -declaration comes first; `direct_example` tests its kernel and -`single_object_scenario` shows the smallest runtime composition. +We will give that equation a name, declare its variables and units, test it, +and run it on two plants. Before adding your own model, use +[New process or new model?](@ref) to choose its process. + +## Name the process and its model + +A **process** identifies the scientific calculation. A **model** implements +one hypothesis for it. This example declares a biomass-production process: ```@eval -using Markdown, PlantSimEngine -source = read(joinpath( - pkgdir(PlantSimEngine), "skills", "plantsimengine", "assets", "minimal-model.jl", -), String) -Markdown.MD([Markdown.Code("julia", source)]) +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "PlantSimEngine.@process", "const INTERCEPTED_PAR_CONTRACT", +) ``` -## Load and inspect it +The model stores one fixed parameter, `rue`. The `{T}` allows its numerical +type to follow the supplied parameter. -The documentation and agent skill use the same executable source instead of -maintaining two copies: +```@eval +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "struct RadiationUseEfficiency", "PlantSimEngine.inputs_", +) +``` -```@example modeler_basic -using Dates, PlantSimEngine - -asset = joinpath( - pkgdir(PlantSimEngine), - "skills", - "plantsimengine", - "assets", - "minimal-model.jl", +## Declare the values the equation uses + +| Value | Role | Meaning | +|---|---|---| +| `rue` | Fixed parameter | g dry matter per mol intercepted photons | +| `intercepted_par` | Input | Daily intercepted photons, mol per plant | +| `biomass_increment` | Output | Daily biomass production, g dry matter per plant | + +`Required(Real)` says the simulation must supply a real-valued input. +`zero(model.rue)` initializes the output with the parameter's numerical type. +This model reads no environmental variables directly. + +```@eval +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "PlantSimEngine.inputs_(::RadiationUseEfficiency)", + "PlantSimEngine.variable_contracts_", ) -include(asset) -using .MinimalModelExample +``` + +A `VariableContract` describes a variable's units and meaning. It records, +for example, whether a value is per plant or per square metre, and whether it +is a rate or a daily total. This helps check that two connected models +interpret a value in the same way. Here both quantities are daily totals +for one plant: -boundary = RadiationUseEfficiency(1.5f0) -description = Authoring.describe_model(boundary) -validation = Authoring.validate_model(boundary; strict=true) -( - runtime_process=process(boundary), - described_process=description.process, - inputs=inputs(boundary), - outputs=outputs(boundary), - contracts=variable_contracts(boundary), - description_provenance=description.provenance, - field_provenance=description.field_provenance, - structurally_valid=validation.valid, +```@eval +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "const INTERCEPTED_PAR_CONTRACT", "\"\"\"", ) ``` -The loaded declaration is deliberately short. `RadiationUseEfficiency{T}` -stores `rue`; its schemas declare `intercepted_par` and -`biomass_increment`, plus explicitly empty environment inputs and outputs. The -two ports receive complete contracts, and the complete kernel equation is -`status.biomass_increment = model.rue * status.intercepted_par` followed by -`return nothing`. This description is derived from the asset included above, -so the tutorial does not maintain a second untested copy of its source. +Read these settings as follows: `unit` names the measurement unit, +`basis=:plant` says it refers to one plant, and `temporal=:day` with +`aggregation=:total` says it is a daily total. `extent=:extensive` means the +amounts from several plants can be added to obtain their combined amount. + +Attach those descriptions to the corresponding variables: -The model struct stores only the fixed radiation-use-efficiency parameter. -`Required(Real)` is a type requirement, not an initial value. The output -initial value follows the parameter's numeric type. The complete -`VariableContract` declarations state that intercepted radiation and biomass -increment are daily, plant-scale totals with explicit units. +```@eval +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "PlantSimEngine.variable_contracts_(::RadiationUseEfficiency)", + "PlantSimEngine.Authoring.model_metadata", +) +``` -The kernel reads as the scientific calculation from input to output. It does -not select objects, find producers, choose a cadence, or retain output rows; -those are scenario responsibilities. +These descriptions help check connections, but do not convert values. If one +model supplies radiation per square metre and another needs radiation per +plant, write the conversion in an [adapter model](../../guides/coupling.md). -## Test the kernel directly +## Write the equation -Use a minimal `Status` before involving the compiler: +The `run!` function reads the parameter from `model`, reads the input from +`status`, and writes its result back to `status`: -```@example modeler_basic -direct = direct_example(Float32) -( - biomass_increment=direct.biomass_increment, - value_type=typeof(direct.biomass_increment), +```@eval +Main.DocsSources.section( + "skills/plantsimengine/assets/minimal-model.jl", + "function PlantSimEngine.run!(", "\"\"\"Run the kernel directly", ) ``` -This test isolates the equation and proves that the fixture preserves -`Float32`. Model packages should also test edge cases and supported enriched -number types. +The other arguments provide environmental data, constants, and tools for +calling other models or changing the simulated objects. This equation does +not need them. Choose which plants use the model and when it runs in the +simulation setup below. -## Compose it on one object +## Test one calculation -The asset provides the smallest full scenario with the required input supplied -as initial status: +These displayed definitions come from the package's executable +`skills/plantsimengine/assets/minimal-model.jl` example. To load the complete +example in your session: ```@example modeler_basic -one_object = single_object_scenario(Float32) -( - initialization=Diagnostics.explain_initialization(one_object), - final=final_state(run!(one_object)), -) +using Dates, Test, PlantSimEngine +asset = joinpath(pkgdir(PlantSimEngine), "skills", "plantsimengine", "assets", "minimal-model.jl") +include(asset) +using .MinimalModelExample + +model = RadiationUseEfficiency(1.5f0) +status = Status(intercepted_par=10.0f0, biomass_increment=0.0f0) +PlantSimEngine.run!(model, status, NamedTuple(), nothing, nothing) + +@test status.biomass_increment == 15.0f0 +@test status.biomass_increment isa Float32 +status.biomass_increment +``` + +The `f0` notation chooses `Float32`. The tests check the equation and that +the implementation preserves this numerical type. Also check the declarations: + +```@example modeler_basic +validation = Authoring.validate_model(model; strict=true) +@test validation.valid +validation.valid ``` -`Diagnostics.explain_initialization` distinguishes supplied inputs, model -defaults, produced outputs, environment bindings, and unresolved requirements. -Inspect this report before running a larger scenario. +That check finds missing or inconsistent model declarations. To check whether +the equation describes real plants, compare its results with appropriate +observations or reference results. -## Reuse the same kernel over several objects +## Run the model on two plants -Object selection remains outside the model. Change only the application -multiplicity and provide each object with initial radiation: +Each plant has its own intercepted radiation. The same model applies to both: ```@example modeler_basic -development = RadiationUseEfficiency(1.5f0) -several_objects = CompositeModel( - Object( - :plant_1; - scale=:Plant, - status=Status(intercepted_par=10.0f0), - ), - Object( - :plant_2; - scale=:Plant, - status=Status(intercepted_par=6.0f0), - ); +plants = CompositeModel( + Object(:plant_1; scale=:Plant, status=Status(intercepted_par=10.0f0)), + Object(:plant_2; scale=:Plant, status=Status(intercepted_par=6.0f0)); applications=( - ModelSpec( - development; - name=:biomass_production, - on=Many(scale=:Plant), - ), + ModelSpec(model; name=:biomass_production, on=Many(scale=:Plant)), ), + environment=(duration=Day(1),), ) -final_state(run!(several_objects), Many(scale=:Plant)) +simulation = run!(plants) +result_1 = final_state(simulation, :plant_1).biomass_increment +result_2 = final_state(simulation, :plant_2).biomass_increment +@test (result_1, result_2) == (15.0f0, 9.0f0) +(plant_1=result_1, plant_2=result_2) ``` -Do not loop over objects inside `RadiationUseEfficiency.run!`. -PlantSimEngine compiles homogeneous targets and invokes the one-target kernel -for each selected object. - -## Continue the authoring path - -- [Port an existing model](@ref) explains the readable-kernel convention. -- [Model repository layout and tests](@ref) shows where to place alternatives, - documentation, and each test level. -- [Implement Cross-Object Values](@ref) adds `One`, `Many`, and `Subtree()` - bindings. -- [Coupling models](@ref) explains when `OptionalOne` is valid and - distinguishes value coupling, hard calls, and explicit physical adapters. -- [Model compatibility and replacement](@ref) checks whether another - hypothesis is genuinely substitutable. - -## Model-author recap - -- **You implemented:** one immutable parameter type, declared ports, complete - scientific contracts, and a continuous one-target kernel. -- **PlantSimEngine inferred:** initialization, target execution, and generic - status construction. -- **The scenario author keeps explicit:** object identities, target - multiplicity, initial radiation, cadence, and output retention. -- **New API names:** `AbstractModel`, `inputs_`, `outputs_`, - `variable_contracts_`, `VariableContract`, `Required`, `Status`, and `run!`. +PlantSimEngine calls the equation once for each selected plant. Each plant +keeps its own input and result, so you do not need to write a loop over plants +inside the model. + +## Continue with your own model + +- [Port an existing model](@ref): separate a calculation from its original script. +- [Model repository layout and tests](@ref): organize a package and its checks. +- [Implement Cross-Object Values](@ref): read another object's result or sum several. +- [Model compatibility and replacement](@ref): compare another hypothesis. +- [Loaded model catalog](@ref): discover and inspect models already loaded. diff --git a/docs/src/journeys/modelers/cross_object_values.md b/docs/src/journeys/modelers/cross_object_values.md index e14cd548c..f7bb971bc 100644 --- a/docs/src/journeys/modelers/cross_object_values.md +++ b/docs/src/journeys/modelers/cross_object_values.md @@ -1,21 +1,34 @@ # Implement Cross-Object Values -**New concept:** scalar and vector-like inputs use the same one-step kernel -contract. Object selection and topology remain scenario concerns. +A model reads its inputs from `status`, whether the values came from the +same object, another object, or several objects. The scenario chooses those +sources. This page shows what the model author writes in each case. -See [Build One Multiscale Plant](@ref) for the simulation-user construction -journey. +The equations and numbers below are teaching examples. For the corresponding +scenario walkthrough, see [Build One Multiscale Plant](@ref). -Every block below executes during the documentation build using the tested, -shipped example models. +## Read one value from another object -## Model 4: consume one scalar from another object +The development example calculates: -`ToyDevelopmentModel` already declares `stress=Default(1.0)`. A scenario may -replace that fallback with one live scalar from a soil object: +**growth increment = efficiency × thermal time × stress factor** + +Here is its actual input declaration and calculation, extracted from +`examples/ToyModelDeveloper.jl`: + +```@eval +Main.DocsSources.section( + "examples/ToyModelDeveloper.jl", + "PlantSimEngine.inputs_(::ToyDevelopmentModel)", + "\"\"\"\n ToyDailyDevelopmentModel", +) +``` + +`stress=Default(1.0)` means the model can run without stress reduction when +that is appropriate. A scenario can instead supply a soil object's value: ```@example modeler_cross_object -using Dates, PlantMeteo, PlantSimEngine, DataFrames +using Dates, Test, PlantSimEngine using PlantSimEngine.Examples cross_object = CompositeModel( @@ -27,131 +40,92 @@ cross_object = CompositeModel( name=:development, on=One(scale=:Leaf), inputs=( - :stress => One( - scale=:Soil, - within=SceneScope(), - var=:stress, - from_status=true, + stress=One( + scale=:Soil, within=SceneScope(), + var=:stress, from_status=true, ), ), ), ), ) -cross_simulation = run!(cross_object) -( - leaf=final_state(cross_simulation, :leaf), - binding=only(Diagnostics.explain_bindings(cross_object)), -) +simulation = run!(cross_object) +growth = final_state(simulation, :leaf).growth +@test growth == 2.0 +growth ``` -The model kernel still reads only `status.stress`. It does not search for soil, -know object ids, or copy the scalar each step. The scenario's `One` selector -resolves a shared `Ref`. +`from_status=true` reads the value we stored in the soil object's `Status`. +When a soil model calculates that value instead, select that model as described in +[Coupling models](@ref). The development equation itself stays unchanged. -## Model 5: consume a vector-like multiscale value +## Read several values and combine them -`ToyMaintenanceRespirationModel` runs once per leaf and publishes `Rm`. -`ToyPlantRmModel` declares one vector-like input and reduces it: +Suppose leaf respiration amounts are available for the same interval. A +plant-level model can add them: -```@example modeler_cross_object -plant_respiration = ToyPlantRmModel() -plant_status = Status(Rm_organs=[0.2, 0.3], Rm=-Inf) -PlantSimEngine.run!( - plant_respiration, - plant_status, - NamedTuple(), - nothing, - nothing, -) -( - inputs=PlantSimEngine.inputs_(plant_respiration), - outputs=PlantSimEngine.outputs_(plant_respiration), - total=plant_status.Rm, +**plant respiration = sum of leaf respiration** + +The model asks for a vector of real values and sums it. It does not need to +know how many leaves exist: + +```@eval +Main.DocsSources.section( + "examples/ToyMaintenanceRespirationModel.jl", + "struct ToyPlantRmModel", ) ``` -The scenario decides that `Rm_organs` means all descendant leaf outputs: +Test the equation with an ordinary vector first: ```@example modeler_cross_object -respiration = ToyMaintenanceRespirationModel( - 2.0, - 0.06, - 25.0, - 0.5, - 0.02, -) +plant_respiration = ToyPlantRmModel() +sample = Status(Rm_organs=[0.2, 0.3], Rm=0.0) +PlantSimEngine.run!(plant_respiration, sample, nothing, nothing, nothing) +@test sample.Rm == 0.5 +sample.Rm +``` -multiscale = CompositeModel( +## Choose which leaves contribute + +This scenario supplies two illustrative leaf amounts, then selects only the +leaves belonging to the plant: + +```@example modeler_cross_object +plant = CompositeModel( Object(:plant; scale=:Plant), - Object( - :leaf_1; - scale=:Leaf, - parent=:plant, - status=Status(carbon_biomass=10.0), - ), - Object( - :leaf_2; - scale=:Leaf, - parent=:plant, - status=Status(carbon_biomass=20.0), - ); + Object(:leaf_1; scale=:Leaf, parent=:plant, status=Status(Rm=0.2)), + Object(:leaf_2; scale=:Leaf, parent=:plant, status=Status(Rm=0.3)); applications=( ModelSpec( - respiration; - name=:maintenance, - on=Many(scale=:Leaf), - ), - ModelSpec( - ToyPlantRmModel(); - name=:plant_maintenance, + plant_respiration; + name=:plant_respiration, on=One(scale=:Plant), inputs=( - :Rm_organs => Many( - scale=:Leaf, - within=Subtree(), - application=:maintenance, - var=:Rm, + Rm_organs=Many( + scale=:Leaf, within=Subtree(), + var=:Rm, from_status=true, ), ), ), ), - environment=Atmosphere( - T=25.0, - Wind=1.0, - Rh=0.7, - duration=Hour(1), - ), -) - -multiscale_simulation = run!(multiscale) -( - plant=final_state(multiscale_simulation, :plant), - leaves=final_state(multiscale_simulation, Many(scale=:Leaf)), -) -``` - -```@example modeler_cross_object -select( - DataFrame(Diagnostics.explain_bindings(multiscale)), - :application_id, - :input, - :source_ids, - :carrier_kind, - :copy_semantics, + environment=(duration=Day(1),), ) +plant_result = final_state(run!(plant), :plant).Rm +@test plant_result == 0.5 +plant_result ``` -The `Many` carrier is a live `RefVector`; the aggregation kernel operates on an -`AbstractVector` and stays independent of object count and identity. +`Many` gathers the selected values so the model can read them like a vector. +`Subtree()` searches this plant and its descendants. With `scale=:Leaf`, +only its leaves contribute, so another plant's leaves are not included. -## Model-author recap +Before adding real leaf values, check that they use the same units and time +interval. Also check whether they describe a whole leaf or one square metre +of leaf area. For values per square metre, multiply each value by its leaf's +area before adding them to obtain a plant total. -- **You implemented:** scalar or vector-compatible input schemas and ordinary - one-step arithmetic. -- **PlantSimEngine inferred:** shared `Ref` and `RefVector` carriers plus - producer-before-consumer order. -- **The scenario author keeps explicit:** cross-object scope, multiplicity, - source application, and variable remapping. -- **New API names:** `One`, `Many`, `SceneScope`, `Subtree`, `from_status`, - `RefVector`, and `input_carrier`. +Use `Diagnostics.explain_bindings(plant)` to check which leaves supply the +values. PlantSimEngine keeps the inputs connected to those leaves' current +results. The equation only needs to add the values; it does not need to look +up individual leaves or count them. diff --git a/docs/src/journeys/modelers/environment_and_cadence.md b/docs/src/journeys/modelers/environment_and_cadence.md index a8b927ac6..cfa4a30a7 100644 --- a/docs/src/journeys/modelers/environment_and_cadence.md +++ b/docs/src/journeys/modelers/environment_and_cadence.md @@ -1,142 +1,106 @@ # Implement Environment And Cadence Traits -**New concept:** model-authored runtime traits. Environment declarations name -the fields a kernel samples, while cadence and output-policy traits state when -the same kernel runs and how its values cross clocks. +A model may need air temperature or may be intended to run once a day. +Describe these requirements alongside the model's equation. The simulation +setup then chooses where the temperature comes from and how often the model +runs. This update frequency is also called its **cadence**. -Simulation users configure providers in [Understand Environments](@ref) and -application clocks in [Give Models Different Cadences](@ref). +Start with [Understand Environments](@ref) and +[Give Models Different Cadences](@ref) for the scenario-user perspective. -## Model 6: declare sampled environment inputs +## Declare an environmental input -`ToyMaintenanceRespirationModel` reads object state and sampled temperature. -The tested contract names that environment field explicitly: +This teaching model simply copies the environmental temperature to an output. +It shows how to read environmental data before adding a biological equation. +These are its actual definitions in `examples/ToySpatialEnvironment.jl`: -```@example modeler_environment_time -using Dates, PlantMeteo, PlantSimEngine, DataFrames -using PlantSimEngine.Examples - -respiration = ToyMaintenanceRespirationModel( - 2.0, - 0.06, - 25.0, - 0.5, - 0.02, -) -( - inputs=PlantSimEngine.inputs_(respiration), - environment_inputs=PlantSimEngine.environment_inputs_(respiration), - environment_outputs=PlantSimEngine.environment_outputs_(respiration), - outputs=PlantSimEngine.outputs_(respiration), +```@eval +Main.DocsSources.section( + "examples/ToySpatialEnvironment.jl", + "struct ToyEnvironmentReaderModel", + "\"\"\"\n ToyEnvironmentControllerModel", ) ``` -The kernel reads model parameters from `model`, object state from `status`, and -forcing from `environment`: +`environment_inputs_` declares `T`, and `run!` reads it from +`environment.T`. The model does not need to know whether the temperature +comes from a weather file or varies with position in the canopy. + +Test that read directly: ```@example modeler_environment_time -direct_status = Status(carbon_biomass=10.0, Rm=-Inf) -PlantSimEngine.run!( - respiration, - direct_status, - (T=25.0,), - nothing, - nothing, -) -direct_status +using Dates, Test, PlantSimEngine +using PlantSimEngine.Examples + +reader = ToyEnvironmentReaderModel() +sample = Status(temperature_seen=0.0) +PlantSimEngine.run!(reader, sample, (T=25.0,), nothing, nothing) +@test sample.temperature_seen == 25.0 +sample.temperature_seen ``` +Then supply an environment through the simulation: + ```@example modeler_environment_time model = CompositeModel( - Object( - :leaf; - scale=:Leaf, - status=Status(carbon_biomass=10.0), - ); - applications=( - ModelSpec( - respiration; - name=:maintenance, - on=One(scale=:Leaf), - ), - ), - environment=Atmosphere( - T=25.0, - Wind=1.0, - Rh=0.7, - duration=Hour(1), - ), -) - -( - declared=PlantSimEngine.environment_inputs_(respiration), - final=final_state(run!(model)), + reader; + environment=(T=25.0, duration=Hour(1)), ) +result = final_state(run!(model)).temperature_seen +@test result == 25.0 +result ``` -The model does not name a provider or inspect raw weather storage. -`Environment(...)` remains scenario configuration. +A scientific model should also declare the temperature's units and meaning +with `variable_contracts_`, as in [Implement a basic model](@ref). +Use [Port an existing model](@ref) for an equation that combines environmental +temperature with object state. -## Model 7: declare cadence and output semantics +## Give a model a default cadence -`ToyDailyDevelopmentModel` accumulates one increment whenever it runs. Its -model-level traits say “every 24 simulation steps, starting at step 1” and -“consumers may hold the last daily value between publications”: +The next teaching model adds a fixed increment whenever it runs. By default, +it runs every 24 simulation steps. Other models can keep reading its latest +result until it runs again: -```@example modeler_environment_time -daily = ToyDailyDevelopmentModel(2.0) -( - clock=PlantSimEngine.timespec(daily), - outputs=PlantSimEngine.output_policy(daily), +```@eval +Main.DocsSources.section( + "examples/ToyModelDeveloper.jl", + "PlantSimEngine.inputs_(::ToyDailyDevelopmentModel)", ) ``` -`ClockSpec` is expressed in simulation steps. Use -`ModelSpec(...; every=Day(1))` when a scenario should express a -duration-relative cadence or override the model default. +`timespec` sets the default update frequency. `output_policy` describes how +other models read the result between updates. Here `HoldLast` tells them to +use the latest available value; it does not run this equation again. + +`ClockSpec(24.0, 1.0)` means every 24 base steps, starting at step 1. It +corresponds to a day only when the base step is an hour. In a scenario, +`every=Day(1)` expresses the intended duration directly: ```@example modeler_environment_time +daily = ToyDailyDevelopmentModel(2.0) daily_model = CompositeModel( Object(:plant; scale=:Plant); applications=( ModelSpec( - daily; - name=:daily_development, - on=One(scale=:Plant), + daily; name=:daily_development, on=One(scale=:Plant), + every=Day(1), ), ), - environment=[ - (duration=Hour(1),) - for _ in 1:25 - ], + environment=[(duration=Hour(1),) for _ in 1:25], ) -daily_simulation = - run!(daily_model; steps=25, outputs=:all) -( - traits=( - clock=PlantSimEngine.timespec(daily), - outputs=PlantSimEngine.output_policy(daily), - ), - schedule=DataFrame(Diagnostics.explain_schedule(daily_model)), - final=final_state(daily_simulation), - retained=DataFrame( - Diagnostics.explain_outputs(daily_simulation), - ), -) +daily_simulation = run!(daily_model; steps=25, outputs=:all) +growth = final_state(daily_simulation).daily_growth +@test growth == 4.0 +growth ``` -The model runs at steps 1 and 25. A downstream application can override -`HoldLast` with an explicit selector policy when its scientific interpretation -requires `Integrate`, `Aggregate`, or `Interpolate`. - -## Model-author recap +The model runs at steps 1 and 25, adding 2 each time. When connecting another +model, you can choose to average or add results over an interval instead of +keeping the last value. The choice depends on what the variable represents; +see [Give Models Different Cadences](@ref). -- **You implemented:** declared environment reads, a model default clock, and - per-output temporal meaning. -- **PlantSimEngine inferred:** environment validation/sampling, execution - steps, and the default cross-clock policy. -- **The scenario author keeps explicit:** concrete environment provider, - simulation base step, cadence overrides, and input-policy overrides. -- **New API names:** `environment_inputs_`, `timespec`, `ClockSpec`, - `output_policy`, and `HoldLast`. +Give a model a default update frequency only when its equations require one. +Choose weather data, timing for a particular study, and results to save in +the simulation setup. diff --git a/docs/src/journeys/modelers/hard_dependencies.md b/docs/src/journeys/modelers/hard_dependencies.md index 2e3307487..e92ae156e 100644 --- a/docs/src/journeys/modelers/hard_dependencies.md +++ b/docs/src/journeys/modelers/hard_dependencies.md @@ -1,131 +1,111 @@ # Implement A Hard Dependency -**New concept:** a process-level hard dependency, used only when the parent -kernel must control another model's execution. Value dependencies should stay -in `inputs_`. +Use a **hard dependency** when one model must decide when or how often another +model runs. For example, an energy-balance calculation may evaluate gas +exchange at several trial temperatures before accepting a solution. -Simulation users wire and inspect advanced calls in -[Control Advanced Execution](@ref). +When a model only needs another model's result, use an ordinary input instead. +[Coupling models](@ref) explains the difference, and +[Control Advanced Execution](@ref) covers scenario configuration. -The examples below execute the shipped, tested -`ToySelectiveCallControllerModel`. +## Declare the model you need to call -## Model 8: declare and execute the call +The teaching model below acts as a **controller**: it chooses when to run +another model. It selects one leaf, tries two prescribed temperatures, and +finally accepts a third. This shows how to run trials; it does not solve an +energy-balance equation. -`ToySelectiveCallControllerModel` declares a reusable default by process, -scale, and relative scope. It cannot know future application names: +Its declaration asks for temperature-reading models on the current plant's leaves. +These definitions are extracted from `examples/ToyAdvancedControl.jl`: -```@example modeler_hard_dependency -using PlantSimEngine, DataFrames -using PlantSimEngine.Examples +```@eval +Main.DocsSources.section( + "examples/ToyAdvancedControl.jl", + "PlantSimEngine.dep(::ToySelectiveCallControllerModel)", + "function PlantSimEngine.outputs_", +) +``` -controller = ToySelectiveCallControllerModel( - (28.0, 31.0), - 22.0; - selected_object=:sun_leaf, +`Call` declares which models the controller needs. The controller chooses +when to run them. Asking for a process on the current plant's leaves lets +you reuse it without knowing the names a future simulation will give those +model applications. + +## Run trials and accept one result + +Here is the actual controller calculation: + +```@eval +Main.DocsSources.section( + "examples/ToyAdvancedControl.jl", + "function PlantSimEngine.run!(\n model::ToySelectiveCallControllerModel,", + "\"\"\"\n ToyStockWriterModel", ) -PlantSimEngine.dep(controller) ``` -Inside `run!`, the controller inspects the vector-like target collection, -restricts the declared call by object id, runs trials with `publish=false`, and -publishes one accepted execution with `publish=true`. The complete scenario -below executes that real kernel, so this page does not duplicate an untested -source excerpt. +`call_targets` lists the models and objects that match the `Call` declaration. +Each match is called a **target**. Here the controller chooses the target for +one leaf. Each trial uses `publish=false`, so its result is not saved as an +accepted output sample. The final call uses `publish=true` to save the +accepted result for output history and time-based connections. + +For a real solver, you must decide how to calculate each trial and when a +solution is close enough. You must also handle any values changed by a +rejected trial: `publish=false` does not restore them automatically. -The shipped model is exercised by the example-model contract suite. Build a -scenario without a `calls` keyword to use that model default: +## Compose a small scenario ```@example modeler_hard_dependency +using Test, PlantSimEngine +using PlantSimEngine.Examples + +controller = ToySelectiveCallControllerModel( + (28.0, 31.0), 22.0; selected_object=:sun_leaf, +) environment = ToySpatialEnvironment( - Dict( - :sun => (T=26.0,), - :shade => (T=18.0,), - ); + Dict(:sun => (T=26.0,), :shade => (T=18.0,)); step_seconds=3600.0, ) model = CompositeModel( Object(:plant; scale=:Plant), - Object( - :sun_leaf; - scale=:Leaf, - parent=:plant, - geometry=(cell=:sun,), - ), - Object( - :shade_leaf; - scale=:Leaf, - parent=:plant, - geometry=(cell=:shade,), - ); + Object(:sun_leaf; scale=:Leaf, parent=:plant, geometry=(cell=:sun,)), + Object(:shade_leaf; scale=:Leaf, parent=:plant, geometry=(cell=:shade,)); applications=( ModelSpec( ToyEnvironmentReaderModel(); - name=:reader, - on=Many(scale=:Leaf), + name=:reader, on=Many(scale=:Leaf), environment=Environment(backend=environment), ), - ModelSpec( - controller; - name=:controller, - on=One(scale=:Plant), - ), + ModelSpec(controller; name=:controller, on=One(scale=:Plant)), ), ) - -DataFrame(Diagnostics.explain_calls(model)) -``` - -```@example modeler_hard_dependency simulation = run!(model; outputs=:all) +accepted = final_state(simulation, :plant) +@test accepted.trial_temperature_seen == 31.0 +@test accepted.accepted_temperature_seen == 22.0 ( - controller=final_state(simulation, :plant), - leaves=final_state(simulation, Many(scale=:Leaf)), - publications=filter( - row -> row.application_id == :reader, - DataFrame(Diagnostics.explain_outputs(simulation)), - ), + last_trial=accepted.trial_temperature_seen, + accepted=accepted.accepted_temperature_seen, ) ``` -`origin=:model_default` identifies the `dep(model)` contract. A concrete -scenario can replace it with `ModelSpec(...; calls=...)` when application -identity or target selection differs. - -## Keep the common path bulk and concrete - -The selective example above intentionally materializes one public target -because it chooses an object and gives each trial its own sampled value. If the -algorithm executes every resolved target with the same already-sampled -environment, use the bulk `run_call!` path with `context`, `:readers`, -`sampled_environment=environment`, and `publish=false`. - -This executes the compiler's cached typed batches directly. It avoids creating -or indexing `CallTarget` wrappers inside a timestep loop. - -Some iterative algorithms must inspect a singular dependency model before -executing it. Keep that dispatch concrete with -`reader_model = call_model(context, :reader)`, let the application build its -own scientifically meaningful trial state from that concrete model, then -execute the same declared call in bulk. PlantSimEngine does not define or infer -that application-specific trial builder. - -`call_model` requires exactly one resolved target. Use `call_targets` when the -algorithm also needs target status, object selection, a custom order, or -several distinct sampled environments. - -The dependency definition is immutable after compilation, while its selected -objects are not. Growth, removal, and reparenting refresh the affected target -buffers once at the lifecycle barrier; normal timesteps continue through the -same compiled plan. - -## Model-author recap - -- **You implemented:** a process-level `Call` requirement and explicit - execution inside the parent kernel. -- **PlantSimEngine inferred:** call-only scheduling, resolved targets, nested - context, and publication boundaries. -- **The scenario author keeps explicit:** application overrides and any - architecture-specific target choice. -- **New API names:** `dep`, `Call`, `call_model`, `call_targets`, - `CallTargets`, `run_call!`, `sampled_environment`, and `publish`. +The controller's `dep` declaration describes the models it calls by default. +To choose different models or objects in a simulation, set +`ModelSpec(...; calls=...)`. Use `Diagnostics.explain_calls(model)` to check +which models and objects were selected. + +## Choose the simplest call operation + +| Your algorithm needs… | Use | +|---|---| +| To run all selected models and objects | `run_call!(context, :readers)` | +| To read one called model's parameters or type | `call_model(context, :reader)` | +| To choose objects, read their current values, or give them different trial values | `call_targets(context, :readers)`, then call the selected target | + +`call_model` requires exactly one match. If you have already prepared the +environmental values that all selected objects should use, pass them as +`sampled_environment=value` to `run_call!`. + +When objects are added, removed, or moved to a different parent through the +PlantSimEngine functions, the selection is updated. Use the call functions +above so your controller uses that updated selection. diff --git a/docs/src/journeys/modelers/mutable_environment.md b/docs/src/journeys/modelers/mutable_environment.md index 5b233ffdf..1e7a10739 100644 --- a/docs/src/journeys/modelers/mutable_environment.md +++ b/docs/src/journeys/modelers/mutable_environment.md @@ -1,109 +1,107 @@ # Implement A Mutable Environment Controller -**New concept:** accepted mutable environment state. A controller declares -which variables it may commit, evaluates typed trial states, and commits one -accepted state explicitly. - -Simulation users first encounter this workflow in -[Modify The Environment](@ref). Backend packages implement the separate -[Environment Backend Extensions](@ref) contract. - -The examples below execute the shipped, tested -`ToyEnvironmentControllerModel`. +Some models also change their environment. A canopy energy-balance model, +for example, may try several temperatures before deciding which temperature +other models should use. A model that manages these trials is called a +**controller**. + +This teaching example uses prescribed temperatures to explain that sequence. +It does not implement a physical canopy solver. Start with +[Modify The Environment](@ref) for the scenario perspective and +[Implement A Hard Dependency](@ref) for model calls. + +## Declare the accepted values you can write + +A controller declares both the model it calls and the environmental variables +it may update. Here `environment_outputs_` names temperature `T`. These are +the actual declarations in `examples/ToySpatialEnvironment.jl`: + +```@eval +Main.DocsSources.section( + "examples/ToySpatialEnvironment.jl", + "PlantSimEngine.inputs_(::ToyEnvironmentControllerModel)", + "function PlantSimEngine.run!(\n model::ToyEnvironmentControllerModel,", +) +``` -## Model 9: declare commit permission +The variables in `outputs_` record the temperatures seen during the +calculation. The variable in `environment_outputs_` is the temperature the +controller may change in the shared environment. -`ToyEnvironmentControllerModel` declares its reader hard dependency and the -environment variable it may commit: +## Evaluate a trial, then commit an accepted state -```@example modeler_mutable_environment -using PlantSimEngine, DataFrames -using PlantSimEngine.Examples +The controller's implementation makes the sequence explicit: -controller = ToyEnvironmentControllerModel(30.0, 22.0) -( - dependency=PlantSimEngine.dep(controller), - commit_schema=PlantSimEngine.environment_outputs_(controller), +```@eval +Main.DocsSources.section( + "examples/ToySpatialEnvironment.jl", + "function PlantSimEngine.run!(\n model::ToyEnvironmentControllerModel,", ) ``` -Its tested kernel keeps trial, commit, and accepted publication separate. It -runs the reader against the trial environment with `publish=false`, calls -`commit_environment!` only for the accepted environment, then publishes one -accepted reader execution. The complete scenario below executes that source -instead of repeating it as an unchecked excerpt. +The first call gives the reader a trial temperature. Its result is not saved +as an accepted output sample. `commit_environment!` then stores the accepted +temperature in the shared environment. The final reader call saves the +result calculated at that temperature. -`environment_outputs_` is commit permission, not object-status output. -PlantSimEngine validates that the accepted state provides every declared -variable before invoking the backend through the controller's compiled handle. +For a scientific controller, you must choose how to calculate trials and +when to accept a solution. You must also handle any values changed by a +rejected trial: `publish=false` does not restore them automatically. -## Compose the controller +## Connect the controller to a provider -The reader needs only a provider. The controller additionally receives -`sink=:cells`; the backend defines what that sink means: +An **environment provider** supplies data such as temperature to the models. +This example stores temperature in a named canopy cell. The reader can read +that temperature. The controller also gets `sink=:cells`, which allows it to +write accepted temperatures into the provider's cells. ```@example modeler_mutable_environment +using Test, PlantSimEngine +using PlantSimEngine.Examples + environment = ToySpatialEnvironment( - Dict(:canopy => (T=20.0,)); - step_seconds=3600.0, + Dict(:canopy => (T=20.0,)); step_seconds=3600.0, ) +controller = ToyEnvironmentControllerModel(30.0, 22.0) model = CompositeModel( - Object( - :leaf; - scale=:Leaf, - geometry=(cell=:canopy,), - ); + Object(:leaf; scale=:Leaf, geometry=(cell=:canopy,)); applications=( ModelSpec( ToyEnvironmentReaderModel(); - name=:reader, - on=One(scale=:Leaf), + name=:reader, on=One(scale=:Leaf), environment=Environment(backend=environment), ), ModelSpec( controller; - name=:controller, - on=One(scale=:Leaf), - environment=Environment( - backend=environment, - sink=:cells, - ), + name=:controller, on=One(scale=:Leaf), + environment=Environment(backend=environment, sink=:cells), ), ), ) -( - call=DataFrame(Diagnostics.explain_calls(model)), - environment=DataFrame( - Diagnostics.explain_environment_bindings(model), - ), -) -``` - -```@example modeler_mutable_environment simulation = run!(model; outputs=:all) +state = final_state(simulation) +@test state.trial_temperature_seen == 30.0 +@test state.accepted_temperature_seen == 22.0 +@test environment.cells[:canopy].T == 22.0 ( - final=final_state(simulation), - committed=environment.cells[:canopy], - publications=filter( - row -> row.application_id == :reader, - DataFrame(Diagnostics.explain_outputs(simulation)), - ), + trial=state.trial_temperature_seen, + accepted=state.accepted_temperature_seen, + committed_temperature=environment.cells[:canopy].T, ) ``` -The rejected `T=30` trial mutates only the reader's trial status. The accepted -`T=22` state is committed once and produces the reader's only retained sample. -If the controller itself runs as an unpublished ancestor call, PlantSimEngine -also suppresses its descendant publications and environment writes. - -## Model-author recap - -- **You implemented:** declared commit variables, typed trial construction, - acceptance logic, explicit commit, and one accepted publication. -- **PlantSimEngine inferred:** permission validation, backend/handle routing, - nested trial suppression, and retained output history. -- **The scenario author keeps explicit:** provider, commit sink, concrete - backend, and any hard-call override. -- **New API names:** `environment_outputs_`, `commit_environment!`, - `Environment`, `environment`, and `publish`. +The temperature starts at 20, the trial uses 30, and the accepted value is 22. +Use `Diagnostics.explain_environment_bindings(model)` to check where models +read and write environmental data. `Diagnostics.explain_outputs(simulation)` +shows the saved results. + +When accepting a solution, supply a value for every variable declared in +`environment_outputs_`. If another controller calls this one as a trial with +`publish=false`, none of its nested calls can save accepted output samples +or change the shared environment. + +To add a new kind of spatial environment provider, see +[Environment Backend Extensions](@ref). When writing a process model, you +can normally use an existing provider through `Environment` and the call +and commit functions shown here. diff --git a/docs/src/journeys/users/advanced_execution.md b/docs/src/journeys/users/advanced_execution.md index b7db5eea3..948cad334 100644 --- a/docs/src/journeys/users/advanced_execution.md +++ b/docs/src/journeys/users/advanced_execution.md @@ -1,17 +1,20 @@ # Control Advanced Execution -## New concept: parent-controlled execution and explicit publication +## Let one model control another's calculations -Most coupling should remain a value dependency through `inputs`. Use a hard -call only when a parent algorithm must decide whether, when, or how often -another model runs—for example, while iterating toward an accepted leaf -temperature. +Use `inputs` when a model simply needs a value calculated by another model. +Sometimes a model also needs to control when the other model runs, or repeat +its calculation several times. For example, a heat-balance solver might try +several leaf temperatures before accepting a result. PlantSimEngine calls +this a **hard call**. You declare it with `calls` and run it with `run_call!`. -## Declare parent-controlled targets +## Choose which models the controller can call -Start with one plant and two leaves. The reader application is selected by the -controller's `calls` declaration, so it is call-only rather than independently -scheduled: +Start with one plant and two leaves. A controller on the plant can call a +temperature reader on either leaf. In this example, the readers run only when +the controller calls them; the simulation does not also run them separately. +The `Diagnostics.explain_calls` table shows which leaves the controller can +call: ```@example journey_advanced_execution using PlantSimEngine, DataFrames @@ -77,16 +80,18 @@ select( ) ``` -`run_call!(context, :readers)` executes every resolved target and returns a -vector-like `CallTargets` collection. `One` still returns a collection of one; -`OptionalOne` returns zero or one; `Many` returns zero or more. +`run_call!(context, :readers)` runs the reader for every selected leaf and +returns a `CallTargets` collection that you can loop over. Even `One` returns +a collection, containing one target. `OptionalOne` returns zero or one target; +`Many` returns zero or more. -## Inspect, select, iterate, then publish once +## Try several values and save the accepted result -`ToySelectiveCallControllerModel` needs different treatment per target, so its -kernel first calls `call_targets(context, :readers)` without executing -anything. It records the total, restricts the same declared call to -`:sun_leaf`, runs two temperature trials, and accepts one result: +The controller in this example wants to run only the sun leaf's reader. +`call_targets(context, :readers)` lists the available targets without running +them. The controller counts both leaves, selects `:sun_leaf`, tries two +temperatures, then records one accepted result. The repeated calls follow +this pattern: ```@example journey_advanced_execution function run_selected_trials!( @@ -109,9 +114,10 @@ function run_selected_trials!( end ``` -`publish=false` is the default. Trials may update the called model's current -status for convergence checks, but they neither append output samples nor -commit mutable environment state. Publish exactly the accepted execution. +`publish=false` is the default. Each trial updates the called model's status, +so the controller can inspect it and decide whether to continue. The trial +does not add a result to the output history or save changes to the environment. +Use `publish=true` for the accepted calculation. ```@example journey_advanced_execution simulation = run!(model; outputs=:all) @@ -121,11 +127,11 @@ simulation = run!(model; outputs=:all) ) ``` -The controller resolved two targets but selected only `:sun_leaf`. Object -selection uses `call_targets(context, name; objects=(ObjectId(:sun_leaf),))`; -it does not depend on iteration order. Two trials -left no history; its accepted call published once, while `:shade_leaf` was -never executed: +The controller found two leaves but ran only `:sun_leaf`. It selects that leaf +by name with `call_targets(context, name; objects=(ObjectId(:sun_leaf),))`, +so changing the order of the leaves would not change the selection. The two +trials were not recorded. The accepted calculation recorded one result, and +the reader on `:shade_leaf` did not run: ```@example journey_advanced_execution filter( @@ -134,21 +140,28 @@ filter( ) ``` -Use `run_call!(context, name; environment=trial_state)` when every target -should sample the same provider-aware trial state through its own compiled -handle. If the caller has already sampled the model-facing environment, use -`run_call!(context, name; sampled_environment=value)` to execute all targets -through cached typed batches. Use `call_targets` and -`run_call!(target; sampled_environment=...)` only for selection, custom order, -status inspection, or distinct already-sampled environments. For one target, -`call_model(context, name)` provides allocation-free access to its concrete -model when an algorithm must dispatch on model type or read its parameters. +There are two ways to supply trial conditions: -## Order intentional duplicate writers +- `run_call!(context, name; environment=trial_state)` lets each target read + its own local values from the trial environment. Use this when, for example, + a trial canopy temperature field gives different values to different leaves. +- `run_call!(context, name; sampled_environment=value)` passes values you have + already chosen, such as `(T=22.0,)`, directly to all targets. -One canonical variable normally has one writer. Two applications that both -claim `stock` therefore fail compilation unless their relationship is -intentional and ordered. `Updates` makes that ownership explicit: +Both forms run all selected targets together. Use `call_targets` followed by +`run_call!(target; sampled_environment=...)` when you need to choose individual +targets, change their order, inspect their status, or give each one different +values. For a call with one target, `call_model(context, name)` gives access to +the model itself, for example to read a parameter. It preserves the concrete +model type and does not allocate memory. + +## Let two models update the same value + +Normally, only one model may set a given variable on an object. If two models +both set `stock`, PlantSimEngine needs to know which value to keep. If the +second model is meant to change the first model's result, use `Updates` to +specify their order. Without that instruction, this configuration is rejected +before either model runs: ```@example journey_advanced_execution writer_model = CompositeModel( @@ -184,10 +197,10 @@ select( ) ``` -`initial_stock` owns the first canonical write and `adjusted_stock` explicitly -updates it afterward. The alternative value is useful as a retained comparison -but must not replace canonical status, so `output_routing` marks it -`:stream_only`. +`initial_stock` sets `stock` first, then `adjusted_stock` changes it. The third +model calculates an alternative value that we want to keep for comparison. +`output_routing=(stock=:stream_only,)` records that alternative in its own +output history without replacing the object's `stock` value. ```@example journey_advanced_execution writer_simulation = run!(writer_model; outputs=:all) @@ -202,18 +215,9 @@ writer_simulation = run!(writer_model; outputs=:all) ) ``` -The canonical result is `8`; the three application-specific streams retain -`4`, `8`, and `99`. A stream-only output is not a fallback writer and is not -selected by an application-free `OutputRequest`; request its application -explicitly when retaining only selected outputs. - -## Page recap - -- **You added:** one declared hard call, selective trials, one accepted - publication, explicit update ordering, and one stream-only alternative. -- **PlantSimEngine inferred:** the call-only schedule, concrete targets, - canonical writer ownership, and update edge. -- **You keep explicit:** when each target runs, `publish`, per-target forcing, - intentional duplicate writers, and non-canonical streams. -- **New API names:** `calls`, `call_targets`, `run_call!`, `CallTargets`, - `Updates`, `output_routing`, and `:stream_only`. +The object's final `stock` is `8`. The three models' output histories keep +their respective values: `4`, `8`, and `99`. The `:stream_only` setting never +lets the alternative replace the stored `stock`, even if no other model sets +it. If you use `OutputRequest` to save selected results, name +`:alternative_stock` explicitly to retain its output; requesting `stock` +without an application name does not select this alternative. diff --git a/docs/src/journeys/users/cadences.md b/docs/src/journeys/users/cadences.md index 61eaeba03..9d34960bc 100644 --- a/docs/src/journeys/users/cadences.md +++ b/docs/src/journeys/users/cadences.md @@ -1,22 +1,25 @@ # Give Models Different Cadences -## New concept: application clocks and temporal input policies +## Run models at different intervals -Running a whole composite over many timesteps was introduced on the first -journey. This page changes one thing: applications no longer all run at the -environment base step. +Canopy development might need an update once a day, while light interception +needs one every hour. A model's **cadence** is how often it runs. This page +shows how an hourly light model uses a daily LAI value, then how to calculate +daily water uptake from hourly rates. -Choose a base step that divides every application cadence: hourly and -90-minute applications can share a 30-minute base step. A duration such as -`every=Minute(90)` on an hourly base step is rejected. Fixed durations include -subsecond periods; calendar months and adaptive timesteps are not application -cadences. +The simulation's **base step** is its smallest time interval. Each model's +cadence must be a whole number of base steps: hourly and 90-minute models can +share a 30-minute base step. PlantSimEngine rejects `every=Minute(90)` with +an hourly base step. You can use fixed durations, including fractions of a +second. Calendar months and timesteps that change during a run are not +supported as model cadences. ## Hold a daily state for an hourly model -Reuse the thermal-time, LAI, and light chain. The environment advances hourly; -thermal time and LAI run daily; light interception runs hourly. `HoldLast` -makes each hourly light execution read the latest published daily LAI. +Reuse the models that calculate thermal time, LAI, and absorbed light. The +weather advances hourly. Thermal time and LAI update daily, while light is +calculated every hour. `HoldLast` tells the light model to keep using the most +recent LAI value until a new one is calculated. ```@example journey_cadences using PlantSimEngine, Dates, DataFrames @@ -28,24 +31,24 @@ hourly_forcing = [ ] model = CompositeModel( - Object(:plant; scale=:Plant, kind=:plant); + Object(:canopy; scale=:Canopy, kind=:canopy, status=Status(TT_cu=600.0)); applications=( ModelSpec( ToyDegreeDaysCumulModel(); name=:degree_days, - on=One(scale=:Plant), + on=One(scale=:Canopy), every=Day(1), ), ModelSpec( ToyLAIModel(); name=:lai, - on=One(scale=:Plant), + on=One(scale=:Canopy), every=Day(1), ), ModelSpec( Beer(0.6); name=:light, - on=One(scale=:Plant), + on=One(scale=:Canopy), inputs=( :LAI => One( within=Self(), @@ -64,7 +67,26 @@ model = CompositeModel( simulation = run!(model; steps=25, outputs=:all) ``` -The schedule reports physical cadence in seconds and in base steps: +First inspect the outputs at the beginning of the run and around the daily +update. LAI is in m² of leaves per m² of ground; absorbed PAR is in μmol m⁻² +of ground s⁻¹. The initial 600 °C d is an illustrative development stage, +chosen so the LAI changes are visible. + +```@example journey_cadences +rows = collect_outputs(simulation; sink=DataFrame) +light_samples = rows[(rows.variable .== :aPPFD) .& in.(rows.timestep, Ref((1, 2, 24, 25))), + [:timestep, :value]] +light_samples +``` + +The daily models run at steps 1 and 25. They start at the beginning of the +simulation, so the first update does not wait for a whole day of weather. +The hourly light model uses the first LAI value until the next daily update. +If your equation needs a full preceding day, decide what it should do at the +start, before that history is available. + +Check how often each model runs, in seconds (`dt_seconds`) and in base steps +(`dt_steps`): ```@example journey_cadences select( @@ -75,8 +97,9 @@ select( ) ``` -The temporal binding is explicit even though the producer and consumer share -an object: +You can also check which rule each input uses to read earlier values. The LAI +input uses `HoldLast` because we chose it in `inputs` above. Sharing a canopy +object does not choose that rule for us: ```@example journey_cadences select( @@ -89,8 +112,8 @@ select( ) ``` -The daily applications publish at steps 1 and 25; the hourly application -publishes on all 25 steps: +There are two results for each daily model, at steps 1 and 25. The hourly +model has a result at every step. The `nsamples` column counts them: ```@example journey_cadences select( @@ -101,46 +124,28 @@ select( ) ``` -`HoldLast` is appropriate because LAI is a state: between daily updates, its -latest value remains meaningful. +`HoldLast` fits this example because LAI describes the canopy at a given time. +The daily development model assumes that LAI stays unchanged between updates. ## Integrate a rate into an amount -`Integrate(reducer)` can integrate rates using sample durations. The default -`Integrate()` only sums values; it does not multiply by elapsed time. The -explicit reducer below uses durations in seconds. If a leaf publishes a constant -rate in units per second, integrating 24 hourly samples produces a daily -amount. The consumer below sums the independently integrated amounts from two -leaves. +To turn a water-uptake rate into an amount, multiply each rate by the time it +represents, then add the amounts. `Integrate(reducer)` lets you supply that +calculation as a function, called a **reducer**. Be careful: `Integrate()` +without this function only adds the values; it does not multiply by time. + +The function below uses durations in seconds. For a rate in mg per second, +24 hourly values give a daily amount in mg. The plant then adds the amounts +from its two leaves. The constant rates are teaching values, not predictions +of water demand. + +Load the [teaching models](../../guides/time/teaching_models.jl). One copies a +leaf's supplied water-uptake rate; the other sums amounts from leaves. Their +source is shown in [Hourly, Daily, And Weekly Models](../../guides/time/hourly_daily_weekly.md). ```@example journey_cadences -PlantSimEngine.@process "cadence_hourly_flux" verbose = false -PlantSimEngine.@process "cadence_daily_amount" verbose = false - -struct CadenceHourlyFlux <: AbstractCadence_Hourly_FluxModel end -struct CadenceDailyAmount <: AbstractCadence_Daily_AmountModel end - -PlantSimEngine.inputs_(::CadenceHourlyFlux) = (rate=Required(Real),) -PlantSimEngine.outputs_(::CadenceHourlyFlux) = (flux=0.0,) -PlantSimEngine.run!( - ::CadenceHourlyFlux, - status, - environment, - constants, - context, -) = (status.flux = status.rate) - -PlantSimEngine.inputs_(::CadenceDailyAmount) = ( - leaf_amounts=Required(AbstractVector{<:Real}), -) -PlantSimEngine.outputs_(::CadenceDailyAmount) = (amount=0.0,) -PlantSimEngine.run!( - ::CadenceDailyAmount, - status, - environment, - constants, - context, -) = (status.amount = sum(status.leaf_amounts)) +include(joinpath(pkgdir(PlantSimEngine), "docs", "src", "guides", "time", "teaching_models.jl")) +using .TeachingTimeModels ``` ```@example journey_cadences @@ -150,31 +155,31 @@ flux_model = CompositeModel( :leaf_1; scale=:Leaf, parent=:plant, - status=Status(rate=1.0), + status=Status(rate_mg_s=1.0), ), Object( :leaf_2; scale=:Leaf, parent=:plant, - status=Status(rate=2.0), + status=Status(rate_mg_s=2.0), ); applications=( ModelSpec( - CadenceHourlyFlux(); + HourlyWaterRate(); name=:hourly_flux, on=Many(scale=:Leaf), every=Hour(1), ), ModelSpec( - CadenceDailyAmount(); + SumWaterAmounts(); name=:daily_amount, on=One(scale=:Plant), inputs=( - :leaf_amounts => Many( + :amounts_mg => Many( scale=:Leaf, within=Subtree(), application=:hourly_flux, - var=:flux, + var=:water_rate_mg_s, policy=Integrate((values, durations_seconds) -> sum(values .* durations_seconds)), window=Day(1), ), @@ -185,45 +190,45 @@ flux_model = CompositeModel( environment=[(duration=Hour(1),) for _ in 1:25], ) -flux_simulation = run!(flux_model; steps=25) -amount = final_state(flux_simulation, One(scale=:Plant)).amount +flux_simulation = run!(flux_model; steps=25, outputs=:all) +amount = final_state(flux_simulation, One(scale=:Plant)).water_amount_mg @assert amount == 259200.0 amount ``` -The result is `(1 + 2) × 24 × 3600 = 259200` rate-seconds. Use -`Aggregate(reducer)` instead when the desired quantity is a mean, minimum, -maximum, or another reduction of observations rather than a time integral. - -!!! note "Temporal policies and scientific contracts" - - This numerical example leaves variable contracts undeclared. In this - release, temporal policies do not transform `VariableContract` metadata: - connected ports must still declare identical contracts. A rate contract - and a total contract therefore cannot be connected directly through - `Integrate()`. - - For contracted models, put the rate-to-amount calculation in a named - adapter. Its incoming binding uses the producer's rate contract and its - output declares the amount contract consumed downstream. For a varying - rate, accumulate at the producer cadence or use a correctly averaged - rate; multiplying one held sample by a long duration is valid only when - the rate is constant over that interval. Keep contracts on both sides; - see [Coupling models](@ref). - -There is no same-step feedback cycle in either example, so -`PreviousTimeStep` is not needed. It should be introduced only when a real -scientific dependency intentionally reads the preceding step to break such a -cycle. - -## Page recap - -- **You added:** daily and hourly application clocks, `HoldLast` for a state, - and then `Integrate` for a rate. -- **PlantSimEngine inferred:** the base-step ratios, publication schedule, and - bounded temporal storage needed by the consumers. -- **You keep explicit:** each application cadence, the physical meaning of its - temporal policy, and the integration window. -- **New API names:** `every`, `HoldLast`, `Integrate`, `Aggregate`, - `window`, `Diagnostics.explain_schedule`, and - `Diagnostics.explain_outputs`. +The complete-day result is `(1 + 2) × 24 × 3600 = 259200 mg` of water. +The first execution has only one hour of available history, so it produces +10800 mg; step 25 has a complete 24-hour rolling window: + +```@example journey_cadences +water_rows = collect_outputs(flux_simulation; sink=DataFrame) +daily_rows = water_rows[water_rows.application_id .== :daily_amount, [:timestep, :value]] +@assert daily_rows.value == [10800.0, 259200.0] +daily_rows +``` + +Each window looks back over a fixed duration; it does not automatically start +at midnight. The +[weekly example](../../guides/time/hourly_daily_weekly.md) extends this same +calculation to seven days and checks the first result separately. Use +`Aggregate(reducer)` to calculate a mean, minimum, maximum, or another +statistic from the values in a window. + +!!! note "When models declare units and physical meaning" + + A `VariableContract` describes a variable's units and physical meaning. + The teaching models above do not declare these contracts. If your models + do declare them, the two sides of a connection must match. `Integrate()` + changes the values but does not change their declared contract, so it + cannot directly connect a rate contract to an amount contract. + + Instead, write a small conversion model. Its input declares the rate + contract, and its output declares the amount contract expected by the + next model. If the rate changes, calculate each amount when the rate + updates, or use a rate correctly averaged over the interval. Multiplying + one held value by a long duration is only correct when the rate stays + constant over that interval. See [Coupling models](@ref). + +Neither example needs `PreviousTimeStep`: no two models wait for each other's +result in the same step. Use that option only when an equation should read +the preceding step. See [Diagnosing Dependency Cycles](@ref) for an example. diff --git a/docs/src/journeys/users/environments.md b/docs/src/journeys/users/environments.md index d3ab194d7..470506b34 100644 --- a/docs/src/journeys/users/environments.md +++ b/docs/src/journeys/users/environments.md @@ -1,34 +1,23 @@ # Understand Environments -## New concept: declared sampling from global and spatial sources +## Give models weather and light -The first simulation used a weather file as supplied forcing. This page now -makes that contract explicit. A model declares the names it reads from its -model-facing environment: +An **environment** supplies values such as air temperature and incident light. +Here you will first use weather data whose column names differ from the names +your models expect. Then you will give a sunny canopy more light than a shaded +one. The models and weather values are chosen to explain these operations. + +## Match weather names to model inputs + +Suppose your weather data use the names `air_temperature` and `incident_par`, +but your models expect `T` and `Ri_PAR_f`. Use `sources` in `Environment(...)` +to say which weather variable supplies each model input. `provider=:global` +means that the weather values do not depend on the object's position. ```@example journey_environments using PlantSimEngine, Dates, DataFrames using PlantSimEngine.Examples -( - degree_days=PlantSimEngine.environment_inputs_( - ToyDegreeDaysCumulModel(), - ), - light=PlantSimEngine.environment_inputs_(Beer(0.6)), -) -``` - -`ToyDegreeDaysCumulModel` reads `environment.T`; `Beer` reads -`environment.Ri_PAR_f`. These are not status inputs and are not outputs owned -by the target object. - -## Global sampling and source names - -The source does not need to use the model-facing names. Here a global provider -has `air_temperature` and `incident_par`; `Environment(...; sources=...)` -remaps them for the two model applications. - -```@example journey_environments forcing = ( air_temperature=20.0, incident_par=300.0, @@ -36,12 +25,12 @@ forcing = ( ) global_model = CompositeModel( - Object(:plant; scale=:Plant, kind=:plant); + Object(:canopy; scale=:Canopy, kind=:canopy); applications=( ModelSpec( ToyDegreeDaysCumulModel(); name=:degree_days, - on=One(scale=:Plant), + on=One(scale=:Canopy), environment=Environment( provider=:global, sources=(T=:air_temperature,), @@ -50,12 +39,12 @@ global_model = CompositeModel( ModelSpec( ToyLAIModel(); name=:lai, - on=One(scale=:Plant), + on=One(scale=:Canopy), ), ModelSpec( Beer(0.6); name=:light, - on=One(scale=:Plant), + on=One(scale=:Canopy), environment=Environment( provider=:global, sources=(Ri_PAR_f=:incident_par,), @@ -71,8 +60,33 @@ global_state = final_state(global_simulation) (TT_cu=global_state.TT_cu, LAI=global_state.LAI, aPPFD=global_state.aPPFD) ``` -The environment diagnostic distinguishes the variables seen by each model from -the actual source names: +`T` and `air_temperature` are in °C. `Ri_PAR_f` and `incident_par` are +mean PAR fluxes in W m⁻² of ground; changing a source name does not convert +its units. `aPPFD` is absorbed PAR in μmol m⁻² of ground s⁻¹. + +## Inspect the input names + +A model declares which external values it needs. You can inspect those names +without changing the model: + +```@example journey_environments +using PlantSimEngine, Dates, DataFrames +using PlantSimEngine.Examples + +( + degree_days=PlantSimEngine.environment_inputs_( + ToyDegreeDaysCumulModel(), + ), + light=PlantSimEngine.environment_inputs_(Beer(0.6)), +) +``` + +`ToyDegreeDaysCumulModel` reads `environment.T`; `Beer` reads +`environment.Ri_PAR_f`. These values come from the weather data. They are +separate from values stored on the canopy, such as its LAI. + +The table below shows the names each model expects (`required_inputs`) and the +names it reads from the weather data (`source_inputs`): ```@example journey_environments select( @@ -85,17 +99,19 @@ select( ) ``` -Global sampling has no spatial handle. The forcing above is intentionally -strict: apart from timeline `duration`, it exposes only the two remapped source -variables. Removing either source makes `validate_environment_inputs` fail -before simulation. +The `handle` column is empty because neither model needs a spatial location +to read this weather. The example supplies only `duration` and the two weather +variables. If either weather variable is missing, +`validate_environment_inputs` reports it before you run the simulation. -## Spatial sampling +## Give each canopy its own light -Spatial backends keep the same model-facing declaration. They additionally -compile an opaque handle for each application/object target. The small -`ToySpatialEnvironment` example maps object geometry to either a sunny or -shaded cell: +When weather or light varies across space, an **environment backend** supplies +the values at each object's location. The models still read the same input +names. The small `ToySpatialEnvironment` example below stores a light value in +each of two cells, named `:sun` and `:shade`. Each canopy's `geometry` says +which cell to use. These light values are supplied directly; this example does +not calculate how light travels through a canopy. ```@example journey_environments spatial_environment = ToySpatialEnvironment( @@ -108,16 +124,16 @@ spatial_environment = ToySpatialEnvironment( spatial_model = CompositeModel( Object( - :sun_leaf; - scale=:Leaf, - kind=:leaf, + :sun_canopy; + scale=:Canopy, + kind=:canopy, geometry=(cell=:sun,), status=Status(LAI=2.0), ), Object( - :shade_leaf; - scale=:Leaf, - kind=:leaf, + :shade_canopy; + scale=:Canopy, + kind=:canopy, geometry=(cell=:shade,), status=Status(LAI=2.0), ); @@ -125,18 +141,24 @@ spatial_model = CompositeModel( ModelSpec( Beer(0.6); name=:light, - on=Many(scale=:Leaf), + on=Many(scale=:Canopy), environment=Environment(backend=spatial_environment), ), ), ) spatial_simulation = run!(spatial_model) -spatial_states = final_state(spatial_simulation, Many(scale=:Leaf)) +spatial_states = final_state(spatial_simulation, Many(scale=:Canopy)) Dict(id => state.aPPFD for (id, state) in spatial_states) ``` -The one `Many` application retains two distinct compiled handles: +Both canopies have LAI = 2 m² m⁻². The sunny canopy receives four times the +incident PAR of the shaded canopy, so its absorbed PAR is also four times +as large. Both results use ground area, not individual leaf area. + +The table below lets you check that each canopy reads from its intended cell. +PlantSimEngine stores this location in a value called a **handle**, so it does +not need to find the cell again at every step: ```@example journey_environments select( @@ -148,19 +170,6 @@ select( ) ``` -The scientific `Beer` kernel is unchanged. It sees only -`environment.Ri_PAR_f`; the backend owns the meaning of each handle. Backend -authors can inspect the implementation of `ToySpatialEnvironment` in the -environment extension reference. - -## Page recap - -- **You added:** explicit environment declarations, global source remapping, - and then a spatial backend with object geometry. -- **PlantSimEngine inferred:** global sampling, validation of required source - names, and one cached spatial handle per application/object target. -- **You keep explicit:** model-facing environment names, scenario source - remaps, provider/backend choice, and geometry used by a spatial backend. -- **New API names:** `environment_inputs_`, `Environment`, - `validate_environment_inputs`, `ToySpatialEnvironment`, and - `Diagnostics.explain_environment_bindings`. +The `Beer` equation is unchanged. It reads `environment.Ri_PAR_f` in both +examples; the environment supplies the correct value. To provide your own +spatial data, see [Environment Backend Extensions](@ref). diff --git a/docs/src/journeys/users/maespa_synthesis.md b/docs/src/journeys/users/maespa_synthesis.md index 3b298f3a1..ec64280b6 100644 --- a/docs/src/journeys/users/maespa_synthesis.md +++ b/docs/src/journeys/users/maespa_synthesis.md @@ -1,21 +1,27 @@ # MAESPA-Style Synthesis -## New concept: synthesis without another runtime mechanism - -This page is an integrated reference, not an onboarding example. It combines -the ideas developed independently in the earlier journeys into a small -MAESPA-style stand: two species, five leaves, hourly canopy and soil exchange, -daily allocation and LAI, iterative leaf calls, and accepted mutable canopy -air. - -If any individual mechanism is unfamiliar, follow its focused link in -[How the pieces compose](@ref) before reading the implementation. +Bring the earlier tutorials together in a small MAESPA-style stand with two +species and five leaves. Canopy and soil exchange run hourly; carbon +allocation and LAI run daily. Within each hour, a controller repeatedly runs +the leaf models to find a consistent canopy air temperature and humidity. +This is an advanced example; start with the individual tutorials if these +steps are unfamiliar. + +This is an uncalibrated teaching example inspired by MAESPA's process +structure. It is not a validated MAESPA implementation. Leaf illumination is +uniform with complete absorption, the canopy has one air layer, and the soil +water model uses prescribed withdrawals and bounds rather than a complete +soil hydraulic balance. The example tests coupling and carbon accounting; +its results should not be used to predict a real stand's behaviour. + +The table in [How the pieces compose](@ref) links each part of this example +to the tutorial that explains it. ## Run the reference case -The complete, tested source lives in -`examples/maespa_model_example.jl`. Run 25 hours so both hourly and daily -applications cross a day boundary: +The complete, tested source is in `examples/maespa_model_example.jl`. Run it +with 25 hourly weather records. The daily models run on the first step and +again 24 hours later, so this is long enough to see two calls: ```@example journey_maespa_synthesis using PlantSimEngine, DataFrames @@ -32,8 +38,9 @@ model = result.model nothing ``` -The model contains one scene, one soil object, and two template instances with -different species parameters and leaf counts: +The model contains one object for the whole scene, one soil object, and two +plants with the same model connections. Each plant has its own template, +species parameters, and number of leaves: ```@example journey_maespa_synthesis ( @@ -45,11 +52,13 @@ different species parameters and leaf counts: ) ``` -## Inspect the compiled architecture +## Check when models run and where their inputs come from -The execution schedule makes the two cadences and parent-controlled -applications visible. Leaf energy balance and soil water are call-only under -the scene controller; allocation and LAI run daily: +Check when each calculation runs. The scene controller decides when to call +leaf energy balance and soil water; these models do not run independently. +Allocation and LAI run once per day. In the table, `root_scheduled` means a +model runs directly from the simulation schedule, `manual_call_only` means +another model calls it, and `dt_steps` gives the interval in hourly steps: ```@example journey_maespa_synthesis schedule = DataFrame(Diagnostics.explain_schedule(result.compiled)) @@ -72,8 +81,10 @@ select( ) ``` -The scene energy-balance application resolves all five leaves through one -`Many` hard call and the soil through one `One` hard call: +The scene energy-balance model calls all five leaf models with `Many` and the +single soil model with `One`. These are **hard calls**: the calling model +controls when the other models run. The table lists the models and objects +called from `:scene_eb`: ```@example journey_maespa_synthesis calls = DataFrame(Diagnostics.explain_calls(result.compiled)) @@ -86,9 +97,14 @@ select( ) ``` -Each plant allocation application receives a live vector of only its own -descendant leaves. The scene receives stand-wide vectors and one scalar soil -potential: +Each plant's allocation model reads carbon values from its own leaves. The +scene model reads areas from all leaves and water potential from the soil. +Here `AllocA` and `AllocB` use the same fixed-fraction allocation equation +with different parameters. For two different allocation rules running on +two plants together, see [Instantiate Several Plants](several_plants.md). +Inspect `source_ids` below to check where each input comes from. The values +are shared by reference, meaning the reader sees the current source values +without copying them: ```@example journey_maespa_synthesis bindings = DataFrame(Diagnostics.explain_bindings(result.compiled)) @@ -115,11 +131,17 @@ select( ## Follow trial canopy air to its accepted state -The scene controller reads above-canopy `:forcing`, iterates leaf models -against typed trial canopy air with `publish=false`, commits the converged -state to `sink=:canopy`, and then publishes one accepted leaf execution. Leaf -applications read the committed `:canopy` provider. Those routes are compiled -into opaque handles: +The scene controller starts from the above-canopy weather, named `:forcing`. +It tries different canopy air conditions and runs the leaf models for each +trial with `publish=false`, so these intermediate results are not saved in +the output history. Once the calculation converges, it commits the accepted +air conditions with `sink=:canopy` and runs the leaves once more to publish +their accepted results. + +The leaf models then read the accepted conditions from `:canopy`. The table +below shows which environmental variables each model reads or changes. Its +`handle` column contains an internal identifier used to retrieve those +conditions; you do not need to interpret that identifier: ```@example journey_maespa_synthesis environment_bindings = DataFrame( @@ -142,16 +164,34 @@ select( ) ``` -`MaespaSingleLayerEnvironment` is intentionally a one-layer canopy backend. -Its handle still separates forcing, canopy, and commit-sink routes per -application/object. A voxel or multilayer backend can replace it without -changing the model-facing environment contract; the two-cell proof is in -[Modify The Environment](@ref), and backend implementation belongs in +`MaespaSingleLayerEnvironment` supplies one set of air conditions for the +whole canopy. It keeps the above-canopy weather separate from the canopy +conditions that the controller changes. You could replace it with an +environment that represents several layers or 3D cells, while keeping the +same variables available to the process models. See the two-cell example in +[Modify The Environment](@ref) and the implementation guide in [Environment Backend Extensions](@ref). -## Check the scientific handoffs +## Check units and carbon accounting + +Check the units and conversions as values pass between models: + +| Quantity | Meaning and units | +|---|---| +| `Ri_SW_f`, `Ri_PAR_f` | Incoming radiation in W m⁻²; PAR is `PlantMeteo.Constants().PAR_fraction` of shortwave energy. | +| Leaf `aPPFD` | Absorbed photon flux in µmol photons m[leaf]⁻² s⁻¹: `Ri_PAR_f * constants.J_to_umol`, assuming uniform illumination and complete absorption. | +| Leaf `A` | Net CO₂ assimilation in µmol CO₂ m[leaf]⁻² s⁻¹. | +| Leaf `leaf_carbon` | Cumulative net assimilation in g elemental C: sum of `A * leaf_area * duration_seconds * 12e-6`. | +| Plant `daily_growth` | Net C since this plant's previous allocation, in g C per allocation interval. The first call covers only the start of the simulation, not a full day. | +| Plant carbon pools | Allocated g elemental C, not g dry matter; the unassigned allocation fraction remains in `reserve_pool`. | +| `scene_transpiration` | Accepted water loss in mm over the current hourly forcing interval. | + +Every leaf receives the same above-canopy irradiance here. There is no +shading, scattering, or leaf-angle calculation; a radiation model would need +to replace that assumption for a realistic stand. -The final snapshots expose canonical state independently of retained history: +Use `final_state` to read the latest values, whether or not you saved their +history: ```@example journey_maespa_synthesis scene = final_state(simulation, :model) @@ -160,18 +200,43 @@ plants = final_state(simulation, Many(scale=:Plant)) ( lai=scene.lai, - canopy_temperature=scene.canopy_tair, - transpiration=scene.scene_transpiration, - soil_water_potential=soil.psi_soil, - daily_growth=Dict( + canopy_temperature_C=scene.canopy_tair, + hourly_transpiration_mm=scene.scene_transpiration, + soil_water_potential_MPa=soil.psi_soil, + allocation_interval_g_C=Dict( id => state.daily_growth for (id, state) in plants ), ) ``` -Retained output counts confirm the cadence boundary: hourly scene and leaf -variables have 25 samples, while daily LAI and allocation variables have two: +Allocation reads cumulative leaf C without resetting it. Each plant stores +the cumulative amount it has already accounted for and allocates only the +difference at the next daily call. This prevents the same carbon being +allocated again on later days. Carbon gained or lost since the last +allocation remains pending until the next one: + +```@example journey_maespa_synthesis +DataFrame([ + ( + plant=id, + cumulative_net_C_g=sum(state.leaf_carbon), + accounted_C_g=state.accounted_carbon, + pools_C_g=state.leaf_pool + state.wood_pool + state.reserve_pool, + pending_C_g=sum(state.leaf_carbon) - state.accounted_carbon, + ) + for (id, state) in plants +]) +``` + +At each allocation, the three pools sum to `accounted_carbon`. Adding pending +C recovers cumulative net assimilation. These accounts can increase or +decrease: negative net assimilation reduces them. The example does not model initial +biomass, construction respiration, dry-matter conversion, or limits on +withdrawing reserves, so the pools are not predictions of organ mass. + +Count the saved values to check how often the models ran. Hourly scene and +leaf variables have 25 samples; daily LAI and allocation variables have two: ```@example journey_maespa_synthesis output_summary = DataFrame(Diagnostics.explain_outputs(simulation)) @@ -198,45 +263,32 @@ select( ## How the pieces compose -| Construct in this synthesis | Role here | Focused journey | +| Part of the example | What it does here | Tutorial | |---|---|---| -| `CompositeModelTemplate` and two `ObjectInstance`s | Reuse one species-specific application set across several plants | [Instantiate Several Plants](@ref) | -| Scene, plant, internode, leaf, and soil objects | Represent one registry without prescribing plant architecture | [Build One Multiscale Plant](@ref) | -| Scalar and `Many` live-reference bindings | Couple soil-to-scene and leaf-to-plant/scene values | [Build One Multiscale Plant](@ref) | -| Hourly and daily applications with `HoldLast` | Keep canopy exchange and allocation on scientific cadences | [Give Models Different Cadences](@ref) | -| Forcing and canopy providers with compiled handles | Sample global forcing and committed canopy state through one contract | [Understand Environments](@ref) | -| Typed trials and explicit accepted commit | Iterate canopy air without publishing rejected states | [Modify The Environment](@ref) | -| Nested hard calls and accepted publication | Let scene energy balance control leaf and soil execution | [Control Advanced Execution](@ref) | -| `Simulation`, final state, and retained streams | Separate current canonical state from requested history | [Couple Models On One Object](@ref) | - -This 25-hour reference keeps plant topology fixed because organogenesis is not -part of its scientific question. A growth model can add, reparent, or remove -organs through the same registry and refresh machinery; that independent -lifecycle is demonstrated in [Modify Plant Structure](@ref). Keeping it out of -this synthesis prevents canopy iteration, daily allocation, and topology -mutation from becoming one inseparable example. - -## Reference invariants - -The automated example test verifies the important handoffs rather than exact -floating-point trajectories: - -- the stand contains two isolated instances and five correctly routed leaves; -- plant allocation vectors contain only descendant leaves; -- the scene call resolves every leaf and the shared soil application; -- hourly and daily output counts match their cadences; -- accepted canopy air is committed separately from above-canopy forcing; -- leaf fluxes are finite and aggregate consistently at scene scale; -- both species grow, while their parameterized allocations remain distinct. - -## Page recap - -- **You added:** no new primitive; you assembled the earlier topology, - cadence, hard-call, environment, and output mechanisms into one stand. -- **PlantSimEngine inferred:** application order, plant-local bindings, - concrete call targets, environment handles, and the hourly/daily schedule. -- **You keep explicit:** species parameters, topology, scientific iteration, - accepted state, output requests, and the invariants used to validate the - result. -- **New API names:** none. Every API in this synthesis was introduced on a - focused earlier journey. +| `CompositeModelTemplate` and two `ObjectInstance`s | Reuse the same models for plants with different species parameters | [Instantiate Several Plants](@ref) | +| Scene, plant, internode, leaf, and soil objects | Represent the chosen plant structure and shared soil | [Build One Multiscale Plant](@ref) | +| `One` and `Many` inputs | Read one soil value or a collection of leaf values | [Build One Multiscale Plant](@ref) | +| Hourly and daily models with `HoldLast` | Keep using the last daily value between daily calculations | [Give Models Different Cadences](@ref) | +| Above-canopy weather and canopy conditions | Supply each model with the environment it needs | [Understand Environments](@ref) | +| Trial air conditions and an accepted result | Find consistent canopy conditions, then save the accepted result | [Modify The Environment](@ref) | +| Hard calls | Let scene energy balance decide when leaf and soil models run | [Control Advanced Execution](@ref) | +| `Simulation`, `final_state`, and saved outputs | Read current values and analyse changes over time | [Couple Models On One Object](@ref) | + +Plant structure stays fixed during this 25-hour example. To add or remove +organs with a growth model, follow [Modify Plant Structure](@ref). + +## What the tests check + +The automated tests check that the parts work together as intended: + +- the stand contains two plants, with five leaves assigned to the right plant; +- each plant's allocation model reads only its own leaves; +- the scene controller calls every leaf and the shared soil model; +- hourly and daily output counts match their scheduled intervals; +- accepting new canopy conditions does not replace the above-canopy weather; +- leaf fluxes are finite and their totals agree with the scene results; +- PAR energy is bounded by shortwave energy and converted to photon units; +- a longer run with 73 hourly samples covers three daily intervals plus the + initial call, with no carbon added by rejected trial calculations; +- each plant allocates every C increment once, preserves cumulative leaf C, + and conserves the sum of its leaf, wood, reserve, and pending C accounts. diff --git a/docs/src/journeys/users/mental_model.md b/docs/src/journeys/users/mental_model.md index ffec0a6b2..fa80d89ca 100644 --- a/docs/src/journeys/users/mental_model.md +++ b/docs/src/journeys/users/mental_model.md @@ -1,55 +1,63 @@ # A Mental Model For PlantSimEngine -## New concept: composition - -PlantSimEngine is a framework for composing and running scientific models. It -does not prescribe a plant architecture, and it is not itself a library of -crop, tree, or organ equations. Model packages provide those equations; -PlantSimEngine connects them to simulated entities, orders their execution, and -manages time, environments, and retained results. - -Seven ideas are enough to read a PlantSimEngine simulation: - -| Idea | Meaning | -|:--|:--| -| **Process** | A scientific responsibility, such as thermal time or light interception | -| **Model** | One reusable implementation of a process | -| **Application** | One configured use of a model in a simulation | -| **Object** | A simulated entity with stable identity, such as a scene, plant, leaf, or soil layer | -| **Status** | The current values owned by an object | -| **Environment** | Values sampled from outside object status, such as weather or microclimate | -| **Simulation** | A running timeline, including the live model, current step, and any retained output streams | - -The distinction between a model and an application is important. A model -author writes an equation once. A simulation author can then apply it to one -whole plant, every leaf, selected soil layers, or several named groups without -putting an object loop inside the equation. - -Objects are equally general. Scales and parent/child links describe the -topology chosen by the simulation author; PlantSimEngine does not require a -particular hierarchy. A simple simulation can have one object. A detailed one -can have scenes, several plants, organs, voxels, and shared resources. - -Values reach a model in two ways: - -- status inputs come from the target object or from outputs of other model - applications; -- environment inputs are sampled from the environment selected for that - application and object. - -Before running, PlantSimEngine compiles applications into concrete -application/object targets, resolves value connections, and determines a valid -execution order. During the timestep loop, model kernels work with their own -parameters, the resolved status view, the sampled environment, constants, and -a runtime context. - -## Page recap - -- **You added:** no configuration yet—only the vocabulary used by every later - journey. -- **PlantSimEngine infers:** application order and unambiguous value - connections once a simulation is assembled. -- **You keep explicit:** scientific equations, object topology, ambiguous - cross-object connections, time policies, and requested output history. -- **New API names:** none yet. The next page introduces `CompositeModel`, - `run!`, `Simulation`, `final_state`, and `collect_outputs`. +PlantSimEngine connects scientific models and runs them together. For example, +one model can calculate the light absorbed by a canopy, and another can use +that light to calculate biomass production. You choose the equations and the +parts of the plant or environment they describe. + +This page explains the terms used in the guides. If you have not run an +example yet, start with [your first simulation](one_object.md). + +## Models describe calculations; objects describe what is simulated + +A **process** is something you want to calculate, such as photosynthesis or +light interception. A **model** provides the equations for that process. +Two models for the same process can use different equations or assumptions. + +An **object** represents something in your simulation: a leaf, a plant, a +canopy, or a soil layer, for example. Each object has a **status**, which +stores its current values, such as leaf area or water content. + +You decide how much detail to represent. A canopy can be one object, or it +can contain several plants with individual leaves. PlantSimEngine does not +require a particular plant structure. + +## An application says where and how to use a model + +A **model application** combines a model with instructions about where to run +it, how often to run it, and where to get its inputs. For example, you could +apply one photosynthesis model to every leaf and run it once an hour. + +You write the photosynthesis equation once. PlantSimEngine then runs it for +each selected leaf, using that leaf's own values and local conditions. You +can also apply different models to different groups of leaves or plants. + +In the [first simulation](one_object.md), all models describe the same canopy, +so `CompositeModel` creates these applications for you. Later guides use +`ModelSpec` to choose objects and connections explicitly. + +## Inputs come from object values or the environment + +A model needs **inputs** to calculate its **outputs**. For example, a +light-interception model reads LAI and calculates absorbed light. Another +model can then use that absorbed light as an input. + +Weather and local growing conditions are supplied through an **environment**. +This can be a weather table shared by the whole simulation, or a source of +local conditions that differ between leaves or soil layers. + +Before the simulation starts, PlantSimEngine checks where each input will +come from and puts the calculations in order. If a biomass model needs the +light model's result, the light model runs first. You can inspect these +connections in the [graph viewer](../../guides/graph_visualizer_editor.md). + +## A simulation keeps track of progress and results + +Calling `run!` starts a **simulation**. It keeps track of the current time +step and the current values for every object. It also saves the history of +the outputs you requested. + +Use `final_state` to read the latest values, `collect_outputs` to make a table +of saved results, and `step!` or `continue!` to advance the same simulation. +The [results guide](../../guides/data/outputs_plotting.md) shows how to select +and plot those outputs. diff --git a/docs/src/journeys/users/mutable_environments.md b/docs/src/journeys/users/mutable_environments.md index 6840a6214..7fce0d452 100644 --- a/docs/src/journeys/users/mutable_environments.md +++ b/docs/src/journeys/users/mutable_environments.md @@ -1,14 +1,21 @@ # Modify The Environment -## New concept: trial state versus accepted state +## Try a value before keeping it -The previous environment journey sampled read-only global and spatial values. -Now a controller evaluates one typed trial state, accepts a different state, -and commits it explicitly. +Some models need to try several temperatures before choosing a solution. +For example, a model might adjust canopy air temperature until its heat +balance is close enough to zero. A **controller** is a model that manages +these repeated calculations. -Start with one cell. `ToyEnvironmentReaderModel` declares `T` as an environment -input. The controller declares `T` as an environment output: this is permission -to commit that variable, not an ordinary object-status output. +This teaching example shows how to try one temperature, then keep a different +one. It does not solve a heat balance: the trial and final temperatures are +chosen in advance. **Committing** the final value means writing it back to +the environment so that later calculations can use it. + +Start with one spatial cell. `ToyEnvironmentReaderModel` reads temperature +`T` from the environment. The controller declares `T` with +`environment_outputs_` to say that it may change this environment variable. +This declaration does not add `T` to the leaf's stored status. ```@example journey_mutable_environment using PlantSimEngine, DataFrames @@ -24,9 +31,10 @@ using PlantSimEngine.Examples ) ``` -The controller's kernel uses the current typed trial-state path. A trial call -changes the callee status for inspection but does not publish output history or -commit backend state: +The first function asks the reader to calculate a result using a trial +environment. You can inspect that result in the reader's status. +`publish=false` prevents it from being added to the output history, and this +call does not change the stored environment: ```@example journey_mutable_environment function run_trial!(context, trial_environment) @@ -39,7 +47,9 @@ function run_trial!(context, trial_environment) end ``` -Accepted state is explicit and separate: +After choosing a final value, save it in the environment with +`commit_environment!`. Then run the reader with `publish=true` to record +its accepted result: ```@example journey_mutable_environment function commit_and_publish!(context, accepted_environment) @@ -53,9 +63,10 @@ function commit_and_publish!(context, accepted_environment) end ``` -`ToyEnvironmentControllerModel` applies those two operations in its kernel. -Configure the reader as its one hard-call target and give only the controller a -commit sink: +`ToyEnvironmentControllerModel` performs these two operations in its `run!` +function. The `calls` setting below lets it run the reader. Only the controller +has `sink=:cells`, which tells the environment where to save the accepted +temperature: ```@example journey_mutable_environment environment = ToySpatialEnvironment( @@ -104,8 +115,9 @@ state = final_state(simulation) ) ``` -The trial was `30`, but the accepted and committed temperature is `22`. -Only the accepted reader call published: +The reader tried 30 °C, then used the accepted value of 22 °C. The environment +now stores 22 °C. The table below shows that the reader recorded only its +accepted result: ```@example journey_mutable_environment select( @@ -116,10 +128,11 @@ select( ) ``` -## Preserve distinct handles under `Many` +## Give each leaf its own local conditions -Extend the same backend to two spatial cells. One `Many` application samples -both, while each target retains its own compiled handle: +Now give one leaf a sunny cell and the other a shaded cell. `Many(scale=:Leaf)` +runs the same reader on both leaves, but each leaf reads its own cell's +temperature: ```@example journey_mutable_environment spatial_environment = ToySpatialEnvironment( @@ -156,6 +169,9 @@ spatial_states = final_state(spatial_simulation, Many(scale=:Leaf)) Dict(id => state.temperature_seen for (id, state) in spatial_states) ``` +The sun leaf reads 26 °C and the shade leaf reads 18 °C. A **handle** stores +the cell used by each leaf. You can check that the two handles are different: + ```@example journey_mutable_environment select( DataFrame(Diagnostics.explain_environment_bindings(spatial_model)), @@ -164,18 +180,7 @@ select( ) ``` -This ordinary user page does not require the backend implementation protocol. -Framework builders can follow [Environment Backend Extensions](@ref); the -complete MAESPA-style synthesis later combines mutable microclimate, several -plants, and iterative leaf calls. - -## Page recap - -- **You added:** one typed trial, one explicit accepted commit, one accepted - publication, and then two spatial cells. -- **PlantSimEngine inferred:** the reader call target, publication boundary, - commit permission check, and distinct `Many` handles. -- **You keep explicit:** trial and acceptance logic, `publish`, the committed - variables, controller sink, and backend state type. -- **New API names:** `environment_outputs_`, `run_call!`, - `commit_environment!`, `publish`, and `calls`. +For a larger example that adjusts canopy air conditions and repeats leaf +calculations across several plants, see [MAESPA-Style Synthesis](@ref). +To connect your own source of environmental data, see +[Environment Backend Extensions](@ref). diff --git a/docs/src/journeys/users/one_object.md b/docs/src/journeys/users/one_object.md index 350cee5e5..9ead09721 100644 --- a/docs/src/journeys/users/one_object.md +++ b/docs/src/journeys/users/one_object.md @@ -1,25 +1,52 @@ # Couple Models On One Object -## New concept: automatic same-object coupling over time +In this example, we combine three models to calculate how a canopy develops +and absorbs light over 30 days. We represent the whole canopy as one +**object**: one part of the simulated system, with its own values. We do not +describe individual leaves here. -This first executable simulation couples three existing models on one object: +The three models pass values to one another: -1. `ToyDegreeDaysCumulModel` reads temperature and accumulates thermal time. -2. `ToyLAIModel` reads cumulative thermal time and computes LAI. -3. `Beer` reads LAI and radiation and computes absorbed PAR. +1. `ToyDegreeDaysCumulModel` uses temperature to calculate cumulative thermal + time, a measure of accumulated warmth. +2. `ToyLAIModel` uses that thermal time to calculate leaf area index (LAI). +3. `Beer` uses LAI and incoming radiation to calculate the light absorbed by the canopy. -The weather file is supplied forcing data for now. Environments get their own -journey later. +These are teaching models with illustrative parameters. They show how to +connect calculations; their results are not predictions for a particular crop. + +Start with the [tutorial installation](../../prerequisites/installing_plantsimengine.md) +if these packages are not yet available in your Julia project. + +## Prepare the weather data + +We use a weather file included with PlantSimEngine. Each row describes one day. +The file records daily radiation totals in MJ m⁻² d⁻¹. `Beer` needs the average +radiation during that day in W m⁻², so the code below converts those columns. +`SW` means shortwave radiation, `PAR` is the light used for photosynthesis, +and `NIR` means near-infrared radiation. The weather data are called the +**environment** in this simulation. ```@example journey_one_object using PlantSimEngine, PlantMeteo, Dates, DataFrames using PlantSimEngine.Examples weather = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); + joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), + :Ri_SW_f => (x -> x .* 1e6 ./ 86_400) => :Ri_SW_f, + :Ri_PAR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_PAR_f, + :Ri_NIR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_NIR_f; duration=Day, ) +nothing # hide + +``` + +## Connect the models + +Put the three models together in a `CompositeModel` and give it the weather data: +```@example journey_one_object model = CompositeModel( ToyDegreeDaysCumulModel(), ToyLAIModel(), @@ -28,39 +55,37 @@ model = CompositeModel( ) ``` -No `ModelSpec` or selector is needed when all models run on the one object made -by the concise constructor. +PlantSimEngine connects these models automatically. The thermal-time model +provides `TT_cu` to the LAI model, which provides `LAI` to `Beer`. Each input +has the same name as an output from exactly one other model on this canopy. +PlantSimEngine also runs the models in that order, so each calculation can +use the result it needs. -!!! tip "Choose a status type for the whole scenario" - Add `type_promotion=Dict(Float64 => Float32)` to the constructor to - materialize every matching status scalar, model input default, and model - output default as `Float32`. Ordinary numeric arrays are converted element - by element. Model parameters such as `Beer(0.6)` and values supplied by - `weather` keep their own types. +## Run 30 days and look at the results - Use `status_transform=(variable, value) -> ...` when only selected - variables need another representation. The precise transform runs before - the general type mapping. See [Numerical Reliability](@ref) for complete - `Float32` and uncertainty-propagation examples. +`run!` starts the simulation. Here, `steps=30` runs the first 30 weather rows, +and `outputs=:all` saves the results from every model at each step. +`collect_outputs(simulation; sink=DataFrame)` gathers those saved results +into a DataFrame, the table type provided by DataFrames.jl. `DataFrame` is +already the default, so you can also write `collect_outputs(simulation)`. -Run thirty daily steps and retain the model outputs: +These first 30 days fall in winter, so thermal time increases slowly and LAI +stays small. The [plotting guide](../../guides/data/outputs_plotting.md) shows +how to plot results and compare two canopies. ```@example journey_one_object simulation = run!(model; steps=30, outputs=:all) -results = collect_outputs(simulation) - -thermal_time = results[results.variable .== :TT_cu, :value] -lai = results[results.variable .== :LAI, :value] -evolution = DataFrame( - step=1:length(thermal_time), - TT_cu=thermal_time, - LAI=lai, -) -vcat(first(evolution, 3), last(evolution, 3)) +results = collect_outputs(simulation; sink=DataFrame) +first(select(results, :timestep, :variable, :value), 8) ``` -The table is retained history. The latest values are also available directly, -whether or not history was requested: +Each row records one variable on one day. The last line selects three +columns and shows the first eight rows: four variables for each of the first +two days. `TT` is daily thermal time and `TT_cu` is cumulative thermal time, +both in °C d. LAI is leaf area per ground area, in m² m⁻². + +`final_state` gives the latest values, here at the end of day 30. It is also +available when you run a simulation without saving its history: ```@example journey_one_object state_at_day_30 = final_state(simulation) @@ -69,26 +94,17 @@ state_at_day_30 = final_state(simulation) TT_cu=state_at_day_30.TT_cu, LAI=state_at_day_30.LAI, aPPFD=state_at_day_30.aPPFD, - retained_streams=length(outputs(simulation)), ) ``` -PlantSimEngine inferred both status connections because each has one -unambiguous producer on the same object. This focused diagnostic shows the -resolved sources and the live reference carriers: +`aPPFD` measures absorbed photosynthetically active radiation (PAR), the light +available for photosynthesis. Its unit here is μmol of photons per m² of +ground per second, averaged over the day. The area refers to the ground +covered by the canopy, rather than the area of its leaves. -```@example journey_one_object -select( - DataFrame(Diagnostics.explain_bindings(model)), - :application_id, - :input, - :source_application_ids, - :carrier_kind, -) -``` +## Continue for another day -A `Simulation` owns a continuing timeline. Advancing it does not rebuild a -separate result object: +`step!` runs the next day and adds its results to the same simulation: ```@example journey_one_object step!(simulation) @@ -96,16 +112,6 @@ state_at_day_31 = final_state(simulation) (current_step=current_step(simulation), TT_cu=state_at_day_31.TT_cu) ``` -## Page recap - -- **You added:** three models, supplied weather, a 30-step run, and retained - outputs. -- **PlantSimEngine inferred:** the one object, three applications, their - execution order, and the `TT_cu` and `LAI` connections. -- **You keep explicit:** model parameters, forcing data, number of steps, and - whether output history is retained. -- **New API names:** `CompositeModel`, `run!`, `Simulation`, `final_state`, - `collect_outputs`, `outputs`, `current_step`, `step!`, and - `Diagnostics.explain_bindings`. -- **Optional status policies:** `type_promotion` for a general type mapping and - `status_transform` for a variable-specific conversion. +You have now extended the same history to day 31. Continue with +[several independent objects](several_objects.md), or +[plot the results](../../guides/data/outputs_plotting.md). diff --git a/docs/src/journeys/users/one_plant.md b/docs/src/journeys/users/one_plant.md index cbb13eae8..3bf3c8c11 100644 --- a/docs/src/journeys/users/one_plant.md +++ b/docs/src/journeys/users/one_plant.md @@ -1,24 +1,35 @@ # Build One Multiscale Plant -## New concept: topology and cross-object values +Share an absorbed-light supply between two leaves, then compute how their +areas contribute to the plant total. This teaching example represents the +plant and its two leaves as three objects. Each leaf names the plant as its +`parent`, which records that the leaf belongs to that plant. The leaf areas +and radiation values are illustrative. -The previous journey used independent objects at one scale. A multiscale plant -adds parent/child topology: one plant object owns two leaf objects. +The structure is: -The scope picture for this page is: +> `:plant`
+> ├─ `:leaf_1`
+> └─ `:leaf_2` -> `:plant` — `Subtree()` from here contains `:plant`, `:leaf_1`, and `:leaf_2`
-> ├─ `:leaf_1` — `Self()` is `:leaf_1`; `SelfPlant()` resolves to `:plant`
-> └─ `:leaf_2` — `Self()` is `:leaf_2`; `SelfPlant()` resolves to `:plant` +To choose objects for a calculation, use a **selector** such as +`Many(scale=:Leaf)`. The `within` option limits where to look. For a model +running on `:plant`, `Subtree()` includes that plant and everything below it, +so `Many(scale=:Leaf, within=Subtree())` selects its two leaves. For a model +running on a leaf, `Self()` means that leaf, and `SelfPlant()` means its plant. -Selectors still filter that scope. For example, -`Many(scale=:Leaf, within=Subtree())` selects the two leaves when evaluated for -the plant application. +## First pass: share light between leaves -## First pass: one scalar value from plant to leaves +Start by supplying the leaf areas and their total in `Status`, where each +object stores its values. Each leaf model will read the plant's absorbed +light and total leaf area to calculate its own share. -Start with leaf surfaces and total plant surface supplied as status. The only -new value connection sends the plant-level absorbed light to each leaf. +We use one **common reference ground area** for the whole plant. Its supplied +`aPPFD` is 120 μmol m⁻² of reference ground s⁻¹. Each leaf receives a share in +proportion to its area: `120 × 1/3 = 40` and `120 × 2/3 = 80`, on that same +ground-area basis. These contributions can be added to recover 120. They are +not photon flux densities per unit leaf area. This deliberately simple share +does not calculate shading or 3D light interception. ```@example journey_one_plant using PlantSimEngine, DataFrames @@ -75,8 +86,17 @@ scalar_states = final_state(scalar_simulation, Many(scale=:Leaf)) Dict(id => state.aPPFD for (id, state) in scalar_states) ``` -The leaf model reads its own `surface` directly from each leaf status. -`SelfPlant()` makes the other two scalar sources plant-local: +The areas stored in `surface` are in m² of leaves. A leaf photosynthesis model +may instead need light per m² of leaf. To make that conversion, multiply a +leaf's contribution by the plant's reference ground area, then divide by +that leaf's area. Write this conversion as a model so the units are clear +when connecting the two calculations; see [Coupling models](../../guides/coupling.md). + +Each leaf model reads `surface` from that leaf and uses `SelfPlant()` to find +the plant's `aPPFD` and total `surface`. In the table below, `consumer_id` +identifies the object reading a value, and `source_ids` identifies where the +value comes from. `carrier_kind` describes how PlantSimEngine shares it; +`ref` means the model reads the source's current value directly. ```@example journey_one_plant select( @@ -88,15 +108,20 @@ select( ) ``` -## Second pass: compute and aggregate leaf surfaces +## Second pass: calculate leaf areas and their total Now replace the supplied surfaces with two existing models: - `ToyLeafSurfaceModel` computes each leaf surface from its carbon biomass; - `ToyPlantLeafSurfaceModel` sums those leaf surfaces on the plant. -This is the first vector-like cross-object input. It comes after the scalar -connection above, and differs only in the new `:leaf_surfaces` binding. +Here the leaf carbon biomasses are 50 and 100 g C, and the specific leaf area +is 0.02 m² g C⁻¹. Their calculated areas are therefore 1 and 2 m², preserving +the light shares from the first pass. + +The plant model now needs a collection of values: one area from each leaf. +The `Many(...)` selector for `:leaf_surfaces` provides that collection, which +`ToyPlantLeafSurfaceModel` adds together. ```@example journey_one_plant computed_objects = ( @@ -174,8 +199,14 @@ leaf_states = final_state(computed_simulation, Many(scale=:Leaf)) ) ``` -The plant aggregation uses a live `RefVector`; the scalar connections remain -single references: +The resulting plant surface should be 3 m² and the light contributions should +still be 40 and 80 μmol m⁻² of reference ground s⁻¹. You can now +[use different models on two plants in the same simulation](several_plants.md). + +The optional table below lets you check the connections. For +`:leaf_surfaces`, the plant should read from both leaves. Its `RefVector` +holds references to their current areas, so the plant sees the new values +after the leaf models update them. Inputs with just one source use `ref`. ```@example journey_one_plant select( @@ -187,14 +218,3 @@ select( :carrier_kind, ) ``` - -## Page recap - -- **You added:** parent/child topology, plant-to-leaf scalar connections, and - one plant-local vector aggregation. -- **PlantSimEngine inferred:** same-leaf `surface` coupling, application order, - and live scalar/vector reference carriers. -- **You keep explicit:** object parentage, the scope of cross-object searches, - and the source application when selecting a produced value. -- **New API names:** `parent`, `Self`, `SelfPlant`, `Subtree`, and the - `application` and `var` selector fields. diff --git a/docs/src/journeys/users/several_objects.md b/docs/src/journeys/users/several_objects.md index 19fba3432..980442c0c 100644 --- a/docs/src/journeys/users/several_objects.md +++ b/docs/src/journeys/users/several_objects.md @@ -1,79 +1,76 @@ # Run The Coupling On Several Objects -## New concept: stable object identity and `Many` - -The previous page ran one model chain on one automatically created object. The -smallest extension is to create two same-scale objects and target both with one -reusable `Many` selector. +Run the same teaching models on two independent canopies with different +initial development stages. Each canopy is one object; `Many(scale=:Canopy)` +selects both. This lets you compare the two canopies without writing a loop +inside each model. We start the canopies at different cumulative thermal +times so their leaf area indices differ visibly over this short, five-day run. ```@example journey_several_objects using PlantSimEngine, PlantMeteo, Dates, DataFrames using PlantSimEngine.Examples weather = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); + joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), + :Ri_SW_f => (x -> x .* 1e6 ./ 86_400) => :Ri_SW_f, + :Ri_PAR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_PAR_f, + :Ri_NIR_f => (x -> x .* 1e6 ./ 86_400) => :Ri_NIR_f; duration=Day, ) -plants = ( +canopies = ( Object( - :plant_a; - scale=:Plant, - kind=:plant, - status=Status(TT_cu=0.0), + :canopy_a; + scale=:Canopy, + kind=:canopy, + status=Status(TT_cu=600.0), ), Object( - :plant_b; - scale=:Plant, - kind=:plant, - status=Status(TT_cu=200.0), + :canopy_b; + scale=:Canopy, + kind=:canopy, + status=Status(TT_cu=900.0), ), ) -plant_targets = Many(scale=:Plant) +canopy_targets = Many(scale=:Canopy) model = CompositeModel( - plants...; + canopies...; applications=( ModelSpec( ToyDegreeDaysCumulModel(); name=:degree_days, - on=plant_targets, + on=canopy_targets, ), - ModelSpec(ToyLAIModel(); name=:lai, on=plant_targets), - ModelSpec(Beer(0.6); name=:light, on=plant_targets), + ModelSpec(ToyLAIModel(); name=:lai, on=canopy_targets), + ModelSpec(Beer(0.6); name=:light, on=canopy_targets), ), environment=weather, ) ``` -`:plant_a` and `:plant_b` are stable object identities. Their initial -cumulative thermal times differ, but the same three model kernels execute for -both. The model implementations contain no loop over plants. - -The application diagnostic confirms that each application compiled to both -objects: - -```@example journey_several_objects -select( - DataFrame(Diagnostics.explain_applications(model)), - :application_id, - :target_ids, -) -``` +The names `:canopy_a` and `:canopy_b` identify the canopies throughout the +simulation. Both use the same three models, but each keeps its own values. +PlantSimEngine runs the models for each canopy, so the model code does not +need a loop over canopies. -Run five steps and inspect each independent final status: +Run five daily steps and read the final values for each canopy: ```@example journey_several_objects simulation = run!(model; steps=5, outputs=:all) -states = final_state(simulation, Many(scale=:Plant)) +states = final_state(simulation, Many(scale=:Canopy)) Dict( id => (TT_cu=state.TT_cu, LAI=state.LAI, aPPFD=state.aPPFD) for (id, state) in states ) ``` -Retained streams are keyed by application, object, and variable, so the two -objects do not overwrite one another: +LAI is in m² of leaves per m² of ground; `aPPFD` is in μmol of absorbed PAR +per m² of ground per second. The CSV radiation totals were converted to mean +fluxes just as in the one-object example. + +The saved results include the model application name, canopy name, and +variable name. This keeps the two LAI time series separate: ```@example journey_several_objects rows = collect_outputs(simulation) @@ -86,17 +83,18 @@ lai_rows = rows[rows.variable .== :LAI, [ first(lai_rows, 6) ``` -This remains a same-scale simulation. Parent/child topology and cross-object -value selection are introduced on the next journey, after independent object -execution is established. +You can also check which objects each model will run on. The table below +should list both canopies for each application: -## Page recap +```@example journey_several_objects +select( + DataFrame(Diagnostics.explain_applications(model)), + :application_id, + :target_ids, +) +``` -- **You added:** two explicit `Object`s, stable ids, one shared `Many` selector, - and named `ModelSpec` applications. -- **PlantSimEngine inferred:** two targets per application plus independent - same-object `TT_cu` and `LAI` connections for each plant. -- **You keep explicit:** which objects exist, their initial status, application - names, and the selector describing the target set. -- **New API names:** `Object`, `Status`, `ModelSpec`, `Many`, and - `Diagnostics.explain_applications`. +The two canopies run independently here. In [one multiscale plant](one_plant.md), +you will connect a plant to its leaves and pass values between them. To +compare the canopy time series visually, follow +[Collecting And Plotting Outputs](../../guides/data/outputs_plotting.md). diff --git a/docs/src/journeys/users/several_plants.md b/docs/src/journeys/users/several_plants.md index a468532c1..6b1e5d0e8 100644 --- a/docs/src/journeys/users/several_plants.md +++ b/docs/src/journeys/users/several_plants.md @@ -1,84 +1,89 @@ # Instantiate Several Plants -## New concept: templates, instances, and overrides +Two plants can use different equations for the same process in one +simulation. Here both plants receive the same amount of carbon, but use +different rules to divide it between leaves, wood, and reserves. This lets +you compare the rules while keeping the inputs the same. -The previous journey configured one plant explicitly. Its three applications -can become a `CompositeModelTemplate`, then be mounted on several independent -object topologies without duplicating that model configuration. +We represent each whole plant as one object. For an example with individual +leaves, see [one multiscale plant](one_plant.md). + +## Choose two allocation rules + +Both models describe **carbon allocation**: deciding where available carbon +goes. They read the same inputs and produce the same outputs, so either can +fill the `:allocation` application in our plant template. Their equations +differ: + +- `FixedFractionAllocation(0.5, 0.3)` assigns up to 50% of the available + carbon to leaves and up to 30% to wood. Neither receives more than its + demand. Carbon left over goes into reserves. +- `DemandAllocation()` divides carbon in proportion to leaf and wood demand. + When there is enough carbon, both demands are met. Any excess goes into + reserves. + +You can see the difference in the equations. Let `C` be available carbon, +`L` leaf demand, and `W` wood demand. `min(a, b)` means the smaller of the +two amounts: + +| Carbon sent to | Fixed fractions | Proportional to demand | +|---|---|---| +| Leaves | `min(0.5 * C, L)` | `min(C, L + W) * L / (L + W)` | +| Wood | `min(0.3 * C, W)` | `min(C, L + W) * W / (L + W)` | +| Reserves | What remains after leaf and wood allocation | What remains after leaf and wood allocation | + +If both demands are zero, both models put all available carbon into reserves. + +These are teaching rules, not calibrated models of particular species. +All amounts are grams of elemental carbon (g C) per plant. The example does +not convert carbon into dry biomass or subtract respiration losses, and +neither rule withdraws carbon from reserves. +The carbon offer is the amount available after any respiration costs. Offers +and demands must be finite and nonnegative. + +Load the models from the example source included with PlantSimEngine: ```@example journey_several_plants -using PlantSimEngine, DataFrames -using PlantSimEngine.Examples +using PlantSimEngine, Dates, DataFrames + +include(joinpath(pkgdir(PlantSimEngine), "examples", "two_plant_allocation.jl")) +using .TwoPlantAllocationExample +``` +## Make a template and two plants + +A `CompositeModelTemplate` stores models and their configuration for reuse. +Our template uses the fixed-fraction rule by default. The application name +`:allocation` identifies the calculation we will replace on the second plant. + +```@example journey_several_plants plant_template = CompositeModelTemplate(( ModelSpec( - ToyLeafSurfaceModel(0.02); - name=:leaf_surface, - on=Many(scale=:Leaf), - ), - ModelSpec( - ToyPlantLeafSurfaceModel(); - name=:plant_surface, + FixedFractionAllocation(0.5, 0.3); + name=:allocation, on=One(scale=:Plant), - inputs=( - :leaf_surfaces => Many( - scale=:Leaf, - within=Subtree(), - application=:leaf_surface, - var=:surface, - ), - ), - ), - ModelSpec( - ToyLightPartitioningModel(); - name=:leaf_light, - on=Many(scale=:Leaf), - inputs=( - :aPPFD_larger_scale => One( - scale=:Plant, - within=SelfPlant(), - var=:aPPFD, - ), - :total_surface => One( - scale=:Plant, - within=SelfPlant(), - application=:plant_surface, - var=:surface, - ), - ), ), )) +nothing # hide ``` -An `ObjectInstance` supplies the concrete root and organs. These two instances -reuse the same template while keeping different initial plant radiation and -leaf biomasses: +Each `ObjectInstance` supplies a plant and its initial values. Here `root` +means the object at the top of the plant's structure, not a botanical root. +Both plants have 10 g C available today, a leaf demand of 8 g C, and a wood +demand of 2 g C. + +Plant A keeps the template's model. Plant B uses `overrides` to replace that +model with `DemandAllocation()`: ```@example journey_several_plants plant_a = ObjectInstance( :plant_a, plant_template; root=Object( - :plant_a_root; + :plant_a; scale=:Plant, kind=:plant, - status=Status(aPPFD=120.0), - ), - objects=( - Object( - :plant_a_leaf_1; - scale=:Leaf, - kind=:leaf, - parent=:plant_a_root, - status=Status(carbon_biomass=50.0), - ), - Object( - :plant_a_leaf_2; - scale=:Leaf, - kind=:leaf, - parent=:plant_a_root, - status=Status(carbon_biomass=100.0), - ), + status=Status(carbon_offer=10.0, leaf_demand=8.0, wood_demand=2.0), ), ) @@ -86,119 +91,69 @@ plant_b = ObjectInstance( :plant_b, plant_template; root=Object( - :plant_b_root; + :plant_b; scale=:Plant, kind=:plant, - status=Status(aPPFD=200.0), - ), - objects=( - Object( - :plant_b_leaf_1; - scale=:Leaf, - kind=:leaf, - parent=:plant_b_root, - status=Status(carbon_biomass=50.0), - ), - Object( - :plant_b_leaf_2; - scale=:Leaf, - kind=:leaf, - parent=:plant_b_root, - status=Status(carbon_biomass=50.0), - ), + status=Status(carbon_offer=10.0, leaf_demand=8.0, wood_demand=2.0), ), + overrides=(allocation=DemandAllocation(),), ) - -model = CompositeModel(plant_a, plant_b) -simulation = run!(model; outputs=:all) -plant_states = final_state(simulation, Many(scale=:Plant)) -Dict(id => (surface=state.surface, aPPFD=state.aPPFD) for (id, state) in plant_states) +nothing # hide ``` -Plant A aggregates surfaces `1 + 2 = 3`; plant B aggregates `1 + 1 = 2`. -Those totals prove that `Subtree()` did not mix leaves between instances. -Likewise, each pair of leaf-level light outputs sums to its own plant's -supplied light: +The process is the same on both plants: `:carbon_allocation`. The model used +for that process is different. Each plant keeps its own inputs and carbon +pools; replacing Plant B's model does not change Plant A's model. -```@example journey_several_plants -leaf_states = final_state(simulation, Many(scale=:Leaf)) -( - plant_a_light=sum( - leaf_states[id].aPPFD - for id in (:plant_a_leaf_1, :plant_a_leaf_2) - ), - plant_b_light=sum( - leaf_states[id].aPPFD - for id in (:plant_b_leaf_1, :plant_b_leaf_2) - ), -) -``` +## Run both plants together -The instance diagnostic shows the mounted object and application ids. Template -application names are prefixed automatically, so the two mounted graphs remain -unambiguous: +Put both plants in one `CompositeModel`. One step lasts one day here: ```@example journey_several_plants -select( - DataFrame(Diagnostics.explain_instances(model)), - :name, - :root_id, - :object_ids, - :application_ids, +model = CompositeModel(plant_a, plant_b; environment=(duration=Day(1),)) +simulation = run!(model; steps=1, outputs=:all) +results = collect_outputs(simulation; sink=DataFrame) + +allocation_rows = filter( + :variable => v -> v in (:leaf_growth, :wood_growth, :reserve_change), + results, ) +comparison = unstack(allocation_rows, :object_id, :variable, :value) +select(comparison, :object_id, :leaf_growth, :wood_growth, :reserve_change) ``` -## Override one instance +`collect_outputs` returns a table with one row per variable. We select the +three daily allocations, then use `unstack` to give each variable its own +column. Each row of the displayed table now describes one plant. -Only after the two unchanged instances work, override one application for a -new instance. This plant uses a larger specific leaf area while retaining the -same logical `:leaf_surface` application and all other template wiring: +Plant A sends **5 g C to leaves, 2 to wood, and 3 to reserves**. Its wood +fraction would give 3 g C, but wood only demands 2. The unused carbon stays +in reserves rather than being reassigned to leaves. -```@example journey_several_plants -plant_c = ObjectInstance( - :plant_c, - plant_template; - root=Object( - :plant_c_root; - scale=:Plant, - kind=:plant, - status=Status(aPPFD=120.0), - ), - objects=( - Object( - :plant_c_leaf_1; - scale=:Leaf, - kind=:leaf, - parent=:plant_c_root, - status=Status(carbon_biomass=50.0), - ), - Object( - :plant_c_leaf_2; - scale=:Leaf, - kind=:leaf, - parent=:plant_c_root, - status=Status(carbon_biomass=100.0), - ), - ), - overrides=(leaf_surface=ToyLeafSurfaceModel(0.04),), -) +Plant B sends **8 g C to leaves, 2 to wood, and 0 to reserves**. The available +10 g C is enough to meet both demands. In both cases, the three amounts add +up to the 10 g C supplied. -override_simulation = run!(CompositeModel(plant_c)) -override_state = final_state(override_simulation, One(scale=:Plant)) -override_state.surface -``` - -There is no `SceneScope()` in this example because nothing is deliberately -shared between plants. Introduce scene-wide scope only when adding a real -shared source, such as a soil object or scene-level forcing controller. +The models also keep cumulative `leaf_carbon`, `wood_carbon`, and +`reserve_carbon` values. These pools start at zero here, so after one day +they equal the amounts just allocated. They record allocated carbon, not +predicted organ biomass. -## Page recap +```@example journey_several_plants +fixed = final_state(simulation, :plant_a) # hide +demand = final_state(simulation, :plant_b) # hide +@assert (fixed.leaf_growth, fixed.wood_growth, fixed.reserve_change) == (5.0, 2.0, 3.0) # hide +@assert (demand.leaf_growth, demand.wood_growth, demand.reserve_change) == (8.0, 2.0, 0.0) # hide +@assert fixed.leaf_carbon + fixed.wood_carbon + fixed.reserve_carbon == 10.0 # hide +@assert demand.leaf_carbon + demand.wood_carbon + demand.reserve_carbon == 10.0 # hide +nothing # hide +``` -- **You added:** one reusable `CompositeModelTemplate`, two independent - `ObjectInstance`s, and then one application override. -- **PlantSimEngine inferred:** instance-local selector scopes, prefixed mounted - application ids, and the same compiled coupling graph for each plant. -- **You keep explicit:** each instance's objects and initial values, plus the - exact application replaced by an override. -- **New API names:** `CompositeModelTemplate`, `ObjectInstance`, `overrides`, - and `Diagnostics.explain_instances`. +To compare other conditions, change `carbon_offer`, `leaf_demand`, or +`wood_demand` when constructing the plants. These supplied values stay fixed +in this example: each new day supplies another 10 g C to each plant and +renews the demands. The carbon pools accumulate over those days. A longer +simulation could obtain changing daily values from +photosynthesis and organ-demand models. See +[Collect and plot results](../../guides/data/outputs_plotting.md) for comparing +the resulting time series. diff --git a/docs/src/journeys/users/structure_changes.md b/docs/src/journeys/users/structure_changes.md index b09749df7..ff182070a 100644 --- a/docs/src/journeys/users/structure_changes.md +++ b/docs/src/journeys/users/structure_changes.md @@ -1,11 +1,10 @@ # Modify Plant Structure -## New concept: lifecycle changes refresh compiled targets - Start with one plant, one branch, and two leaves. Each leaf computes carbon -demand, then treats that fully met demand as accepted carbon allocation for -`ToyCBiomassModel`. This small chain gives us a conserved quantity to check -while topology changes. +demand. We assume enough carbon is available to meet that demand and pass the +full amount to `ToyCBiomassModel`, which calculates growth and respiration. +We will add a leaf, move it to the branch, and remove another leaf. After +each change, we can check that the carbon balance still holds. ```@example journey_structure using PlantSimEngine, DataFrames @@ -61,9 +60,10 @@ initial_targets = only( ## Add one leaf -Registering an object mutates the live model and marks affected compiled state -dirty. Because this call happens between simulation steps, the new leaf is -compiled before the next step: +Use `register_object!` to add a leaf with its initial thermal time. The +simulation then needs to update which leaves its models run on. Here we add +the leaf between steps, so PlantSimEngine makes that update before running +the next step with `continue!`: ```@example journey_structure register_object!( @@ -101,16 +101,18 @@ targets_after_refresh = only( ) ``` -When a lifecycle operation occurs *inside* a model kernel, PlantSimEngine -refreshes after that application. A newly registered object may therefore run -applications that remain later in the same timestep. It runs an application -that already completed only through an explicit `Initializer` binding and -`run_initializer!` call from its creator. +You can also create organs inside a model's `run!` function, for example in +a growth model. In that case, PlantSimEngine updates the simulation after +that model finishes. The new organ can take part in calculations scheduled +later in the same timestep. Calculations that already ran are not repeated +automatically: to run one of them on the new organ, the growth model must +declare an `Initializer` and call `run_initializer!`. See +[Manual Calls Across Objects](../../guides/multiscale/manual_calls.md). ## Reparent, then remove -Creation now works, so make two further changes in order. First move the new -leaf under the branch and advance: +First change the new leaf's parent from the plant to the branch, then advance +the simulation: ```@example journey_structure reparent_object!(model, :leaf_3, :branch) @@ -145,8 +147,9 @@ continue!(simulation) ## Check conservation and history -For every retained leaf sample, accepted carbon allocation equals demand. The -biomass model partitions it into biomass increment plus growth respiration: +In this example, each leaf receives all the carbon it demands. For every +saved timestep, check that this carbon equals the increase in biomass plus +the carbon used in growth respiration: ```@example journey_structure rows = collect_outputs(simulation; sink=nothing) @@ -176,8 +179,7 @@ all( ) ``` -Removed-object history remains queryable even though the object is no longer -in the registry: +You can still read a removed leaf's earlier results: ```@example journey_structure history_counts = Dict( @@ -191,20 +193,10 @@ history_counts = Dict( ) ``` -`:leaf_2` keeps the three samples published before removal; `:leaf_3` begins at -step 2, after registration, and also has three samples. +`:leaf_2` keeps the three samples saved before removal. Results for `:leaf_3` +begin at step 2, after it was added, and also contain three samples. `ToyCAllocationModel` is useful when supply is limiting and a plant controller -must divide carbon among many organ demands. This journey deliberately assumes -all demand is accepted so lifecycle timing and conservation stay visible -without introducing a controller or hard calls. - -## Page recap - -- **You added:** one leaf, then one reparenting operation, then one removal. -- **PlantSimEngine inferred:** the affected application targets, status views, - reference binding, execution batch extension, and retained stream keys. -- **You keep explicit:** initialized status for a new object, its parent, - conservation assumptions, and when removal or reparenting occurs. -- **New API names:** `register_object!`, `reparent_object!`, `remove_object!`, - and `Diagnostics.explain_applications(simulation)`. +must divide carbon among organs. Here we assume there is enough carbon to +meet every demand, so you can focus on when organs are added or removed and +how to check their results. diff --git a/docs/src/migration_composite_model.md b/docs/src/migration_composite_model.md index 395952952..8196a2d87 100644 --- a/docs/src/migration_composite_model.md +++ b/docs/src/migration_composite_model.md @@ -1,11 +1,16 @@ # Migrating To The CompositeModel/Object API +Use this page when updating code written for an older PlantSimEngine API. +It shows how earlier model mappings, input connections, and output requests +are written with `CompositeModel` and `Object`. If you are starting a new +simulation, follow [the first tutorial](journeys/users/one_object.md). + ## Refining early CompositeModel/Object code -The stabilized public surface makes several early CompositeModel/Object behaviors -explicit: +Some names and defaults changed during development of the CompositeModel/Object +API. Update early examples as follows: -| Early spelling or behavior | Stabilized API | +| Early spelling or behavior | Current API | | --- | --- | | `Self()` searched self and descendants | `Self()` selects only the current object; use `Subtree()` for self plus descendants | | omitted `tracked_outputs` retained everything | use explicit `outputs=:all`; the safe default is `outputs=:none` | @@ -18,7 +23,7 @@ explicit: `tracked_outputs` has been removed. Use `outputs=:all`, `outputs=:none`, or `outputs=requests` directly. Singular scenario `inputs` and `calls`, `OutputRequest`, object overrides, and `Updates(...; after=...)` now identify -the target by canonical `application=...` or application ID. Model-authored +the model application with `application=...` or its application ID. Model-authored `Input`/`Call` defaults may still discover a process because they cannot know scenario application names, and `Many(process=...)` remains an explicit multi-application discovery query. @@ -35,8 +40,8 @@ step!(simulation) @assert current_step(simulation) == 49 ``` -The composite-model/object API replaces the historical multiscale mapping system with -one object-address graph. +The new API stores the simulated objects and their model applications in one +`CompositeModel`, replacing the earlier multiscale mappings. New scenario code should be organized around: @@ -48,8 +53,8 @@ Updates Environment ``` -Process-model implementations do not need to know about composite models, plants, objects, or -timesteps. They keep the existing kernel contract: +The equations stay in a model's `run!` function. Models that only calculate +values can be reused without referring to the simulation's plant structure: ```julia inputs_(model) @@ -64,8 +69,8 @@ equivalents. ## Explicit Input Initialization -Input literals no longer double as ambiguous placeholder values. Declare -whether each model input is required or genuinely has a fallback: +For each input, say whether a value must be supplied or whether the model +can use a default: ```julia # Old, ambiguous @@ -113,8 +118,8 @@ model = CompositeModel( ) ``` -`Object` labels describe runtime entities. They do not prescribe plant -topology. A plant may use any hierarchy of plants, axes, internodes, segments, +`Object` labels describe the parts of the simulated system. You choose how +these parts are connected. A plant may use any hierarchy of plants, axes, internodes, segments, leaves, roots, fruits, or application-specific objects. ### Status type conversion @@ -169,10 +174,9 @@ model = CompositeModel( `objects_from_mtg(mtg; ...)` exposes the intermediate object list when it is useful to inspect or modify labels before constructing the model. By default, the adapter uses MTG node ids and scales. Runtime `Status` values belong to the -`CompositeModel` registry and are never stored in MTG attributes. A deliberate -import boundary may provide `status=node -> import_status(node)` explicitly; -maintained workflows should initialize scientific state through model objects or -model applications instead. +`CompositeModel` registry and are never stored in MTG attributes. To import values from node attributes, supply a function such as +`status=node -> import_status(node)` explicitly. Set the starting values used +in the simulation on its objects or through its model applications. ## Multiscale Inputs @@ -225,8 +229,9 @@ ModelSpec( ) ``` -Same-rate bindings use shared references or reference vectors when possible. -Cross-rate bindings use typed temporal streams. +When models run at the same rate, their inputs can read the source objects' +current values through shared references. When rates differ, PlantSimEngine +uses saved output histories and your chosen rule for reading them. ## CompositeModel-Wide Values @@ -242,8 +247,8 @@ ModelSpec(SceneWaterBalance(); name=:scene_water, on=One(scale=:Scene), inputs=( ),)) ``` -The compiler chooses the carrier. Scenario authors declare the source objects, -source variable, and temporal policy rather than a route implementation. +Specify which objects supply the value, the source variable's name, and how +to read it over time. PlantSimEngine chooses how to store the connection. ## Manual Hard Calls @@ -282,10 +287,10 @@ function PlantSimEngine.run!(model::SceneEnergyBalance, status, environment, end ``` -`run_call!` defaults to `publish=false`. Trial calls mutate target status but -do not publish temporal samples or commit mutable environment updates. -do not append temporal samples or write environment outputs. The accepted -state must use `publish=true`. +`run_call!` uses `publish=false` by default. A trial changes the called +objects' current values, but does not add samples to their output histories +or save updates to the shared environment. Use `publish=true` to record the +accepted result, and `commit_environment!` to save accepted environment changes. ## Multiple Plants And Species @@ -450,24 +455,25 @@ model object together and, by default, reuses the status initialization policy f `CompositeModel(mtg; status=...)`. Use `register_object!` when adapting another topology backend or when a complete `Object` already exists. -Structural changes refresh application targets, input carriers, call targets, -writer validation, and schedules after the application that made the change. -New objects can therefore run applications that remain later in the current -timestep, but never applications that already ran. Geometry-only changes -refresh environment bindings without rebuilding unrelated structural bindings. +After the application that adds or removes objects finishes, PlantSimEngine +updates which models run, where they get their inputs, and which other models +they can call. It also checks for conflicting outputs and updates the schedule. +New objects can run applications that are still due later in the same step. +An application that already ran is only repeated for a new object through +an explicit `Initializer` call; see [manual calls](guides/multiscale/manual_calls.md). +Changing geometry alone updates the affected environment connections. -The refreshed runtime also rebuilds homogeneous execution batches. Use -`Diagnostics.explain_execution_plan(scene_or_simulation)` to inspect the concrete -model/status/carrier types and the objects grouped into each specialized inner -loop. Exceptional per-object model overrides appear as separate ordered -batches. +PlantSimEngine also updates the groups of similar objects it runs together. +`Diagnostics.explain_execution_plan(scene_or_simulation)` lists those groups +and their model and value types. An object using a replacement model appears +in a separate group. ## Output Collection `run!(model; steps=...)` returns a `Simulation`. Use `final_state(sim)` for the -latest one-object state, `outputs(sim)` for retained typed streams, -`Diagnostics.explain_outputs(sim)` for structured diagnostics, and -`collect_outputs(sim)` for tabular rows. +latest values of a single object, `outputs(sim)` for saved output histories, +`Diagnostics.explain_outputs(sim)` for a report about those outputs, and +`collect_outputs(sim)` to gather them into a table. ```julia request = OutputRequest( @@ -483,8 +489,7 @@ sim = run!(model; steps=48, outputs=request) daily = collect_outputs(sim, :leaf_transpiration_daily) ``` -CompositeModel output requests are materialized from retained temporal streams after -the run. They use the same temporal policies as multirate inputs and export +Output requests collect saved results after the run. They use the same temporal policies as multirate inputs and export dynamic objects only over the interval where that object published samples. If several model applications implement the same process, add `application=:application_name` to select one explicitly. This is also the @@ -492,9 +497,9 @@ way to request a named `:stream_only` publisher. `outputs=:none` retains no user streams. Passing explicit requests retains only their application/variable streams plus streams needed by temporal `ModelSpec(...; inputs=...)`. Use `Diagnostics.explain_output_retention(sim)` -to inspect why each retained stream was kept. Dependency-only streams retain a -bounded policy-specific horizon, while requested streams keep complete -histories for post-run export. Export is not yet a fully online path. +to inspect why each retained stream was kept. For results needed only as inputs to other models, PlantSimEngine keeps +just enough history for the chosen time rule. Results you explicitly request +keep their full history so you can collect them after the run. ## Inspecting The Compiled Scenario @@ -512,9 +517,9 @@ Diagnostics.explain_schedule(model) Diagnostics.explain_writers(model) ``` -These functions return structured rows with concrete object ids, application -ids, processes, variables, temporal policies, carrier semantics, and resolved -targets. They are intended for both users and coding agents. +These reports identify the objects and models used by the simulation, where +their values come from, and how they exchange values over time. People and +coding agents can inspect the same reports. ## Migration Table diff --git a/docs/src/model_execution.md b/docs/src/model_execution.md index 6e5a5c907..b55373442 100644 --- a/docs/src/model_execution.md +++ b/docs/src/model_execution.md @@ -1,10 +1,11 @@ # Model Execution -This page describes how the native composite-model/object runtime executes model -applications. Use this path for new multi-object, multi-plant, soil, -microclimate, and multirate simulations. +This reference explains how PlantSimEngine prepares and runs a simulation. +Start with [your first simulation](journeys/users/one_object.md) if you are +new to the package. -The public configuration surface has one application constructor: +A **model application** says where to run a model and how to supply its +inputs. Use `ModelSpec` to describe one: ```julia ModelSpec( @@ -20,30 +21,33 @@ ModelSpec( ) ``` -Scenarios start from `CompositeModel` and model applications. +Put these applications and the objects they describe into a `CompositeModel`. ## Model Kernels And Applications -A model kernel is still an ordinary PlantSimEngine model: +A **kernel** is the `run!` function that evaluates a model's equations. +The model also declares what those equations need and produce: - `inputs_(model)` declares each status input as `Required(T)` or `Default(value)`; - `outputs_(model)` declares variables the model computes and their initial output-state values; - `environment_inputs_(model)` declares environment variables it reads; +- `environment_outputs_(model)` declares which environmental variables it + may update, such as the temperature controlled by a canopy model; - `commit_environment!(context, state)` commits accepted mutable environment state when the model intentionally controls microclimate; - `dep(model)` may declare model-author defaults; - `run!(model, status, environment, constants, context)` contains the model equations. -`Required(T)` has no initialization value: object state or a producer -application must satisfy it. `Default(value)` is installed only when the target -does not already have the input. Plain input literals are rejected because -they are ambiguous. +`Required(T)` means you must supply the input on the object, or connect it +to another model's output. `Default(value)` supplies a starting value only +when that input is absent. A plain number is not a valid input declaration: +it would not say whether the model requires a value or can use a default. -The composite-model/object layer does not change that kernel contract. It adds a -scenario-specific application around the kernel: +The equations stay in the model. Use `ModelSpec` to configure their use in +this particular simulation: ```julia ModelSpec( @@ -59,29 +63,29 @@ ModelSpec( `ModelSpec` decides where the model runs, where its inputs come from, which models it may call manually, which timestep it uses, and which environment -provider is bound to it. The model implementation stays reusable. +source supplies its growing conditions. You can reuse the same model in +other simulations with different choices. ## Compilation Before Runtime -Before the timestep loop, PlantSimEngine compiles the model into concrete -runtime carriers: - -1. `ModelSpec(...; on=...)` selectors are resolved to stable object ids. -2. `ModelSpec(...; inputs=...)` selectors are resolved to source object/application ids. -3. Same-rate inputs are wired as shared `Ref`s, `RefVector`s, or - heterogeneous object-reference vectors. -4. Temporal inputs are compiled as stream lookups with a policy such as - `HoldLast`, `Interpolate`, `Integrate`, or `Aggregate`. -5. `ModelSpec(...; calls=...)` declarations are compiled to callable target lists. -6. `Environment(...)` is bound to backend cells, layers, voxels, or global - weather providers. -7. The root application order is topologically sorted from value inputs and - `Updates(...)` ordering. -8. Root execution batches are grouped by concrete model/status/environment - types where possible. - -Selectors are not resolved in the hot loop. Runtime execution uses the -compiled indexes and carriers. +Before the first time step, PlantSimEngine prepares the simulation. This +preparation is called **compilation**. It: + +1. finds the objects selected by each application's `on` rule; +2. finds where each input value will come from; +3. connects values updated at the same rate through shared references, which + let one model read another object's current value without copying it; +4. prepares any output history and rules needed to exchange values between + models that run at different time steps; +5. lists the models that each controller can call through `calls`; +6. finds the weather source, cell, or layer that supplies each object; +7. puts applications in order so their inputs are available when needed, + including any order specified by `Updates`; +8. groups objects with matching model, status, and environment types so Julia + can run them efficiently. + +The time loop reuses this work instead of searching for every connection +again at each step. Useful inspection helpers: @@ -95,9 +99,9 @@ Diagnostics.explain_execution_plan(model) Diagnostics.explain_writers(model) ``` -These explanations are intended for both users and agents. They report the -compiled object ids, applications, carriers, clocks, environment bindings, and -manual-call targets that the runtime will use. +These reports show which objects and models were selected, where their +inputs come from, when they run, and which growing conditions they receive. +Both people and coding agents can inspect the reports. ### Readable source views @@ -120,17 +124,16 @@ source = Authoring.compiled_model_source(model) Authoring.write_compiled_model_source("compiled_model.jl", model) ``` -The generated source spells out application order, selected targets, input -provenance, hard calls, and the kernel bodies invoked through normal -PlantSimEngine status, environment, output, and lifecycle machinery. It is -optimized for explanation and review, not as an alternative scheduler. It -represents the resolved plan; `scenario_source` reconstructs the scenario that -an author can edit and compile again. +The generated code shows which models run on which objects, where their +inputs come from, and which equations and manual calls are used. It runs +through the normal PlantSimEngine machinery. Use this view to inspect +execution; use `scenario_source` when you want to edit the simulation setup. ## Soft Dependencies With Inputs -Soft dependencies are value dependencies. A consumer model reads a variable -produced by another model through `ModelSpec(...; inputs=...)`. +A **soft dependency** means that one model needs a value calculated by +another. The model supplying the value is called the **producer**; the model +reading it is the **consumer**. Connect them with `ModelSpec(...; inputs=...)`: ```julia ModelSpec(SceneLAI(ground_area); name=:scene_lai, on=One(scale=:Scene), inputs=(:leaf_areas => Many( @@ -142,24 +145,28 @@ ModelSpec(SceneLAI(ground_area); name=:scene_lai, on=One(scale=:Scene), inputs=( ),)) ``` -For same-rate inputs, the runtime installs a reference carrier into the -consumer status during compilation. A model-scale model reading all leaf areas -therefore sees a `RefVector`-like object: reading pulls current values from -source leaf statuses, and writing through the carrier mutates source refs when -the carrier supports it. +When the models run at the same rate, the input refers to the source +object's current value. A plant model reading several leaf areas receives +a reference vector such as `RefVector`: a list that reads the current value +from each leaf. This shared storage is called a **reference carrier** in +the diagnostic reports. Where it supports writing, changing an entry also +changes the source object's value. -If an input is not explicitly declared with `ModelSpec(...; inputs=...)`, the compiler can -infer simple same-object bindings when exactly one producer on the same object -outputs the same variable. Ambiguous producers are errors and should be -disambiguated with `application=...` and, when names differ, `var=...`. +You can omit an input connection when exactly one other model on the same +object provides an output with the same name. PlantSimEngine connects it +automatically. If several models provide that output, choose one with +`application=...`. Use `var=...` when the source variable has a different name. -Use `PreviousTimeStep(:x) => selector` when a feedback dependency should read -the previous sample instead of creating a same-timestep scheduling edge. +Use `PreviousTimeStep(:x) => selector` when a feedback calculation should +read the previous step's value of `x`. The receiving model then does not +need to wait for the current step's calculation of `x`. ## Hard Calls With Calls -Hard dependencies are manual calls. Use `ModelSpec(...; calls=...)` when a parent model must -control the call stack, for example during an iterative energy-balance solve. +A **hard dependency** means that one model decides when to run another. +Declare it with `ModelSpec(...; calls=...)`. For example, an energy-balance +model may need to run photosynthesis repeatedly while adjusting leaf +temperature. ```julia ModelSpec(SceneEnergyBalance(); name=:scene_energy, on=One(scale=:Scene), calls=(:leaf_energy => Many( @@ -202,20 +209,22 @@ function PlantSimEngine.run!(model::SceneEnergyBalance, status, environment, end ``` -`run_call!` defaults to `publish=false`. Trial calls mutate target statuses but -do not publish temporal samples or commit mutable environment updates. Use -`environment=trial_state` when hard-called descendants should sample temporary -state through their compiled environment handles. Call `commit_environment!` and -`run_call!(...; publish=true)` once for the accepted state. +`run_call!` uses `publish=false` by default. Each trial updates the called +objects' current values, but does not add results to their time histories or +save changes to the shared environment. Pass `environment=trial_state` to +try temporary growing conditions; each called model still gets the conditions +for its own location. Once the result is accepted, save the environment +with `commit_environment!` and run once with `publish=true` to record it. -Applications selected only by `ModelSpec(...; calls=...)` are marked manual-call-only in -`Diagnostics.explain_schedule(model)` and are skipped by the root `run!(model)` loop. +Applications used only through `ModelSpec(...; calls=...)` run when their +controller calls them. They do not also run independently from the normal +schedule. `Diagnostics.explain_schedule(model)` marks them as manual-call-only. ## Duplicate Writers With Updates -By default, one application owns each `(object, output variable)` canonical -writer. If a scenario intentionally lets several models update the same -variable, later writers must declare that order explicitly: +Normally, only one model application may calculate a given output variable +on an object. If you want several models to update that variable, state +which should run first: ```julia ModelSpec(CarbonAllocation(); name=:carbon_allocation, on=Many(scale=:Leaf)) @@ -226,12 +235,14 @@ ModelSpec(LeafPruning(); name=:leaf_pruning, on=Many(scale=:Leaf), updates=Updat This keeps ordinary duplicate outputs as errors while allowing cases such as allocation followed by pruning. `Diagnostics.explain_writers(model)` reports writer groups and the `Updates(...)` declarations that validate them. -The `after` value is the canonical application identifier shown by -`Diagnostics.explain_applications(model)`, not the process name. +For `after`, use the application ID shown by +`Diagnostics.explain_applications(model)`. A process name does not identify +a particular application when several models use that process. ## Multirate Execution -Use `ModelSpec(...; every=...)` with `Dates.Period` values for model application clocks: +**Multirate** means that models run at different time steps. Set how often +a model runs with `ModelSpec(...; every=...)` and a duration such as `Hour(1)`: The duration must be a positive integer multiple of the simulation base step. Choose a finer common base step when needed; the scheduler does not insert @@ -274,8 +285,10 @@ Supported policies are: duration weighting; - `Aggregate()`: reduce values over a window, defaulting to `MeanReducer()`. -Policies resample numeric values but do not transform `VariableContract` -metadata. A contracted rate-to-amount conversion needs an explicit adapter; +These rules combine numeric values but do not change the units or physical +meaning recorded in `VariableContract`. If you declare a rate on one side +and an amount on the other, use a conversion model with the appropriate +units and meaning declared for each side; see [Coupling models](@ref). `Integrate(...)` and `Aggregate(...)` accept reducer objects or callables that @@ -289,9 +302,9 @@ producer execution and weighted by the portion of that interval overlapping the consumer window. This includes the last value published before the window when it remains active inside the window. -Temporal windows are duration-based rolling windows. Calendar-aligned civil -days and "previous complete period" selection are not part of the public API; -there is no `CalendarWindow` compatibility type. +Time windows cover a duration relative to the current simulation time. +They do not automatically align with calendar days or select the previous +complete day, week, or month. ## Environment Sampling @@ -301,9 +314,10 @@ there is no `CalendarWindow` compatibility type. ModelSpec(CO2Probe(); name=:co2_probe, on=Many(scale=:Leaf), environment=Environment(provider=:canopy, sources=(CO2=:Ca,))) ``` -The compiler binds each application/object pair to the selected backend before -runtime. Constant weather, global tabular meteorology, grid, layer, voxel, or -octree-style microclimate backends all use the same contract: +Before running, PlantSimEngine finds the environment source for each model +and object. An environment **backend** is the code that supplies those +conditions, from a weather table or a spatial representation such as soil +layers or canopy cells. All backends use the same model-facing functions: - `environment_inputs_(model)` says what the model reads; - `environment_outputs_(model)` says what the model may commit; @@ -315,7 +329,9 @@ octree-style microclimate backends all use the same contract: - geometry and position are used by spatial backends when available; - object-to-environment links are cached and refreshed when objects move. -Backend authors implement an opaque-handle protocol: +A backend first locates the data needed by an object and saves that location +in a **handle**. The model does not need to interpret this handle; the backend +uses it to retrieve values efficiently. Backend authors implement: ```julia handle = EnvironmentAPI.bind_environment(backend, object, context, config) @@ -325,12 +341,13 @@ EnvironmentAPI.sample(backend, handle, trial_state, variable, time) # transient commit_environment!(backend, handle, accepted_state, time) ``` -`EnvironmentAPI.EnvironmentContext` identifies the application, object, scale, and process -while the handle is compiled. Runtime status and geometry are not passed to -sampling: a spatial backend resolves them once in `EnvironmentAPI.bind_environment` and stores -the resulting provider, layer, voxel, or other routing data in its concrete -handle. A controller that reads from one provider and commits to another should -encode both routes in the handle, for example +`EnvironmentAPI.EnvironmentContext` identifies the model application, object, +scale, and process when the backend prepares the handle. A spatial backend +uses `EnvironmentAPI.bind_environment` to locate the object's layer, cell, or +other data source and stores that location in the handle. Later requests for +environment values use this handle; they do not receive the object's full +status and geometry again. If a controller reads from one source and saves +updates to another, the handle must record both, for example `Environment(provider=:forcing, sink=:canopy)`. Model-level `environment_hint(...)` can provide default source bindings and @@ -346,8 +363,8 @@ Run a model with: sim = run!(model; steps=30) ``` -The returned `Simulation` contains the mutated model, compiled bindings, -environment bindings, execution plan, and retained temporal output streams. +The returned `Simulation` keeps the current model values, the prepared +connections and schedule, and any saved output histories. By default, model runs retain no user output streams. Pass `outputs=:all` to retain every published stream, or pass `OutputRequest` values to retain only @@ -417,36 +434,39 @@ move_object!(model, :leaf_4, new_geometry) update_geometry!(model, :leaf_5, new_geometry) ``` -Use `add_organ!` for an MTG-backed model. It creates the MTG node, initializes -and attaches its `Status`, registers the model object, and invalidates the -affected bindings. By default, status initialization reuses the model's MTG -policy. A framework that already supplies the complete creation attributes and -initial status may set `use_status_adapter=false`; doing so is an explicit -assertion that the configured status accessor contributes no additional fields -or side effects for that node. `register_object!` is the low-level operation -for callers that already own a complete `Object`. - -Structural changes invalidate compiled object/model bindings. Movement and -geometry changes invalidate environment bindings without rebuilding structural -input carriers. Scenario-level application, dependency, selector, cadence, -environment-sampling, and output-retention plans remain immutable; only the -affected object targets and buffers are refreshed. - -Do not mutate `Object` topology, labels, or geometry fields directly. Direct -field mutation bypasses registry indexes and cache invalidation and is -unsupported. Use the lifecycle functions above. They validate prerequisites -before mutating; in particular, `reparent_object!` rejects self-parenting and -descendant cycles without changing existing links. `ObjectInstance` roots are -immutable lifecycle anchors: removing or reparenting a root, or an ancestor -whose subtree contains one, is rejected atomically. Ordinary descendants may -still be added, removed, or reparented. - -Inside a lifecycle-capable model kernel, use `runtime_model(context)` to obtain -the live model. Objects created during a kernel call do not recursively execute -inside that call. At the safe barrier after the mutating application, -PlantSimEngine refreshes affected structural targets, value carriers, hard-call -targets, writer validation, temporal storage, execution groups, output-request -matches, and environment handles. A new object can therefore run an application +Use `add_organ!` when the plant structure comes from an MTG. It creates the +node, prepares its starting values, adds the object to the simulation, and +marks its connections for updating. By default, it reuses the function you +provided to initialize values from MTG nodes. + +Set `use_status_adapter=false` only if you supply all the new organ's +attributes and values yourself, and that initialization function has no +additional work to do. Use `register_object!` when you already have a fully +prepared `Object` to add. + +Adding or removing objects can change which models run and where their +inputs come from, so PlantSimEngine updates the affected connections. Moving +an object or changing its shape updates its environment connection without +rebuilding unrelated model connections. The rules you supplied in the +simulation setup stay the same. + +Use the functions above to change objects; assigning directly to their +structure, label, or geometry fields would leave PlantSimEngine's stored +connections out of date. The functions check each change before applying it. +For example, `reparent_object!` prevents an object from becoming its own +parent or a descendant of itself. + +The root of an `ObjectInstance` must stay in place. You cannot remove or +reparent that root, or an ancestor whose descendants contain it. Rejected +operations leave the existing structure unchanged. You can still add, +remove, or reparent ordinary descendants of the instance root. + +Inside a model's `run!` function, use `runtime_model(context)` to access the +simulation model when creating or changing objects. Creating an object does +not immediately run its models. After the application that made the change +finishes, PlantSimEngine updates the affected model selections, input and +environment connections, manual calls, output histories, and execution order. +It also checks that output variables still have valid sources. A new object can therefore run an application that remains later in the same timestep. It does not retroactively run an application that already completed unless its creator declares that application as an [`Initializer`](@ref) and explicitly calls [`run_initializer!`](@ref) on diff --git a/docs/src/model_traits.md b/docs/src/model_traits.md index 3dee94758..a6adddaa5 100644 --- a/docs/src/model_traits.md +++ b/docs/src/model_traits.md @@ -1,8 +1,12 @@ # Model Traits -Model traits describe intrinsic model behavior. Scenario-specific coupling -belongs in `ModelSpec` through `on`, `inputs`, `calls`, `every`, -`Environment`, `output_routing`, and `Updates`. +A **trait** is a function that tells PlantSimEngine something about a model: +which values it needs, which values it calculates, or how often it should run. +This page lists the declarations a model author can provide. For a complete +example, start with [writing a first model](journeys/modelers/basic_model.md). + +Use `ModelSpec` for choices that belong to a particular simulation, such as +which leaves use the model and where their inputs come from. ## Variables @@ -16,22 +20,22 @@ PlantSimEngine.inputs_(::MyModel) = ( PlantSimEngine.outputs_(::MyModel) = (assimilation=0.0,) ``` -`Required(T)` means the value must be present on the target object's `Status` -or bound from another application. `T` is an expected type, not a placeholder -value. It may be abstract or parametric, so use the scientific type contract -instead of forcing `Float64`. +`Required(T)` means the object must already have this value, or another +model must provide it. `T` describes the kind of value expected, such as +`Float64` for a floating-point number. It does not supply a starting value. +Choose a type that fits the calculation; it need not always be `Float64`. -`Default(value)` means the model can run without user initialization or a -producer for that input. PlantSimEngine installs a private copy of `value` on -each target object when the value is absent. Mutable defaults are therefore -not shared between objects. +`Default(value)` supplies a starting value when neither the user nor another +model provides one. Each object gets its own copy. For example, changing a +default array on one leaf does not change the array on another leaf. -Output literals remain initial output-state values. In the example, -`assimilation` starts at `0.0` before the first accepted model call. +The values in `outputs_` are the outputs' starting values. In this example, +`assimilation` starts at `0.0` before the model first runs. -These declarations are used for status initialization, dependency inference, -validation, and type construction. Plain input literals are rejected because -they do not say whether the value is required or genuinely optional. +PlantSimEngine uses these declarations to prepare each object's values, +connect models, and find missing inputs. Writing a plain number in `inputs_` +is rejected: it would not say whether the model needs a supplied value or +can use a default. Use `init_variables(model)` to inspect only values PlantSimEngine can initialize by itself: `Default` input values and output initial values. @@ -39,13 +43,15 @@ Required inputs are intentionally omitted. Before running a scenario, `Diagnostics.explain_initialization(model)` classifies inputs as `:required`, `:defaulted`, `:supplied`, or `:producer_bound`. A -`:required` row must be resolved before compilation can succeed. +`:required` row identifies an input you must supply before the simulation +can be prepared. ## Scientific meaning and dimensions Names and Julia types are not enough to distinguish, for example, daily PAR per ground area from daily PAR per plant. Add a `VariableContract` when a -variable participates in scientific coupling: +value will pass between models. A **variable contract** records its unit +and physical meaning: ```julia const PLANT_DAILY_PAR = VariableContract( @@ -64,33 +70,35 @@ PlantSimEngine.variable_contracts_(::PlantGrowth) = ( ) ``` -The tokens are open symbols, but a connected producer and consumer must declare -the same complete contract. Once either side declares one, a missing contract -on the other side is also a compilation error. Renaming a variable with -`var=...` does not convert its meaning; put unit, basis, or time conversion in -an explicit model boundary. +You choose the labels, such as `:plant` and `:day`. The model supplying the +value and the model reading it must declare the same complete contract. If +one declares a contract and the other does not, PlantSimEngine reports an +error before running. Renaming a variable with `var=...` does not convert +its units or meaning. Use a separate model for a conversion, such as +multiplying a quantity per unit area by plant area. -`VariableContract` is metadata only. Status and environment payloads remain -ordinary numbers, arrays, unit-bearing values, or automatic-differentiation -values, so the contract adds no wrapper to a model's numerical hot loop. +`VariableContract` describes the values without changing how they are +stored. Your equations still receive numbers or arrays, including compatible +types that carry units, uncertainty, or derivatives. Use `variable_contracts(model)` to inspect the validated declarations. Contract keys must occur in one of the model's declared status or environment traits, or in the compiled application's distributed `outputs_to` declaration. -| Role | Declaration | Ownership | +| Value or operation | Declaration | Where it comes from or goes | |---|---|---| -| Status input | `inputs_` | object state or a compiled model producer | -| Environment input | `environment_inputs_` | the active forcing backend | -| Constant | the `constants` argument | simulation configuration, not mutable status | -| Manual model call | `dep` plus `ModelSpec(...; calls=...)` | explicit callee execution; the callee keeps its own variable declarations | -| Local status output | `outputs_` | the target object's runtime status | -| Distributed output | `ModelSpec(...; outputs_to=...)` | explicitly selected destination objects | +| Object input | `inputs_` | A value on the object or an output from another model | +| Environment input | `environment_inputs_` | Weather data or local growing conditions | +| Constant | the `constants` argument | Values supplied for the simulation, such as physical constants | +| Manual model call | `dep` plus `ModelSpec(...; calls=...)` | Another model that this model decides when to run | +| Output on the current object | `outputs_` | The object on which this model runs | +| Outputs on other objects | `ModelSpec(...; outputs_to=...)` | Selected objects, such as leaves receiving a scene light calculation | ## Manual Dependencies -Implement `dep(model)` only when the model directly calls another process from -inside its own `run!` method: +Use `dep(model)` to suggest default input connections with `Input`, or models +to call with `Call`. A `Call` declaration is needed when the model directly +runs another process from inside its own `run!` function: ```julia PlantSimEngine.dep(::EnergyBalance) = ( @@ -99,10 +107,11 @@ PlantSimEngine.dep(::EnergyBalance) = ( ``` The scenario may override that default selector with -`ModelSpec(...; calls=...)`. The parent executes all resolved targets with -`run_call!(context, :photosynthesis)`, which always returns a vector-like -collection. Use `call_targets` plus `run_call!(target)` when the parent needs -selective trials and accepted publication. +`ModelSpec(...; calls=...)`. The calling model runs all selected photosynthesis models with +`run_call!(context, :photosynthesis)`, which returns a collection even when +there is only one model. Use `call_targets` to inspect that collection first +and `run_call!(target)` to run individual entries. This lets you try values +and record only the accepted result with `publish=true`. ## Timing @@ -113,11 +122,17 @@ selective trials and accepted publication. PlantSimEngine.timespec(::Type{<:DailyGrowth}) = ClockSpec(24.0, 1.0) ``` +Here, `24.0` means every 24 simulation steps and `1.0` sets the first +execution at step 1: the model runs at steps 1, 25, 49, and so on. This is +daily execution only when the simulation uses hourly steps. + Use `ModelSpec(...; every=Dates.Day(1))` when the cadence should be expressed -as a physical duration relative to the scenario environment. A +in hours or days relative to the simulation's weather time step. A `Dates.Period` is not a `ClockSpec` constructor argument. -`output_policy(model)` declares the default temporal policy per output: +`output_policy(model)` says how another model should read an output when +the two models run at different time steps. For example, it can request a +sum or a mean over a time window: ```julia PlantSimEngine.output_policy(::Type{<:MyModel}) = ( @@ -147,23 +162,31 @@ PlantSimEngine.environment_inputs_(::LeafEnergyBalance) = ( ) ``` -Mutable microclimate updates should be committed explicitly by controller -models: +If a controller changes growing conditions, declare the variables it may +update with `environment_outputs_`. For example, a canopy controller that +adjusts temperature declares: + +```julia +PlantSimEngine.environment_outputs_(::CanopyController) = (T=0.0,) +``` + +Once its calculation is accepted, the controller saves the new conditions +with `commit_environment!`. This operation requires the output declaration: ```julia commit_environment!(context, accepted_environment) ``` -For trial solves, pass a backend-specific state with `environment` so each -hard-called model keeps its compiled provider or spatial handle: +To try temporary growing conditions, pass them through `environment`. Each +called model still receives the conditions for its own location: ```julia run_call!(context, :leaf_energy; environment=trial_environment, publish=false) ``` -Diagnostic variables such as canopy temperature or vapor-pressure deficit can -still be regular `outputs_`, but status fields are not the transport mechanism -for mutable environment state. +You can also record canopy temperature or vapor-pressure deficit in +`outputs_`. Changing these outputs alone does not update the environment +that other models read; use `commit_environment!` for that. ## Precedence diff --git a/docs/src/planned_features.md b/docs/src/planned_features.md index af2e89cc4..657f27a60 100644 --- a/docs/src/planned_features.md +++ b/docs/src/planned_features.md @@ -1,20 +1,21 @@ # Roadmap -PlantSimEngine now has one composite-model/object runtime for single-object, multiscale, -multi-plant, soil, microclimate, and multirate simulations. +PlantSimEngine uses the same simulation engine for a single object or many +plants and organs, including models that run at different time steps. This +page lists work planned to extend and check these capabilities. Current priorities are: - migrate downstream model packages to `CompositeModel`, `CompositeModelTemplate`, `ObjectInstance`, and `ModelSpec`; - strengthen type-stability and allocation tests for million-object workloads; -- add broader lifecycle tests for object creation, removal, movement, and - environment-index refresh; -- improve diagnostics for ambiguous selectors, writer conflicts, and temporal - policies; +- test more combinations of adding, removing, and moving objects, including + updates to their local growing conditions; +- make error reports clearer when object selections match too many objects, + models try to set the same output, or time-step connections need attention; - validate mutable voxel, layer, and octree microclimate backends; -- expand downstream release gates and performance benchmarks; -- evaluate parallel execution for independent compiled application batches. +- test more dependent packages and simulation performance before releases; +- investigate running independent groups of model calculations in parallel. ## Environment and microclimate work @@ -43,11 +44,10 @@ commit_environment!(context, accepted_environment) run_call!(context, :leaf_energy; publish=true) ``` -The transient state is interpreted by each target backend through its opaque -compiled handle, so one call can sample different cells for different leaves. -`commit_environment!` commits only the accepted state to a mutable backend. -Future work is to validate full voxel, layer, and octree implementations on -this same model-side API. +Each leaf still receives conditions for its own location, so one call can +supply different trial values to different leaves. `commit_environment!` +saves only the accepted growing conditions. Future work will test this +approach with environments represented by cells, layers, and octrees. The full issue list is available on [GitHub](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues). diff --git a/docs/src/prerequisites/installing_plantsimengine.md b/docs/src/prerequisites/installing_plantsimengine.md index 67c135dbf..b4801a847 100644 --- a/docs/src/prerequisites/installing_plantsimengine.md +++ b/docs/src/prerequisites/installing_plantsimengine.md @@ -1,23 +1,43 @@ # Installing PlantSimEngine +!!! compat "Use the package version described by this manual" + These development pages use the `CompositeModel` API. Registered releases + through 0.14.1 use the previous mapping API. Follow the commands below to + use the development version, or use the documentation matching your + installed release. For a pull-request preview, replace `"main"` with the + branch or commit shown by that pull request so its examples and package + sources match. + Install Julia from the [official download page](https://julialang.org/downloads/), create a project -environment, and add PlantSimEngine: +environment (a folder that records the packages used for this simulation), +and install the tutorial packages: ```julia using Pkg Pkg.activate("my_simulation") -Pkg.add("PlantSimEngine") +Pkg.add(["PlantMeteo", "DataFrames", "CairoMakie"]) +Pkg.add(url="https://github.com/VirtualPlantLab/PlantSimEngine.jl", rev="main") ``` -Most simulations also use PlantMeteo: +PlantMeteo supplies weather data, DataFrames organizes the results, and +CairoMakie draws the tutorial figures. Run these commands at Julia's +interactive prompt, also called the **REPL**; +`my_simulation` is the project directory created relative to your current +working directory. In a later session, run `Pkg.activate("my_simulation")` +from the same location before using the project again. -```julia -Pkg.add("PlantMeteo") -``` +For reproducible work, record the package revision and keep the generated +`Project.toml` and `Manifest.toml` with your experiment. The development branch +can change; a commit revision selects one exact version. ## First Simulation +This small example calculates how much light a canopy absorbs. Its leaf area +index is 2 m² of leaves per m² of ground, and incoming photosynthetically +active radiation (PAR) is 500 W m⁻² of ground. The canopy is one simulated +object; individual leaves are not represented. + ```@example install using PlantSimEngine, PlantMeteo, Dates using PlantSimEngine.Examples @@ -33,17 +53,23 @@ meteo = Atmosphere( model = CompositeModel( Beer(0.5); status=(LAI=2.0,), - id=:leaf, - scale=:Leaf, + id=:canopy, + scale=:Canopy, environment=meteo, ) simulation = run!(model) -final_state(simulation, One(scale=:Leaf)).aPPFD +(absorbed_PAR_umol_m2_ground_s=final_state(simulation).aPPFD,) ``` -Example models are provided by the `PlantSimEngine.Examples` submodule. They -are useful for learning and tests but are not part of the core modeling API. +`using PlantSimEngine.Examples` loads the example models, including `Beer`. +These models are included for learning and testing. + +The result is the amount of light absorbed by the canopy, expressed in μmol +of photons per m² of ground per second. The inputs are +illustrative, not a calibrated crop scenario. Next, +[couple three models over time](../journeys/users/one_object.md), then +[collect and plot their outputs](../guides/data/outputs_plotting.md). For local package development, use `Pkg.develop(path="...")`. Run the package tests with `Pkg.test("PlantSimEngine")`. diff --git a/docs/src/prerequisites/julia_basics.md b/docs/src/prerequisites/julia_basics.md index 707ad6122..8992cbabd 100644 --- a/docs/src/prerequisites/julia_basics.md +++ b/docs/src/prerequisites/julia_basics.md @@ -1,53 +1,66 @@ # Getting started with Julia -PlantSimEngine (as well as its related packages) is written in Julia. The reasons why Julia was chosen are briefly discussed here : [The choice of using Julia](@ref). - -Julia is a language that is gaining traction, but it isn't the most widely used in research and data science. - -Many elements will be familiar to those with an R, Python or Matlab background, but there are some noteworthy differences, and if you are new to the language, there will be a few hurdles you might have to overcome to be comfortable using the language. - -This page is here to list to the parts of Julia that are most relevant regarding usage of PlantSimEngine, and point to resources that can help you grasp those basics. +You can run the PlantSimEngine tutorials without knowing all of Julia. Start +by copying a complete example, then change one parameter and compare the +result. This page explains a few patterns you will see along the way. ## New to programming -It is not meant as a full-fledged from-scratch Julia tutorial. If you are completely new to programming, you may wish to check some other resources first, such as ones found [here](https://docs.julialang.org/en/v1/manual/getting-started/). The video course [Julia Programming for Nervous Beginners](https://www.youtube.com/playlist?list=PLP8iPy9hna6Qpx0MgGyElJ5qFlaIXYf1R) is tailored for people with no programming experience. - -## Installing packages and setting up and environment - -For PlantSimEngine, you can check our documentation page on the topic: -[Installing PlantSimEngine](installing_plantsimengine.md). - -## Cheatsheets - -You can also find a few cheatsheets [here](https://palmstudio.github.io/Biophysics_database_palm/cheatsheets/) as well as a [short introductory notebook](https://palmstudio.github.io/Biophysics_database_palm/basic_syntax/) along with its [install instructions](https://palmstudio.github.io/Biophysics_database_palm/installation/). +The [Julia getting-started guide](https://docs.julialang.org/en/v1/manual/getting-started/) +explains how to start Julia and enter commands. If you prefer a video course, +[Julia Programming for Nervous Beginners](https://www.youtube.com/playlist?list=PLP8iPy9hna6Qpx0MgGyElJ5qFlaIXYf1R) +is aimed at people with no programming experience. -## Troubleshooting - -For more Julia learning-related difficulties, you will find quick responses on the Discourse forum: [https://discourse.julialang.org](https://discourse.julialang.org). - -### Noteworthy differences with other languages: - -If you wish to compare Julia to a specific language, [the noteworthy differences section](https://docs.julialang.org/en/v1/manual/noteworthy-differences/#Noteworthy-differences-from-Python) will provide you with a quick overview of the differences. +## Installing packages and setting up an environment -(Array indexing starts at 1, for example) +Follow [Installing PlantSimEngine](installing_plantsimengine.md) to create a +project folder and install the tutorial packages. A project environment +records which packages and versions your simulation uses. ## Essential Julia concepts for PlantSimEngine -Here's a list of the main aspects of the Julia language required (beyond package management) to understand how to use PlantSimEngine to its potential: +The first tutorials mainly use these patterns: + +| Code | Meaning | +|---|---| +| `lai = 2.0` | Store a value under the name `lai` | +| `Beer(0.6)` | Create a Beer model with an extinction coefficient of 0.6 | +| `run!(model; steps=30)` | Run a function, with the named option `steps=30` | +| `(LAI=2.0, TT=12.0)` | Group named values in a **named tuple** | +| `[1.0, 2.0, 3.0]` | Create an array of three values | +| `values[1]` | Read the first array entry; Julia indexing starts at 1 | +| `state.LAI` | Read the value named `LAI` from `state` | +| `values .* 2` | Multiply every array entry by 2 | + +Options such as `steps=30` are called **keyword arguments**. The semicolon +separates these named options from the other arguments. A dot before an +operator, as in `.*`, applies the operation to each array entry. Julia calls +this **broadcasting**. + +A function name ending in `!`, such as `run!` or `step!`, usually means that +the function changes something it was given. Here, running a simulation +updates its objects' values. + +When you start writing models, you will also meet **types** and **methods**. +A type describes a kind of value; a model type can store its parameters. +A method is a version of a function for particular types of arguments. +The [first model tutorial](../journeys/modelers/basic_model.md) introduces +these ideas with a complete equation and its parameters. -Standard notions and constructs: - -- Standard concepts of a variable, arrays, functions, function arguments -- The typing system and custom types -- Dictionaries and NamedTuple objects are used throughout the codebase - -The Julia manual goes more in-depth than lighter introductions to some of these topics, so might be more useful as a reference than a starting point. You might find other guides or courses, such as the first section in [https://julia.quantecon.org/intro.html](https://julia.quantecon.org/intro.html), chapters 0-4 and 7 of the [Learn Julia the Hard Way](https://scls.gitbooks.io/ljthw/content/) draft or the interactive [Mathigon course](https://mathigon.org/course/programming-in-julia/introduction). +## Cheatsheets -Also of importance: +The [Julia Data Science basics](https://juliadatascience.io/julia_basics) +cover common syntax and working with tables. There are also +[cheatsheets](https://palmstudio.github.io/Biophysics_database_palm/cheatsheets/) +and a [short introductory notebook](https://palmstudio.github.io/Biophysics_database_palm/basic_syntax/). -- [Keyword arguments](https://docs.julialang.org/en/v1/manual/functions/#Keyword-Arguments) (kwargs) are present in many API functions -- [Type promotion](https://docs.julialang.org/en/v1/manual/conversion-and-promotion/#Promotion), [splatting](https://docs.julialang.org/en/v1/base/base/#...), [broadcasting](https://docs.julialang.org/en/v1/manual/functions/#man-vectorized), and [comprehensions](https://docs.julialang.org/en/v1/manual/arrays/#man-comprehensions) are also very useful, but not compulsory to get started +## Troubleshooting -Many of these are also briefly presented in [this Julia Data Science](https://juliadatascience.io/julia_basics) guide, which also happens to focus on the DataFrames.jl package. +Ask Julia language questions on [Julia Discourse](https://discourse.julialang.org). +For errors from PlantSimEngine, use the +[common errors guide](../troubleshooting/common_errors.md). -Understanding more about methods, parametric types and the typing system is usually worthwhile, when working with Julia packages. +If you know R, Python, or MATLAB, Julia's +[comparison with other languages](https://docs.julialang.org/en/v1/manual/noteworthy-differences/) +explains differences you may encounter. You can read about more advanced +features, such as type promotion and parametric types, when a model needs them. diff --git a/docs/src/prerequisites/key_concepts.md b/docs/src/prerequisites/key_concepts.md deleted file mode 100644 index 2f254e75c..000000000 --- a/docs/src/prerequisites/key_concepts.md +++ /dev/null @@ -1,108 +0,0 @@ -# Key Concepts - -## Processes And Models - -A process identifies a biological or physical phenomenon, such as -photosynthesis, growth, water balance, or energy balance. A model is one -implementation of a process. - -Models subtype `AbstractModel` and declare: - -- `inputs_`: values read from object status, each declared as `Required(T)` or - `Default(value)`; -- `outputs_`: values written to object status; -- `environment_inputs_`: values sampled from the environment; -- `environment_outputs_`: environment variables a controller may commit; -- `commit_environment!`: accepted meteorological state committed to a mutable - environment by controller models; -- `dep`: processes called manually by the model, when required. - -The numerical kernel is implemented with: - -```julia -PlantSimEngine.run!(model, status, environment, constants, context) -``` - -`Required(T)` describes an input that must be supplied by object state or -another application. `Default(value)` is a true model fallback that -PlantSimEngine can initialize automatically. Output literals are initial -output-state values. - -## Composite Models And Objects - -A `CompositeModel` contains objects and model applications. An `Object` can represent a -model, plant, soil volume, axis, internode, leaf, sensor, or any other simulated -entity. PlantSimEngine does not impose one plant architecture. - -Objects can carry: - -- a stable identifier; -- scale, kind, species, and name metadata; -- parent-child relationships; -- geometry and position; -- mutable `Status`; -- object-local model applications. - -`CompositeModelTemplate` packages reusable applications for a species or object type. -`ObjectInstance` mounts the template in a model. Several instances can share -models and parameters while declaring targeted overrides for exceptional -objects. - -## Model Applications - -`ModelSpec` configures one use of a model: - -- `ModelSpec(...; on=...)` selects target objects; -- `ModelSpec(...; inputs=...)` selects producers for value dependencies; -- `ModelSpec(...; calls=...)` binds manually controlled model calls; -- `ModelSpec(...; every=...)` selects the execution cadence; -- `Environment(...)` configures environment sampling; -- `Updates(...; after=:application_id)` orders intentional additional writers; -- `ModelSpec(...; output_routing=...)` controls output publication. - -This keeps model implementations generic. Models do not need to know which -model, object, timestep, or coupling scenario will use them. - -## Soft And Manual Dependencies - -Ordinary dependencies are inferred by matching model inputs with outputs and -are compiled into an acyclic execution order. `ModelSpec(...; inputs=...)` is used when the -source is cross-object, renamed, temporal, or otherwise ambiguous. - -Some algorithms need direct call-stack control. For example, a model energy -balance may repeatedly call leaf energy-balance models until canopy -microclimate converges. Such dependencies are bound with `ModelSpec(...; calls=...)`; the -parent invokes them with `run_call!`. - -## Status And References - -`Status` stores variables in references. Same-rate coupling normally shares -those references instead of copying values. A many-object input uses a -reference vector, so aggregation models read current source values directly. - -Temporal coupling uses published streams when producer and consumer clocks -differ. Policies include `HoldLast`, `Interpolate`, `Integrate`, `Aggregate`, -and `PreviousTimeStep`. - -## Environment - -The active environment backend may be: - -- one constant atmosphere shared by all objects; -- a time-indexed weather table; -- a mutable layer, voxel, grid, or octree microclimate. - -Object-to-environment support is compiled and cached. Geometry changes mark the -binding dirty so it can be refreshed without recomputing spatial lookup at -every timestep. - -## Multiscale Plant Structure - -PlantSimEngine treats scale and object hierarchy as scenario data. A plant may -use leaves directly under a plant, or axes, segments, internodes, roots, and -other intermediate levels. Selectors express relationships such as one source, -many descendants, the current plant, an ancestor, or all matching objects in -the model. - -MultiScaleTreeGraph objects can be imported with `objects_from_mtg`, but the -runtime operates on the same composite-model/object representation afterward. diff --git a/docs/src/step_by_step/advanced_coupling.md b/docs/src/step_by_step/advanced_coupling.md index 907953a44..e5efe7d6c 100644 --- a/docs/src/step_by_step/advanced_coupling.md +++ b/docs/src/step_by_step/advanced_coupling.md @@ -10,44 +10,49 @@ meteo_day = read_weather( ) ``` -Most model coupling is a value dependency: one model writes an output, another -model reads it as an input. Some models need tighter control. For example, an -energy-balance model may call photosynthesis and stomatal-conductance models -several times while it iterates leaf temperature. +Usually, coupling means that one model calculates a value and another reads +it. Sometimes a model must also decide when the other calculation runs. For +example, an energy-balance model may run photosynthesis and +stomatal-conductance models several times while trying to find the leaf +temperature that balances heat gains and losses. -That second case is a manual call dependency. In the composite-model/object API it is -declared with `ModelSpec(...; calls=...)`. +That second case is called a **manual call** or **hard dependency**. Declare +it with `ModelSpec(...; calls=...)`. ## Soft inputs and manual calls -Use `ModelSpec(...; inputs=...)` or inferred same-object bindings when a model only needs a -value. Use `ModelSpec(...; calls=...)` when the parent model must directly run another model -inside its own `run!` method. +An ordinary input connection is also called a **soft dependency**. Set it +with `ModelSpec(...; inputs=...)`. PlantSimEngine connects inputs automatically +on the same object when exactly one model supplies the required variable. +Use `ModelSpec(...; calls=...)` when one model must run another from inside +its own `run!` function. The example process models in `examples/dummy.jl` contain both patterns: - `Process4Model` computes `var1` and `var2`; -- `Process1Model` consumes `var1` and `var2` and computes `var3`; +- `Process1Model` reads `var1` and `var2` and computes `var3`; - `Process2Model` manually calls process 1, then computes `var4` and `var5`; - `Process3Model` manually calls process 2, then computes `var6`; -- `Process5Model`, `Process6Model`, and `Process7Model` use regular soft - value dependencies. +- `Process5Model`, `Process6Model`, and `Process7Model` read other models' + results through ordinary inputs. ## Declaring manual calls in the scenario -`ModelSpec(...; calls=...)` is scenario-level wiring. The model kernel remains generic; the -scenario decides which concrete application is called. +The simulation setup chooses which models are called. The model's `run!` +function can then keep the same equations when those choices change. -Use `application=...` in scenario-level `ModelSpec(...; calls=...)` and `ModelSpec(...; inputs=...)` when you -know which mounted model application should provide the value or be called. Use -process identities in model-level contracts such as `dep(model)`, where the -model author only declares that a compatible process is required and cannot know -the names chosen by future scenarios. +A **model application** is a model configured with a name, selected objects, +and any input or timing settings. In the setup below, use `application=...` +to choose that name in a call or input connection. -This split avoids ambiguity when several applications implement the same -process. For example, two soil-water applications can share the same process but -represent different layers, parameter sets, objects, or time steps. A scenario -selector should name the application that has the intended role. +This matters when you use the same process in several places. For example, +two soil-water models may represent different layers. Naming the application +lets you choose the intended layer. + +When writing a reusable model, you will not know the names that future +simulations choose. Its `dep(model)` declaration can instead ask for the +scientific process it needs. The simulation then connects that request to +an application. ```@example scene_advanced_coupling complex_scene = CompositeModel( @@ -80,15 +85,15 @@ select( ) ``` -Applications selected by `ModelSpec(...; calls=...)` are not scheduled as independent root -applications under their caller. They run only when the parent calls them. -This gives the parent full call-stack control. +The table shows which model each named call will run. Models used only +through these calls run when their caller asks them to; they do not also +run independently at each time step. ## Running the coupled model -The regular soft dependencies are still inferred from `inputs_` and -`outputs_`. The scheduler combines those soft edges with the call ownership -rules: +PlantSimEngine still connects ordinary inputs from the models' `inputs_` +and `outputs_` declarations. It uses those connections and the manual calls +to determine which calculations run first. Inspect that order: ```@example scene_advanced_coupling select( @@ -115,16 +120,16 @@ complex_status = final_state(complex_sim) ## Writing new hard-coupled models -For new composite-model/object models, execute all targets directly when they -share meteorology and publication policy: +Inside a model, run all models and objects selected by a named call with: ```julia targets = run_call!(context, :leaf_energy; publish=true) ``` -The result is always vector-like. Retrieve targets without executing them when -an algorithm needs selective execution or an already sampled environment for -each target: +The result is a collection of **targets**, each representing a called model +on one object. To choose individual targets before running them, use +`call_targets`. This also lets you pass different environmental values to +each one: ```julia targets = call_targets(context, :leaf_energy) @@ -137,8 +142,10 @@ for (target, leaf_environment) in zip(targets, environments_by_leaf) end ``` -For a provider-aware trial state shared by the call, keep the execute-all form. -Each target still samples through its own compiled handle: +If an environment provider supplies values for different positions, you can +give it a trial state for the whole call. PlantSimEngine then reads the +appropriate values for each target's location. The following outline shows +the order; your model must define how to calculate and accept a trial: ```julia function PlantSimEngine.run!(model::SceneEnergyBalance, status, environment, @@ -154,14 +161,16 @@ function PlantSimEngine.run!(model::SceneEnergyBalance, status, environment, end ``` -`run_call!` defaults to `publish=false`, which is useful for trial iterations. -Pass non-committing trial state with the `environment` keyword. Use -`commit_environment!` and `publish=true` for the accepted state so temporal -streams and mutable environment state are published once. - -The MAESPA-style example uses the same mechanism: a model energy-balance model -calls all selected leaf energy-balance models and the shared soil model while -it solves canopy microclimate. - -Scenario wiring uses `ModelSpec(...; calls=...)`. Model authors should keep kernels generic -and only require manual calls when the model really needs call-stack control. +`run_call!` defaults to `publish=false`: trial results are not saved as +accepted samples for output history or time-based connections. Pass a trial +environment with the `environment` keyword. Once you accept a solution, +`commit_environment!` writes its environmental values, and a call with +`publish=true` saves the accepted result. Trial calculations can still change +the objects' current values, so your algorithm must handle any changes it +needs to discard. + +The MAESPA-style example uses the same approach: a canopy energy-balance +model calls the leaf energy-balance models and the shared soil model while +it solves canopy microclimate. Use manual calls for calculations that need +this control. An ordinary input is enough when a model simply reads +another model's result. diff --git a/docs/src/step_by_step/detailed_first_example.md b/docs/src/step_by_step/detailed_first_example.md deleted file mode 100644 index 5a762b2dd..000000000 --- a/docs/src/step_by_step/detailed_first_example.md +++ /dev/null @@ -1,225 +0,0 @@ -# [Detailed Walkthrough Of A Simple Simulation](@id detailed-walkthrough-of-a-simple-simulation) - -This page walks through a small composite-model/object simulation. It is written for -readers who are still getting comfortable with Julia and PlantSimEngine. - -If you only want examples to copy and modify, see [Quick examples](quick_and_dirty_examples.md). For -multi-object and multi-plant simulations, the same API scales up: add objects, -select them with `ModelSpec(...; on=...)`, connect values with `ModelSpec(...; inputs=...)`, and use -`ModelSpec(...; calls=...)` when a parent model must manually run child models. - -```@setup detailed_scene -using PlantSimEngine, PlantMeteo, Dates, DataFrames -using PlantSimEngine.Examples - -meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); - duration=Dates.Day, -) -``` - -```@contents -Pages = ["detailed_first_example.md"] -Depth = 3 -``` - -## Setting Up Your Environment - -Every script needs a Julia environment with PlantSimEngine installed. Most -examples also use companion packages such as PlantMeteo for weather data and -DataFrames for tabular outputs. Installation details are in -[Installing PlantSimEngine](../prerequisites/installing_plantsimengine.md). - -## The Simulation Pieces - -### Processes And Models - -A process is something you want to simulate, such as light interception, -photosynthesis, water flux, growth, yield, or energy balance. - -A model is one implementation of a process. In this page we use the example -`Beer` model, which implements a Beer-Lambert light-interception equation. -Its only parameter is the extinction coefficient `k`. - -```@example detailed_scene -fieldnames(Beer) -``` - -The model implementation declares the status variables it reads and writes: - -```@example detailed_scene -inputs(Beer(0.5)) -``` - -```@example detailed_scene -outputs(Beer(0.5)) -``` - -These declarations are the modeler's contract. The composite-model/object layer decides -where the model runs and where those values come from. - -### CompositeModel Objects - -A `CompositeModel` contains simulated `Object`s. An object can represent a model, plant, -axis, leaf, soil layer, sensor, voxel, or any other simulated entity. - -For a first example, we use one object representing the whole model. The `Beer` -model reads `LAI`, so we initialize that variable on the object status. - -```@example detailed_scene -model = CompositeModel( - Beer(0.5); - status=(LAI=2.0,), - environment=meteo_day, - timestep=Day(1), -); -nothing -``` - -The concise constructor creates one ordinary model object and one application -for each supplied model. `status` initializes that object, `timestep` applies a -common daily cadence, and `environment` supplies weather values such as -radiation. Use explicit `ModelSpec` and selectors when applications need -different policies or targets. - -## Inspecting The Compiled CompositeModel - -Before runtime, PlantSimEngine resolves selectors and builds a compiled model. -This avoids resolving object selections inside the timestep loop. - -```@example detailed_scene -select( - DataFrame(Diagnostics.explain_applications(model)), - :application_id, - :process, - :target_ids, -) -``` - -`Beer` has no model-to-model value input in this first model because `LAI` was -initialized directly on the object status: - -```@example detailed_scene -Diagnostics.explain_bindings(model) -``` - -The schedule tells us when each application runs: - -```@example detailed_scene -select( - DataFrame(Diagnostics.explain_schedule(model)), - :application_id, - :dt_seconds, - :root_scheduled, - :manual_call_only, -) -``` - -## Running The Simulation - -Run the model with [`run!`](@ref): - -```@example detailed_scene -sim = run!(model; steps=3, outputs=:all) -nothing -``` - -Final state is available independently of retained output history: - -```@example detailed_scene -scene_status = final_state(sim) -(LAI=scene_status.LAI, aPPFD=scene_status.aPPFD) -``` - -The returned `Simulation` stores retained output streams: - -```@example detailed_scene -first(collect_outputs(sim; sink=nothing), 3) -``` - -For a table, use the default `DataFrame` sink: - -```@example detailed_scene -first(collect_outputs(sim), 3) -``` - -## Adding A Model Coupling - -Now let a daily LAI model compute `LAI` before the light-interception model -runs. `ToyLAIModel` reads cumulative thermal time `TT_cu` and writes `LAI`. -Because `Beer` reads `LAI`, the compiler can infer the same-object binding. - -```@example detailed_scene -coupled_scene = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.5); - status=(TT_cu=0.0,), - environment=meteo_day, - timestep=Day(1), -) - -select( - DataFrame(Diagnostics.explain_bindings(coupled_scene)), - :application_id, - :input, - :source_application_ids, - :carrier_kind, - :copy_semantics, -) -``` - -The `LAI` binding uses a live reference carrier, so the light-interception -model sees the value written by the LAI model without copying it. - -Run the coupled model: - -```@example detailed_scene -coupled_sim = run!(coupled_scene; steps=5, outputs=:all) -first(collect_outputs(coupled_sim), 8) -``` - -The final object status contains the latest values from the coupled models: - -```@example detailed_scene -coupled_status = final_state(coupled_sim) -(TT_cu=coupled_status.TT_cu, LAI=coupled_status.LAI, aPPFD=coupled_status.aPPFD) -``` - -## What Needs Initialization? - -Model `inputs_(...)` explicitly distinguishes `Required(T)` from -`Default(value)`. A required input needs user state or a producer binding; a -defaulted input needs neither. In a coupled model, an upstream application can -satisfy a required input. - -Use the compiler explanations to distinguish the two cases: - -- `:supplied` means the object `Status` already provides the value; -- `:producer_bound` means another application supplies it; -- `:defaulted` means `Default(value)` initialized it; -- `:required` means it still has no source and compilation will fail. - -For example, if we remove `TT_cu` from the model status, compilation fails -because no model in this model computes it before `ToyLAIModel` reads it: - -```@example detailed_scene -bad_scene = CompositeModel( - ToyLAIModel(); - environment=meteo_day, -) - -try - Diagnostics.explain_bindings(bad_scene) -catch err - first(sprint(showerror, err), 300) -end -``` - -## Next Steps - -- [Standard model coupling](@ref) shows more coupling patterns. -- [CompositeModel/Object Quickstart](../composite_model/quickstart.md) is the shortest - copy-pasteable path for the new API. -- [Model execution](../model_execution.md) explains scheduling, temporal inputs, hard calls, - output retention, and lifecycle refreshes. diff --git a/docs/src/step_by_step/implement_a_model.md b/docs/src/step_by_step/implement_a_model.md deleted file mode 100644 index f2a63d5d3..000000000 --- a/docs/src/step_by_step/implement_a_model.md +++ /dev/null @@ -1,31 +0,0 @@ -# [Implementing a model](@id model_implementation_page) - -The canonical, executable model-authoring tutorial is now -[Implement a basic model](@ref). Start there for the complete five-argument -kernel contract, direct testing, same-object coupling, and reuse over several -objects. - -Before declaring a new abstract process type, use -[New process or new model?](@ref) to determine whether the implementation is a -new scientific process or another hypothesis for an existing process. - -Then continue according to the model's needs: - -- [Port an existing model](@ref) explains how to keep a scientific kernel - readable and generic; -- [Model repository layout and tests](@ref) places the process, model, - documentation, and test levels in a package; -- [Implement Cross-Object Values](@ref) covers `One`, `OptionalOne`, - `Many`, and `Subtree()`; -- [Coupling models](@ref) distinguishes value coupling, hard calls, and - explicit adapters; -- [Model compatibility and replacement](@ref) distinguishes process identity - from drop-in substitutability; -- [Model Traits](@ref) documents environment, timing, output, and scientific - variable contracts. - -!!! compat - Older versions of this page showed a hard dependency as an abstract model - type returned directly by `dep(model)`. The current API declares a - `Call(selector)`, for example - `(stomata=Call(One(process=:stomatal_conductance)),)`. diff --git a/docs/src/step_by_step/implement_a_model_additional.md b/docs/src/step_by_step/implement_a_model_additional.md deleted file mode 100644 index 80822b10f..000000000 --- a/docs/src/step_by_step/implement_a_model_additional.md +++ /dev/null @@ -1,113 +0,0 @@ -# Model implementation additional notes - -```@contents -Pages = ["implement_a_model_additional.md"] -Depth = 3 -``` - -## Parametric types - -In [Implementing a model](@ref model_implementation_page), the Beer model's structure was declared with a parametric type. - -```julia -struct Beer{T} <: AbstractLight_InterceptionModel - k::T -end -``` - -Why not force the type ? Float64 is more accurate than Float32, after all: - -```julia -struct YourStruct <: AbstractLight_InterceptionModel - k::Float64 - x::Float64 - y::Float64 - z::Int -end -``` - -Doing so would lose some flexibility in the way users can make use of your models. For example a user could use the `Particles` type from [MonteCarloMeasurements.jl](https://github.com/baggepinnen/MonteCarloMeasurements.jl) for automatic uncertainty propagation, and this is only possible if the model type is parameterizable. Forcing a `Float64` type would render the model incompatible with `Particles`. - -## Promoting model constructor arguments - -When implementing a new model, you can do a little optional extra work to help future users. - -You can add a constructor that uses Julia's `promote` function. This is -promotion of model parameters while constructing the model; it is distinct -from the `CompositeModel(...; type_promotion=...)` policy that converts status -values for a scenario. See [Numerical Reliability](@ref) for that status -policy. - -Constructor promotion would not make any difference for the previous `Beer` -example because it has only one parameter. Consider instead a `Beer2` model -with two parameters: - -```julia -struct Beer2{T} <: AbstractLight_InterceptionModel - k::T - x::T -end -``` - -To add type promotion to `Beer2` we would do: - -```julia -function Beer2(k,x) - Beer2(promote(k,x)...) -end -``` - -!!! note - `promote` returns a tuple, which is splatted into the constructor above. - See the [Julia documentation](https://docs.julialang.org/en/v1/manual/conversion-and-promotion/#Promotion) - for a more in-depth explanation. - -This would allow users to instantiate the model parameters using different types of inputs. For example users may write the following: - -```julia -Beer2(0.6,2) -``` - -`Beer2` is a parametric type, with all fields sharing the same type `T`. This is the `T` in `Beer2{T}` and then in `k::T` and `x::T`. And this forces the user to give all parameters with the same type. - -In the example above, `0.6` for `k` is a `Float64`, while `2` for `x` is an -`Int`. Constructor promotion converts both arguments to a common type when -possible. In this case it converts `2` to `2.0`. - -## Other helper functions and constructors - -### Default parameter values - -You can simplify model usage by helping your user with default values for some parameters (if applicable). For example, in the `Beer` model a user will almost never change the value of `k`. So we can provide a default value like so: - -```@example usepkg -Beer() = Beer(0.6) -``` - -Now the user can call `Beer` with no arguments, and `k` will default to `0.6`. - -### Parameter values as kwargs - -Another useful thing is the ability to instantiate your model type with keyword arguments, *i.e.* naming the arguments. You can do it by adding the following method: - -```@example usepkg -Beer(;k) = Beer(k) -``` - -The `;` syntax indicates that subsequent arguments are provided as keyword arguments, so now we can call `Beer` like this: - -```julia -Beer(k = 0.7) -``` - -This helps readability when there are a lot of parameters and some have default values. - -### eltype - -The last optional utility function to implement is a method for the `eltype` function: - -```julia -Base.eltype(x::Beer{T}) where {T} = T -``` - -This one helps Julia know the type of the elements in the structure, and make it faster. diff --git a/docs/src/step_by_step/implement_a_process.md b/docs/src/step_by_step/implement_a_process.md index 71b65c416..8ed6b645e 100644 --- a/docs/src/step_by_step/implement_a_process.md +++ b/docs/src/step_by_step/implement_a_process.md @@ -1,63 +1,66 @@ # New process or new model? -A process names a biological or physical question. A concrete model is one -hypothesis, formulation, or scale at which that process is computed. Make this -choice before writing the model type: it determines whether users can discover -your implementation beside existing alternatives. +A **process** names a biological or physical question. A **model** is one +hypothesis or formulation used to answer it. For example, two photosynthesis +equations can belong to the same process even if they need different inputs. -## Prefer an existing process +Before creating a model, check whether the process already exists. That lets +users find your implementation beside the alternatives they may want to compare. -Start by loading the packages that may own the process and inspect what they -declare: +## Find the existing family + +Load the package that provides the models. This example uses the teaching models +distributed with PlantSimEngine: ```@example choose_process using PlantSimEngine +using PlantSimEngine.Examples -Authoring.available_processes() +growth_models = Authoring.available_models(AbstractGrowthModel) +growth_models ``` -`Authoring.available_processes()` can only see loaded Julia modules. Search the source of -the target package as well before deciding that a process is missing. The -[Loaded model catalog](@ref) shows the same discovery result grouped into a -generated table with provenance and completeness. - -Reuse an existing abstract process type when the new implementation answers -the same scientific question. Examples include two photosynthesis -formulations, a simple and a water-stress-aware radiation-use-efficiency model, -or the same process represented at different scales. Give each hypothesis its -own concrete model instead of adding a `method=:a_or_b` switch to one large -kernel. - -Models in the same process form a scientific family, but they are not -necessarily interchangeable. They may require different inputs, produce -different outputs, use different clocks, or declare different -`VariableContract`s. See [Model compatibility and replacement](@ref) before -using one as an `Override` or replacing it without revisiting scenario -bindings. - -## Declare a process only for a new meaning +For a scientific application, load its model package first and inspect its +documentation. `Authoring.available_processes()` lists the process types +available in the packages you have loaded. `Authoring.available_models(process_type)` +then lists the model types that implement that process. -Create a process when no existing process has the same biological or physical -meaning: +Choose a model, give it a parameter value, and inspect its inputs and outputs: ```@example choose_process -PlantSimEngine.@process "docs_root_exudation" verbose=false - -abstract = AbstractDocs_Root_ExudationModel -abstract <: AbstractModel +candidate = ToyRUEGrowthModel(0.2) +( + process=process(candidate), + inputs=inputs(candidate), + outputs=outputs(candidate), +) ``` -The generated abstract type is formed by prefixing `Abstract`, preserving word -boundaries from the process name, and appending `Model`. For example: +[Loaded model catalog](@ref) explains discovery and inspection in more detail. +These functions only find packages loaded into Julia. Also check the package +you plan to use before concluding that a process is missing. -| Declaration | Generated abstract type | +## Decide what your new equation changes + +| Your change | What to create | |---|---| -| `@process "growth"` | `AbstractGrowthModel` | -| `@process "light_interception"` | `AbstractLight_InterceptionModel` | +| Another equation, assumption, or level of detail for the same question | A model under the existing process | +| A distinct biological or physical question | A new process and its model | +| A conversion such as radiation per square metre to radiation per plant | A small conversion model, called an adapter | + +Give alternative equations separate model types so users can select and test +them. To compare parameter values in the same equation, create instances of +that model with different parameters. Models in one process may need +different inputs, produce different outputs, or run at different frequencies. +Use [Model compatibility and replacement](@ref) before substituting one. -Concrete implementations subtype the generated abstract type: +## Declare a genuinely new process + +This declaration creates a process for a teaching example of root exudation: ```@example choose_process +PlantSimEngine.@process "docs_root_exudation" verbose=false + struct DocsLinearExudation{T} <: AbstractDocs_Root_ExudationModel fraction::T end @@ -65,43 +68,18 @@ end process(DocsLinearExudation(0.1)) ``` -The macro generates process identity and the abstract type; it does not choose -ports, units, parameters, defaults, equations, or scientific validation for -you. Continue with [Implement a basic model](@ref), which is the canonical -model-authoring path. +`@process` creates the abstract type that concrete models inherit from: -## A practical decision test - -Ask these questions in order: - -1. Is the quantity being simulated and its scientific meaning already - represented by a loaded process? -2. Would users reasonably compare this implementation with the existing - implementations as alternative hypotheses? -3. Is the difference only an equation, assumption, parameterization, scale, or - resolution of that same question? - -If the answers point to the same question, add a model to the existing -process. Create a new process only when the meaning itself changes. If the new -model changes units or basis while connecting two existing meanings, implement -an explicit adapter model instead; see [Coupling models](@ref). - -## Without the macro - -`@process` is a small convenience. The equivalent manual declaration is: - -```@example choose_process -abstract type AbstractDocsManualRootExudationModel <: - PlantSimEngine.AbstractModel end -PlantSimEngine.process_( - ::Type{AbstractDocsManualRootExudationModel}, -) = :docs_manual_root_exudation - -struct DocsManualRootExudation <: AbstractDocsManualRootExudationModel end +| Declaration | Generated abstract type | +|---|---| +| `@process "growth"` | `AbstractGrowthModel` | +| `@process "light_interception"` | `AbstractLight_InterceptionModel` | -manual_process = process(DocsManualRootExudation()) -@assert manual_process == :docs_manual_root_exudation -manual_process -``` +When another package already declares the process, import its abstract type +and use it after `<:` in your model definition. This puts your model in the +same family as the existing alternatives. -Prefer the macro for ordinary package code so process naming stays consistent. +The type above is only the beginning. It still needs input and output +declarations, descriptions of the variables' units and meaning, an equation, +and tests. Continue with +[Implement a basic model](@ref) to complete those steps. diff --git a/docs/src/step_by_step/model_switching.md b/docs/src/step_by_step/model_switching.md index c593a8031..c27ca7da4 100644 --- a/docs/src/step_by_step/model_switching.md +++ b/docs/src/step_by_step/model_switching.md @@ -1,188 +1,141 @@ # Model compatibility and replacement -```@setup scene_model_switching -using PlantSimEngine, PlantMeteo, Dates, DataFrames -using PlantSimEngine.Examples +Suppose daily carbon gain increases with intercepted light. We want to compare +a linear response with a saturating response, then add a soil-water limitation. +All three models answer the same scientific question, but the last needs an +extra input. -meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); - duration=Dates.Day, -) -``` - -One main objective of PlantSimEngine is to compare and switch model -implementations for a process without changing the engine or unrelated model -kernels. Process identity and substitutability are nevertheless different -claims: - -1. **Same process:** two models answer the same scientific question. -2. **Scenario-compatible replacement:** the new model supplies every value - required by the current consumers and its own inputs can be bound. -3. **Drop-in replacement:** process, status and environment ports, scientific - contracts, dependencies, and relevant traits are compatible without - changing scenario wiring. - -Only the third level is suitable for an `Override`, whose applications share -one logical interface. Models may belong to the same process while using -different inputs or producing additional outputs; this is useful scientific -variation, not an error. - -At the model-application layer, replace the model inside a `ModelSpec`, keep -the same `ModelSpec(...; on=...)` selector, then revalidate every binding and -consumer affected by the changed interface. +This example uses teaching models with arbitrary coefficients. They demonstrate +replacement and input checks; their outputs are not predictions for a crop. -## A first simulation - -This model computes degree-days, LAI, absorbed PAR, and growth on one model -object: +## Load one family of alternatives ```@example scene_model_switching -function plant_model_with_growth(growth_model; growth_name=:growth) - CompositeModel( - Object(:scene; scale=:Scene, kind=:scene); - applications=( - ModelSpec(ToyDegreeDaysCumulModel(); name=:degree_days, on=One(scale=:Scene), every=Day(1)), - - ModelSpec(ToyLAIModel(); name=:lai, on=One(scale=:Scene), every=Day(1)), - - ModelSpec(Beer(0.5); name=:light_interception, on=One(scale=:Scene), every=Day(1)), +using Dates, Test, PlantSimEngine - ModelSpec(growth_model; name=growth_name, on=One(scale=:Scene), every=Day(1)), - ), - environment=meteo_day, - ) -end +include(joinpath( + pkgdir(PlantSimEngine), "skills", "plantsimengine", + "assets", "alternative-model.jl", +)) +using .AlternativeModelExample -rue_scene = plant_model_with_growth(ToyRUEGrowthModel(0.2)) -rue_sim = run!(rue_scene; steps=10) -rue_status = final_state(rue_sim) -(growth_model=:ToyRUEGrowthModel, biomass=rue_status.biomass) +linear = LinearCarbonGain(0.2) +saturating = SaturatingCarbonGain(10.0, 5.0) +water_limited = WaterLimitedCarbonGain(0.2) ``` -The compiler infers the same-object bindings from the model declarations. The -growth model reads `aPPFD`, which is produced by the light interception model: +| Model | Equation | Required inputs | +|---|---|---| +| Linear | efficiency × absorbed PAR | Absorbed PAR | +| Saturating | maximum × absorbed PAR / (half-saturation + absorbed PAR) | Absorbed PAR | +| Water-limited | efficiency × absorbed PAR × bounded soil-water fraction | Absorbed PAR and soil-water fraction | -```@example scene_model_switching -select( - DataFrame(Diagnostics.explain_bindings(rue_scene)), - :application_id, - :input, - :source_application_ids, - :origin, - :carrier_kind, -) -``` +Absorbed PAR is a daily total in mol photons per plant; carbon gain is a daily +total in g carbon per plant. The soil-water fraction is dimensionless. The +models record these units and meanings in `VariableContract` declarations. -## Switching the growth model +## Check before changing a scenario -`ToyAssimGrowthModel` implements the same `:growth` process and reads the same -`aPPFD` input, but computes additional outputs such as carbon assimilation and -respiration. It is compatible with this small scenario because no downstream -model requires an output that disappeared. Its larger output interface means -that same process alone did not prove a strict drop-in replacement: +Compare the models with their chosen parameters: ```@example scene_model_switching -assim_scene = plant_model_with_growth(ToyAssimGrowthModel()) -assim_sim = run!(assim_scene; steps=10) -assim_status = final_state(assim_sim) +compatible = Authoring.compare_models(linear, saturating) +needs_water = Authoring.compare_models(linear, water_limited) + +@test compatible.override_compatible +@test needs_water.requires_binding_changes ( - growth_model=:ToyAssimGrowthModel, - carbon_assimilation=assim_status.carbon_assimilation, - Rm=assim_status.Rm, - biomass=assim_status.biomass, + saturating_can_replace_directly=compatible.override_compatible, + water_limited_needs_new_inputs=needs_water.requires_binding_changes, ) ``` -The dependency graph and execution plan are rebuilt from the new application -set: +The linear and saturating models can replace each other directly: they read +and write the same kinds of values and have compatible settings. The +water-limited model answers the same question, but it also needs `ftsw`, the +fraction of transpirable soil water. -```@example scene_model_switching -select( - DataFrame(Diagnostics.explain_execution_plan(assim_sim)), - :application_id, - :object_ids, - :batch_size, - :inner_loop_dispatch, -) -``` +Three distinctions matter: -## Check before replacing +- **Same process:** the models answer the same scientific question. +- **Usable in this scenario:** the new model can get all its inputs and + provide the results needed by the models connected to it. +- **Direct override:** you can replace the model without changing its + connections or other settings. PlantSimEngine checks the process, variables + and their physical meaning, calls to other models, and timing requirements. -Use the public authoring report on the concrete instances: +Use `Override` only for the third case. For broader changes, replace the +model in a `ModelSpec` and update the affected inputs or other configuration. -```@example scene_model_switching -alternative_asset = joinpath( - pkgdir(PlantSimEngine), - "skills", - "plantsimengine", - "assets", - "alternative-model.jl", -) -include(alternative_asset) -using .AlternativeModelExample +## Compare the two light responses -drop_in = Authoring.compare_models( - LinearCarbonGain(0.2), - SaturatingCarbonGain(10.0, 5.0), -) -needs_binding = Authoring.compare_models( - LinearCarbonGain(0.2), - WaterLimitedCarbonGain(0.2), -) -( - drop_in=( - same_process=drop_in.same_process, - override_compatible=drop_in.override_compatible, - requires_reconfiguration=drop_in.requires_reconfiguration, - compatibility=drop_in.compatibility, - ), - water_limited=( - same_process=needs_binding.same_process, - override_compatible=needs_binding.override_compatible, - requires_binding_changes=needs_binding.requires_binding_changes, - requires_reconfiguration=needs_binding.requires_reconfiguration, - compatibility=needs_binding.compatibility, - ), -) -``` +Keep the plants, input data, and timing identical: + +```@example scene_model_switching +function carbon_scenario(gain_model; values=(absorbed_par=10.0,)) + CompositeModel( + Object(:plant; scale=:Plant, status=Status(; values...)); + applications=( + ModelSpec(gain_model; name=:carbon_gain, on=One(scale=:Plant)), + ), + environment=(duration=Day(1),), + ) +end -`requires_binding_changes` is specific to ports, contracts, dependencies, -output policies, or model-level environment hints. `requires_reconfiguration` -is broader: it is true for any interface difference that prevents a direct -override, including a schedule-only trait change. +linear_scene = carbon_scenario(linear) +saturating_scene = carbon_scenario(saturating) -The report compares: +linear_gain = final_state(run!(linear_scene)).carbon_gain +saturating_gain = final_state(run!(saturating_scene)).carbon_gain +@test linear_gain == 2.0 +@test saturating_gain ≈ 100 / 15 +(linear=linear_gain, saturating=saturating_gain) +``` -- `process(model)`; -- required and defaulted status inputs, including declared types; -- local `outputs_` schemas, including initial values; -- environment inputs and outputs; -- complete `VariableContract`s; -- model-authored `Input`, `Call`, and `Initializer` dependencies; -- cadence and temporal output policies. +Only the selected hypothesis changed. At 10 mol of absorbed photons the +linear equation produces 2 g carbon and the saturating equation about +6.67 g carbon. These different outcomes reflect the chosen teaching +coefficients. Models that can replace each other do not have to give the +same result: comparing those results is the purpose of the experiment. -A variable with the same name but a different unit, basis, temporal meaning, -aggregation, or extent is incompatible. Add an explicit adapter rather than -weakening or omitting the contract. +## Supply the additional water input -After replacement, compile the candidate scenario and inspect: +For a controlled comparison, supply a soil-water fraction of 0.5 alongside +the same light input: ```@example scene_model_switching -candidate_validation = Authoring.validate_scenario(assim_scene) -( - scenario_valid=candidate_validation.valid, - initialization=Diagnostics.explain_initialization(assim_scene), - bindings=Diagnostics.explain_bindings(assim_scene), - schedule=Diagnostics.explain_schedule(assim_scene), +water_scene = carbon_scenario( + water_limited; + values=(absorbed_par=10.0, ftsw=0.5), ) -``` +validation = Authoring.validate_scenario(water_scene) +@test validation.valid -The compiler diagnostics prove that this concrete scenario can initialize and -route the replacement. They do not prove that two equations are scientifically -equivalent or valid over the same domain; that remains model documentation and -validation evidence. Distributed `outputs_to` destinations belong to the -`ModelSpec`, not `ModelInterface`, so revalidate them at this scenario level. +water_gain = final_state(run!(water_scene)).carbon_gain +@test water_gain == 1.0 +(linear=linear_gain, water_limited=water_gain) +``` -Use `ObjectInstance(...; overrides=...)` only for a model that satisfies the -logical application's exact replacement contract. Otherwise create or replace -a complete `ModelSpec` and update the affected bindings explicitly. +Here we supplied the soil-water fraction ourselves. To let it change during +a simulation, read it from a soil model or dataset using [Coupling models](@ref). Inspect +`Diagnostics.explain_initialization(water_scene)` to see how each required +input was supplied, then `Diagnostics.explain_bindings(water_scene)` for +connections to other models. + +## Keep physical meaning and scientific validation visible + +Two variables with the same name may use different units or describe +different quantities. Check whether each value is per plant or per unit +area, and whether it is a rate, a mean, or a total. If a conversion is needed, +write it as a small model; see [explicit adapters](../guides/coupling.md). + +`Authoring.compare_models` reports differences in declarations. +`Authoring.validate_scenario` checks whether the models can work together in +your setup. Neither proves that an equation or its parameters are valid for +your study. Also compare assumptions, the conditions in which the models +have been tested, reference data, and simulation results. + +For detailed reports, inspect `requires_binding_changes` for connection +changes and `requires_reconfiguration` for all differences that prevent a +direct override, including changes to how often a model runs. The [Public API](@ref) describes +the complete report. diff --git a/docs/src/step_by_step/quick_and_dirty_examples.md b/docs/src/step_by_step/quick_and_dirty_examples.md deleted file mode 100644 index be48327f0..000000000 --- a/docs/src/step_by_step/quick_and_dirty_examples.md +++ /dev/null @@ -1,121 +0,0 @@ -# Quick Examples - -This page is for copy-paste experimentation with the native composite-model/object API. -If you want a slower explanation of the same ideas, see -[Detailed Walkthrough Of A Simple Simulation](@ref detailed-walkthrough-of-a-simple-simulation). - -The examples use one model object, but the same pattern scales to plants, -organs, soil objects, and microclimate grids by adding more `Object`s and -selecting them with `ModelSpec(...; on=...)` and `ModelSpec(...; inputs=...)`. - -```@setup quick_model_examples -using PlantSimEngine, PlantMeteo, Dates, DataFrames -using PlantSimEngine.Examples - -meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); - duration=Dates.Day, -) -``` - -```@contents -Pages = ["quick_and_dirty_examples.md"] -Depth = 2 -``` - -## One Light Interception Model - -```@example quick_model_examples -model = CompositeModel( - Beer(0.5); - status=(LAI=2.0,), - environment=meteo_day, -) - -sim = run!(model; steps=3, outputs=:all) -first(collect_outputs(sim), 3) -``` - -## LAI And Light Interception - -Here, `ToyDegreeDaysCumulModel` computes cumulative thermal time, `ToyLAIModel` -computes `LAI`, and `Beer` consumes `LAI`. The compiler infers the same-object -value bindings from model inputs and outputs. - -```@example quick_model_examples -lai_scene = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.5); - environment=meteo_day, -) - -lai_sim = run!(lai_scene; steps=5, outputs=:all) -first(collect_outputs(lai_sim), 8) -``` - -Inspect the inferred coupling: - -```@example quick_model_examples -select( - DataFrame(Diagnostics.explain_bindings(lai_scene)), - :application_id, - :input, - :source_application_ids, - :carrier_kind, -) -``` - -## Add Biomass Growth - -`ToyRUEGrowthModel` consumes absorbed light and accumulates biomass. No extra -input binding is needed because `Beer` is the unique producer of `aPPFD` on the -same object. - -```@example quick_model_examples -growth_scene = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.5), - ToyRUEGrowthModel(0.2); - environment=meteo_day, -) - -growth_sim = run!(growth_scene; steps=5) -growth_status = final_state(growth_sim) -(LAI=growth_status.LAI, aPPFD=growth_status.aPPFD, biomass=growth_status.biomass) -``` - -## Keep Only One Requested Output - -For larger simulations, request only the streams you want to keep: - -```@example quick_model_examples -request = OutputRequest( - :Scene, - :biomass; - name=:biomass_daily, - application=:growth, - policy=HoldLast(), - clock=Day(1), -) - -requested_sim = run!( - growth_scene; - steps=5, - outputs=request, -) - -first(collect_outputs(requested_sim, :biomass_daily), 5) -``` - -## PlantBiophysics - -The same composite-model/object API can host models from companion packages such as -PlantBiophysics. A typical PlantBiophysics energy-balance setup uses -`ModelSpec(...; calls=...)` so an iterative parent model can manually run photosynthesis and -stomatal-conductance models, then call `run_call!(target; publish=true)` once -for the accepted solution. - -See [MAESPA-style model example handoff](../dev/maespa_model_handoff.md) for -the current multi-plant energy-balance acceptance example. diff --git a/docs/src/step_by_step/simple_model_coupling.md b/docs/src/step_by_step/simple_model_coupling.md deleted file mode 100644 index 56882d6b2..000000000 --- a/docs/src/step_by_step/simple_model_coupling.md +++ /dev/null @@ -1,97 +0,0 @@ -# Standard model coupling - -```@setup scene_coupling -using PlantSimEngine -using PlantSimEngine.Examples -using PlantMeteo, Dates, DataFrames - -meteo_day = read_weather( - joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"); - duration=Dates.Day, -) -``` - -This page shows the standard coupling case: one model computes a variable that -another model reads. In the composite-model/object API, the user describes model -applications on objects, and the compiler wires the value dependencies. - -## Setting up your environment - -Make sure you have a working Julia environment with PlantSimEngine and the -recommended companion packages. Details are provided on the -[Installing PlantSimEngine](../prerequisites/installing_plantsimengine.md) -page. - -## One object and one model - -A model contains objects. A model application says where a model runs. Here a -light interception model runs on the model object, uses the environment's -daily cadence, and reads `LAI` from that object's status: - -```@example scene_coupling -light_scene = CompositeModel( - Beer(0.5); - status=(LAI=2.0,), - environment=meteo_day, -) - -light_sim = run!(light_scene; steps=3, outputs=:all) -first(collect_outputs(light_sim; sink=DataFrame), 3) -``` - -## Coupling two models - -Suppose we want `ToyLAIModel` to compute `LAI` for `Beer`. Both models can run -on the same object. `ToyLAIModel` produces `LAI`, and `Beer` declares `LAI` as -an input, so the model compiler infers the binding: - -```@example scene_coupling -coupled_scene = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.5); - environment=meteo_day, -) - -select( - DataFrame(Diagnostics.explain_bindings(coupled_scene)), - :application_id, - :input, - :source_application_ids, - :origin, - :carrier_kind, - :copy_semantics, -) -``` - -The `:inferred_same_object` rows are soft dependencies: the consumer input is -provided by another model output. Same-rate local links use live references, so -the timestep loop does not copy values between models. - -Run the coupled model: - -```@example scene_coupling -coupled_sim = run!(coupled_scene; steps=5) -coupled_status = final_state(coupled_sim) -(TT_cu=coupled_status.TT_cu, LAI=coupled_status.LAI, aPPFD=coupled_status.aPPFD) -``` - -## Adding another model - -Additional models are just additional applications. `ToyRUEGrowthModel` -consumes `aPPFD`, which is produced by `Beer`, so the compiler infers another -same-object binding: - -```@example scene_coupling -growth_scene = CompositeModel( - ToyDegreeDaysCumulModel(), - ToyLAIModel(), - Beer(0.5), - ToyRUEGrowthModel(0.2); - environment=meteo_day, -) - -growth_sim = run!(growth_scene; steps=5) -growth_status = final_state(growth_sim) -(LAI=growth_status.LAI, aPPFD=growth_status.aPPFD, biomass=growth_status.biomass) -``` diff --git a/docs/src/troubleshooting/common_errors.md b/docs/src/troubleshooting/common_errors.md index a8df3b70d..6c75af856 100644 --- a/docs/src/troubleshooting/common_errors.md +++ b/docs/src/troubleshooting/common_errors.md @@ -1,13 +1,59 @@ # Common Errors -A missing-input error means a `Required(T)` input has neither supplied state -nor a producer binding; start with `Diagnostics.explain_initialization`. A -plain-input-declaration error means `inputs_` must replace each literal with -`Required(T)` or `Default(value)`. A cardinality error lists selector matches; -correct the scope or choose the intended `OptionalOne`/`Many` multiplicity. An -ambiguity requires an explicit application/object selector. - -Duplicate-writer errors require either distinct output routing or an explicit -`Updates` order. Cadence errors require fixed `Dates` periods compatible with -the environment base step. Extend package functions as -`PlantSimEngine.run!(...)`, including the package qualification. +Start with the model application, object, and variable named in the error. +An application is a model configured to run on selected objects. These names +tell you where to look: for example, a light calculation on a particular +canopy may be missing LAI. PlantSimEngine catches many such problems before +running any equation. + +| Symptom | What it means | First action | +|:--|:--|:--| +| A required input is missing | You have not supplied a starting value or a model that calculates it | Supply the value or connect a model that provides it | +| A selector finds too few or too many objects | For example, `One` expects one match but finds two | Check the object labels and where the selector searches | +| More than one source matches | Several models could supply the input | Name the intended `application` and, if needed, `var` | +| Several models set the same variable | PlantSimEngine cannot decide which value to keep | Choose one model, or use `Updates` if one model is meant to change another's result | +| Variable contracts differ | The connected variables declare different units or physical meanings | Check what each equation expects; add a conversion model where appropriate | +| A cadence is rejected | The chosen interval does not fit the base step or is not supported by the model | [Choose compatible time steps](../guides/time/advanced_time_environment.md) | +| There is a dependency cycle | Two or more models each wait for a result from the others | Decide whether one input should come from the previous step or the equations must be solved together | + +## Example: the light model needs LAI + +`Beer` needs the canopy's LAI to calculate absorbed light. If no other model +calculates LAI, supply its value yourself: + +```@example missing_lai +using PlantSimEngine +using PlantSimEngine.Examples + +model = CompositeModel(Beer(0.6); + status=(LAI=2.0,), environment=(Ri_PAR_f=100.0,)) +simulation = run!(model) +final_state(simulation).aPPFD +``` + +Alternatively, add a model that calculates LAI and supply that model's inputs. +An arbitrary zero may remove a missing-input error while changing the +scientific question. Use a value with a clear meaning. + +## Check the objects a selector actually sees + +Inspect `Diagnostics.explain_objects(model)` to see labels and parent links. +For a plant application, `Many(scale=:Leaf, within=Subtree())` searches that +plant and its descendants. For a leaf application, the same selector starts +at that leaf. Use `SelfPlant()` when the search should cover its whole plant. + +Choose `Many` when the receiving model accepts a collection. Choosing it only +to silence an error can pass a vector to an equation that expects one value. + +## Errors while writing a model + +Declare each status input with `Required(T)` if it must be supplied, or +`Default(value)` if the model provides a fallback value. For example, use +`inputs_(::MyModel) = (LAI=Required(Real),)` with the function qualified as +`PlantSimEngine.inputs_`. Writing a number directly in `inputs_` does not +declare a required input. Define the equation as `PlantSimEngine.run!(...)` +so that Julia adds your model's method to the package function. + +For the complete sequence, see [Write and test a first model](../journeys/modelers/basic_model.md). +For further investigation, see [Inspect a simulation](runtime_contracts.md) +and [Dependency cycles](dependency_cycles.md). diff --git a/docs/src/troubleshooting/dependency_cycles.md b/docs/src/troubleshooting/dependency_cycles.md index 312321816..db1979aa9 100644 --- a/docs/src/troubleshooting/dependency_cycles.md +++ b/docs/src/troubleshooting/dependency_cycles.md @@ -1,17 +1,17 @@ # Diagnosing Dependency Cycles -A same-step value cycle is rejected because no valid execution order exists. -Read the reported application, object, and variable edges. If the science uses -yesterday's value, put `PreviousTimeStep(:variable)` on that input. If the -science requires convergence in the current step, make one parent application -own child trials with `calls`. Otherwise reformulate the coupled equations. +A **dependency cycle** occurs when two or more models each need a new result +from the others before they can run. For example, a leaf model needs water +from a root model, but the root model needs carbon from the leaf model. +Neither can go first, so PlantSimEngine reports the problem before running +the equations. The error names the applications, objects, and variables +involved. -Application declaration order is not a cycle-resolution mechanism. - -For example, if application `:leaf` reads same-step `water` from `:root` while -`:root` reads same-step `carbon` from `:leaf`, compilation fails before either -kernel runs. If root water scientifically affects tomorrow's leaf carbon, -change only that edge: +Choose the solution that matches your equations. If the leaf should use the +root's water from the previous step, mark that input with +`PreviousTimeStep(:water)`. For a daily simulation, this means yesterday's +water. The leaf can then calculate today's carbon before the root calculates +today's water: ```julia ModelSpec( @@ -23,7 +23,15 @@ ModelSpec( ) ``` -The receiving object's initial `water` value is used until the first accepted -historical sample exists. If both values must converge within the same step, -do not add a lag: make a parent model own `calls` to the two trial models, -iterate with `publish=false`, and publish each accepted state once. +At the start, the leaf's initial `water` value is used until a result from a +previous step is available. + +If the two values must instead be solved together in the current step, use +a controller model that calls both models repeatedly. Try values with +`publish=false` and record each accepted result once with `publish=true`. +The controller must decide when the result is close enough and what to do if +the calculation does not converge. See +[Control Advanced Execution](../journeys/users/advanced_execution.md). + +You may also need to rewrite the equations. Simply changing the order of +the `ModelSpec` declarations does not resolve a cycle. diff --git a/docs/src/troubleshooting/runtime_contracts.md b/docs/src/troubleshooting/runtime_contracts.md index 7e5fda2bd..59b0c41c2 100644 --- a/docs/src/troubleshooting/runtime_contracts.md +++ b/docs/src/troubleshooting/runtime_contracts.md @@ -1,12 +1,60 @@ -# Runtime Contracts And Diagnostics - -Use `Diagnostics.explain_initialization`, `Diagnostics.explain_bindings`, `Diagnostics.explain_calls`, -`Diagnostics.explain_schedule`, `Diagnostics.explain_environment_bindings`, and -`Diagnostics.explain_output_retention` as the supported inspection surface. Do not inspect -compiled internal fields. - -Targets, carriers, calls, writer checks, and schedules refresh after the -application that made a structural change. New objects join applications still -remaining in that timestep; they do not retroactively run earlier applications. -Movement and geometry changes invalidate affected spatial environment bindings. -Accepted streams are append-only. +# Inspect A Simulation + +When a result is unexpected, first check what ran, where it ran, and which +values it read. The `Diagnostics` functions return information you can display +as a table. Use them to check how the simulation is configured. Check the +scientific equations and parameter values separately. + +| Question | Diagnostic | +|:--|:--| +| Which objects and labels exist? | `Diagnostics.explain_objects(model)` | +| Which models run on them? | `Diagnostics.explain_applications(model)` | +| Where does each input come from? | `Diagnostics.explain_bindings(model)` | +| Which initial values are supplied or missing? | `Diagnostics.explain_initialization(model)` | +| When does each application run? | `Diagnostics.explain_schedule(model)` | +| Which weather or spatial source is sampled? | `Diagnostics.explain_environment_bindings(model)` | +| Which models are called by a controller? | `Diagnostics.explain_calls(model)` | +| Why were earlier values of an output kept? | `Diagnostics.explain_output_retention(simulation)` | + +## Inspect a small working example + +Here leaf surface depends on supplied carbon biomass. Check its input source +before running a larger structure: + +```@example inspect_simulation +using PlantSimEngine, DataFrames +using PlantSimEngine.Examples + +model = CompositeModel(ToyLeafSurfaceModel(0.02); + status=(carbon_biomass=50.0,), id=:leaf, scale=:Leaf) +DataFrame([ + (variable=row.variable, role=row.role, disposition=row.disposition) + for row in Diagnostics.explain_initialization(model) +]) +``` + +```@example inspect_simulation +simulation = run!(model; outputs=:all) +@assert final_state(simulation).surface ≈ 1.0 # hide +DataFrame(Diagnostics.explain_output_retention(simulation)) +``` + +If model construction fails, use the error's object and application names to +correct the configuration first. A diagnostic cannot inspect a model that was +never constructed. + +## After growth or movement + +After adding or removing organs, PlantSimEngine updates which objects each +model runs on and where its inputs come from. This happens **after the +application that changed the structure finishes**. New organs may run models +scheduled later in the same time step. Models that already ran are not +repeated. If you change the structure between steps, these connections are +updated before the next step. + +If you move an organ or change its geometry, PlantSimEngine needs to find its +new location in the spatial environment. Use functions such as `move_object!` +and `update_geometry!` so it knows to update this connection. Removing an +organ stops its future calculations and keeps results that were already +saved. See [Modify plant structure](../journeys/users/structure_changes.md) +for an example that checks the affected objects and their carbon balance. diff --git a/docs/src/troubleshooting_and_testing/downstream_tests.md b/docs/src/troubleshooting_and_testing/downstream_tests.md deleted file mode 100644 index f78ec40ab..000000000 --- a/docs/src/troubleshooting_and_testing/downstream_tests.md +++ /dev/null @@ -1,9 +0,0 @@ -# Automated tests : downstream dependency checking - -PlantSimEngine is [open sourced on Github](https://github.com/VirtualPlantLab/PlantSimEngine.jl), and so are its other companion packages, [PlantGeom.jl](https://github.com/VEZY/PlantGeom.jl), [PlantMeteo.jl](https://github.com/VEZY/PlantMeteo.jl), [PlantBioPhysics.jl](https://github.com/VEZY/PlantBioPhysics.jl), [MultiScaleTreeGraph.jl](https://github.com/VEZY/MultiScaleTreeGraph.jl), and [XPalm](https://github.com/PalmStudio/XPalm.jl). - -One handy CI (Continuous Integration) feature implemented for these packages is automated integration and downstream testing: after changes to a package, its known downstream dependencies are tested to ensure no breaking changes were introduced. - -For instance, PlantBioPhysics uses PlantSimEngine, so the integration workflow checks that PlantBioPhysics's tests do not break unexpectedly after changes to PlantSimEngine. The repository also keeps a separate benchmark workflow and benchmark scripts in the `benchmark/` directory for performance tracking. - -If you maintain a package that depends on PlantSimEngine, you can propose adding it to the downstream integration workflow through a pull request. diff --git a/docs/src/tutorials/growing_plant/part1_growth.md b/docs/src/tutorials/growing_plant/part1_growth.md index aa692f125..b9ed2d74b 100644 --- a/docs/src/tutorials/growing_plant/part1_growth.md +++ b/docs/src/tutorials/growing_plant/part1_growth.md @@ -1,35 +1,51 @@ # Growing A Plant CompositeModel -Begin with a plant object and leaf objects whose carbon production is gathered -by a plant application through `Many(scale=:Leaf, within=Subtree())`. A growth -model calls `register_object!` after its carbon or thermal threshold is met. - -Structural changes refresh compiled targets after the application that made -the change. A new leaf may run applications that remain later in the same -timestep. It runs an application that already completed only when its creator -declares that application as an `Initializer` and explicitly initializes the -newborn object. -When callers mutate structure between `step!` calls, refresh occurs before the -next step. - -Build the initial registry explicitly so ownership remains visible: - -```julia -model = CompositeModel( - Object(:plant; scale=:Plant, status=Status(carbon=0.0)), - Object(:leaf_1; scale=:Leaf, parent=:plant, status=Status(area=1.0)); - applications=(leaf_application, plant_balance, growth_application), - environment=weather, -) -``` - -The plant balance gathers leaf production with -`Many(scale=:Leaf, within=Subtree())`. The growth kernel obtains the live model -with `runtime_model(context)`, checks its carbon and thermal thresholds, creates -a fully initialized `Object`, and calls `register_object!`. It should deduct -the construction cost exactly once before registration. - -After each step, assert both biology and structure: remaining plant carbon, -the number of leaf objects, each new leaf's parent, and accepted historical -outputs. `Diagnostics.explain_applications` should show that the new leaf is absent -during its creation step and present after the between-step refresh. +Start with [Modify Plant Structure](@ref) for a runnable example of adding and +removing leaves, or changing which object they belong to. This page explains +how to connect those operations to a growth model and a carbon budget. + +## Connect organ creation to a resource budget + +Store the plant's carbon reserves on the plant object and each leaf's carbon +production on that leaf. `Many(scale=:Leaf, within=Subtree())` lets the plant +collect production from its own leaves. Before adding production to reserves, +check what it represents: a rate, an amount produced during one interval, or +a total accumulated since the start of the simulation. For an accumulated +total, add only the increase since the last update. Adding the full total at +every step would count the same carbon repeatedly. + +The growth model's `run!` function then follows this sequence: + +1. Read the available carbon and check whether the plant is ready to grow. +2. If so, create the new organ's status with initial area, mass, and any + other values its models need. +3. Subtract the construction cost once. Add the organ to the simulation with + a unique identity and the correct parent object. +4. Check the carbon balance: the remaining reserves, the carbon in the new + organ, and any carbon spent on respiration must add up to the amount + available before growth. + +Use `register_object!` if your model has already created an `Object` with all +its initial values. If you represent the plant with a MultiScaleTreeGraph +(MTG), use `add_organ!` to create its MTG node, status, and simulation object +together. Your growth model must still decide when an organ appears, what it +costs, and how carbon is converted to dry matter. + +## Know when a newborn can run + +When a model adds, removes, or reparents an organ, PlantSimEngine updates +which objects each model runs on and where their inputs come from +**after that application finishes**. A new leaf can run models scheduled +later in the same timestep. Models that already ran are not repeated. +If the new leaf needs one of those earlier calculations immediately, the +model creating it must declare an `Initializer` and call `run_initializer!`. + +If you change the plant structure between `step!` calls, these connections +are updated before the next step. Neither case automatically undoes changes +to the plant's values if something goes wrong. + +After creating an organ, check its parent, initial values, first saved result, +and the plant's carbon budget. Use the working example in +[Modify Plant Structure](@ref) to inspect the objects, then continue with +[Adding Roots And Water](@ref) for a small resource-accounting example and +[Debugging Growth And Resource Ordering](@ref) when execution order is unclear. diff --git a/docs/src/tutorials/growing_plant/part2_roots_water.md b/docs/src/tutorials/growing_plant/part2_roots_water.md index c15bd5bd5..3669d1f81 100644 --- a/docs/src/tutorials/growing_plant/part2_roots_water.md +++ b/docs/src/tutorials/growing_plant/part2_roots_water.md @@ -1,38 +1,89 @@ # Adding Roots And Water -Add root objects and gather absorption through a plant-local `Many` selector. -Keep shared carbon and water stocks on the plant, while leaf and root state -remains object-local. Environment precipitation is an environment input; root -creation is an explicit `register_object!` operation with initialized status. - -When several plants share one soil object, select it explicitly with a -model-wide `One` selector rather than relying on traversal order. - -Keep stocks at the scale that owns conservation. A root model may publish an -absorption rate per root, while the plant model integrates all root rates and -updates one plant water stock. The example below assumes uptake per second -and weights rates by their durations in seconds. A soil model owns soil water; plants read it -through an explicit model-wide selector. This avoids copying one stock into -every organ and makes duplicate writers visible. - -```julia -ModelSpec( - PlantWaterModel(); - inputs=( - :root_uptake => Many( - scale=:Root, within=Subtree(), application=:root_absorption, - var=:uptake, policy=Integrate((values, durations_seconds) -> sum(values .* durations_seconds)), window=Day(1), - ), - :soil_water => One( - scale=:Soil, within=SceneScope(), application=:soil_water, - var=:water, +This example adds the water taken up by two roots to one plant water stock. +It shows how to count each amount once when roots update hourly and the plant +updates daily. The uptake rates are constant teaching values, not predictions +from a root-uptake equation. We assume that the water supply can provide +these **already accepted** rates. The example does not calculate soil +competition, transpiration, or a complete plant water balance. + +## Integrate each accepted interval once + +Rates are in g water s⁻¹ per root. The plant adds a day's uptake in g water +once per day. Both `on=One(scale=:Plant)` and `every=Day(1)` are explicit: +updating this stock hourly with a rolling one-day total would count overlapping +intervals repeatedly. + +```@example root-water +using Dates, PlantSimEngine + +PlantSimEngine.@process "docs_root_uptake" verbose=false +PlantSimEngine.@process "docs_plant_water" verbose=false +struct DocsRootUptake <: AbstractDocs_Root_UptakeModel end +struct DocsPlantWater <: AbstractDocs_Plant_WaterModel end + +PlantSimEngine.inputs_(::DocsRootUptake) = (accepted_rate=Required(Real),) +PlantSimEngine.outputs_(::DocsRootUptake) = (uptake=0.0,) +function PlantSimEngine.run!(::DocsRootUptake, status, environment, constants, context) + status.uptake = status.accepted_rate + return nothing +end + +PlantSimEngine.inputs_(::DocsPlantWater) = (root_uptake=Required(AbstractVector{<:Real}),) +PlantSimEngine.outputs_(::DocsPlantWater) = (stored_water=0.0,) +function PlantSimEngine.run!(::DocsPlantWater, status, environment, constants, context) + status.stored_water += sum(status.root_uptake) + return nothing +end + +model = CompositeModel( + Object(:plant; scale=:Plant), + Object(:root_1; scale=:Root, parent=:plant, status=Status(accepted_rate=1e-4)), + Object(:root_2; scale=:Root, parent=:plant, status=Status(accepted_rate=2e-4)); + applications=( + ModelSpec(DocsRootUptake(); name=:uptake, on=Many(scale=:Root), every=Hour(1)), + ModelSpec( + DocsPlantWater(); name=:water, on=One(scale=:Plant), every=Day(1), + inputs=(root_uptake=Many( + scale=:Root, within=Subtree(), application=:uptake, var=:uptake, + policy=Integrate((values, seconds) -> sum(values .* seconds)), + window=Day(1), + ),), ), ), + environment=(duration=Hour(1),), ) +simulation = run!(model; steps=49, outputs=:all) +water_history = [ + (base_step=row.time, stored_water_g=row.value) + for row in collect_outputs(simulation; sink=nothing) + if row.object_id == :plant && row.variable == :stored_water +] +@assert isapprox(final_state(simulation, :plant).stored_water, 49 * (1e-4 + 2e-4) * 3600) +water_history ``` -Precipitation, temperature, and radiation remain environment variables, not -ordinary object outputs. Use `Environment(sources=...)` when provider column -names differ from model-facing names. When growth creates a root, initialize -all required root status values before `register_object!`; verify the next -timestep's carrier with `Diagnostics.input_value` or `Diagnostics.explain_bindings`. +The first daily calculation has only one hourly value available, so it adds +`1.08` g. Each following daily calculation adds 24 new hourly amounts, or +`25.92` g. The stock is therefore `1.08`, `27.0`, and `52.92` g at base steps +1, 25, and 49. All 49 supplied hourly amounts are counted once. A model set +to run daily still runs at the start, before a full day of values is available. + +These totals describe uptake added to storage, not tissue hydration or growth. + +## Share a limited soil water supply + +When several plants share a limited soil water supply, use one model to +manage that stock. This model must collect all root demands, decide how much +water each receives, subtract the total withdrawal once, and return the +accepted rates or amounts to the plants. Simply letting each root read the +same soil stock does not prevent them from taking too much water together. +`Updates` can specify the order in which models change a value, but your +equations must decide how to share the water. + +Supply rainfall through the environment and state its units before converting +it to an amount of soil water. Add each loss and exchange when extending +the plant balance. When growth adds a root, provide its initial values and +add it with `register_object!` or, for an MTG, `add_organ!`. The plant's `Many` +selection then includes that root after the creating application finishes. +See [Growing A Plant CompositeModel](@ref). diff --git a/docs/src/tutorials/growing_plant/part3_debugging.md b/docs/src/tutorials/growing_plant/part3_debugging.md index eff0e2282..8c9b488e9 100644 --- a/docs/src/tutorials/growing_plant/part3_debugging.md +++ b/docs/src/tutorials/growing_plant/part3_debugging.md @@ -1,33 +1,58 @@ # Debugging Growth And Resource Ordering -If an organ appears to spend resources before it exists, inspect activation -timing and the compiled schedule. If two models intentionally update one stock, -declare `Updates(:stock; after=:producer)`. If a parent must test several child -states before accepting one, use `calls` and publish only the accepted call. - -For cycles, choose a scientific meaning: lag one edge with -`PreviousTimeStep`, put convergence under a parent-owned hard call, or -reformulate the equations. Do not resolve a cycle by incidental application -ordering. - -Use this debugging order: - -1. `Diagnostics.explain_initialization(model)` for missing state or environment values. -2. `Diagnostics.explain_bindings(model)` for source scope and multiplicity. -3. `Diagnostics.explain_writers(model)` for competing canonical outputs. -4. `Diagnostics.explain_calls(model)` for call-only targets and target cardinality. -5. `Diagnostics.explain_schedule(model)` for cadence and root ordering. -6. `Diagnostics.explain_outputs(simulation)` after execution for publication history. - -A trial call must not mutate accepted output history or scatter mutable -environment outputs. Nested trials inherit the outer publication decision. -Convergence and failure policy belongs to the parent model: it decides the -iteration limit, tolerance, fallback, and whether any state is accepted. - -Structural mutation is also transactional at the timestep boundary. A new -organ is registered immediately in the model registry but does not recursively -run merely because it was created. A creator may explicitly initialize one -newborn object through a declared `Initializer`; otherwise, compilation refreshes -targets, carriers, calls, writer validation, schedules, and requested outputs at -the safe barrier. Geometry-only movement refreshes only affected spatial -bindings where possible. +Use this page when a new organ receives the wrong inputs, spends a resource +twice, or appears in outputs at an unexpected time. Begin with the runnable +[Modify Plant Structure](@ref) example and change one mechanism at a time. + +## Follow one timestep + +First check whether a model created the organ during `run!`, or whether you +added it between `step!` calls. During a step, PlantSimEngine updates the list +of objects and their input connections after the creating application +finishes. The new organ can then run models scheduled later in that step; +models that already ran are not repeated. If you add the organ between steps, +these connections are updated before the next step. + +An `Initializer` lets a model calculate a new organ's initial values without +adding an extra saved result during the step. Adding an organ changes the +object registry immediately. The later update to input connections does not +automatically undo those changes, or changes to other model values, if a +calculation fails. + +## Find the cause of the unexpected result + +| Symptom | First check | What to verify | +|---|---|---| +| A new organ has missing or invalid values | `Diagnostics.explain_initialization(model)` | Every required input has a meaningful initial value. | +| One plant reads values from another plant's leaves | `Diagnostics.explain_bindings(model)` | `Subtree()` or another selector limits the search to the intended plant. | +| Two models change the same stock | `Diagnostics.explain_writers(model)` | Only one model sets the value, or `Updates(:stock; after=:producer)` specifies the intended order. | +| A called model runs unexpectedly | `Diagnostics.explain_calls(model)` | The controller selects the intended models and calls them only for the intended trials and accepted calculations. | +| A day's uptake is added every hour | `Diagnostics.explain_schedule(model)` | The stock is updated only once for each amount of water taken up. | +| A new organ's results start too early or too late | `Diagnostics.explain_outputs(simulation)` and `collect_outputs(simulation)` | The first result matches when the organ was created and which models could still run in that step. | + +For carbon or water, also check the balance directly: initial stock plus +accepted inputs equals final stock plus losses and transfers. PlantSimEngine +can check which models change a stock, but that check does not prove that your +equations conserve the resource. +[Adding Roots And Water](@ref) shows a two-day accounting check. + +## Keep trial and accepted state distinct + +If two models each need the other's result, decide what the equations require. +Use `PreviousTimeStep` if one input should come from the preceding step. If +both must be solved together in the current step, use a controller to repeat +the calculations until the solution is acceptable. You may also need to +rewrite the equations. Changing the order of the `ModelSpec` declarations +does not solve this problem. + +Use `run_call!(context, name; publish=false)` for trials and `publish=true` +only for the accepted result. `publish=false` keeps the trial out of the +output history, but it does not undo changes to status values. The controller +must prepare the values for each new trial and avoid permanently spending +carbon or water on rejected trials. Save environment changes with +`commit_environment!` only after accepting a solution. + +The controller must set the maximum number of trials, how close the solution +must be, and what to do if no acceptable solution is found. The +[MAESPA-Style Synthesis](@ref) shows repeated leaf calculations followed by +an accepted canopy air update. It adds carbon only after accepting a solution. diff --git a/docs/src/working_with_data/fitting.md b/docs/src/working_with_data/fitting.md index 65f058af8..78c2b5417 100644 --- a/docs/src/working_with_data/fitting.md +++ b/docs/src/working_with_data/fitting.md @@ -1,11 +1,13 @@ # Parameter Fitting -`PlantSimEngine.Evaluation.fit` is the shared interface for model-specific -calibration. -Model packages implement a method whose first argument is the model type and -whose second argument is Tables.jl-compatible observations. +Parameter fitting means finding parameter values that make a model agree +with observations. PlantSimEngine provides `Evaluation.fit` as a common +function name; each model package supplies the fitting method for its own +models. Pass the model type first and a table of observations second. +The table can be a DataFrame or another format supported by Tables.jl. -The mathematical core of the Beer fit is: +For the `Beer` model, we can calculate the light-extinction coefficient `k` +from LAI, incoming light, and absorbed light: ```julia J_to_umol = PlantMeteo.Constants().J_to_umol @@ -14,16 +16,16 @@ f_abs = data.aPPFD ./ incident_ppfd k = Statistics.mean(-log1p.(-f_abs) ./ data.LAI) ``` -This snippet shows the inversion only. The implementation in +This snippet only shows how to rearrange Beer's equation to find `k`. The implementation in `examples/Beer.jl` validates every observation and returns `(k=k,)`; do not use the snippet alone as an unchecked fitting method. -The result should be a `NamedTuple` of fitted parameters. +A fitting method returns named parameter values, for example `(k=0.6,)`. -In this Beer example, `Ri_PAR_f` is an incident flux per unit ground area and -`aPPFD` is the flux absorbed by the whole canopy, also per unit ground area. +In this Beer example, `Ri_PAR_f` measures incoming light per unit ground area +and `aPPFD` measures light absorbed by the whole canopy per unit ground area. `LAI` is leaf area per unit ground area. Do not use a PPFD expressed per unit -leaf area in this inversion. The fit rejects empty data, non-finite or +leaf area in this calculation. The fit rejects empty data, non-finite or non-positive `LAI` and incident PAR, and absorbed fractions outside `[0, 1)`. ```@example fitting diff --git a/docs/test/runtests.jl b/docs/test/runtests.jl index 73b4f265c..9ff8d3d65 100644 --- a/docs/test/runtests.jl +++ b/docs/test/runtests.jl @@ -1,42 +1,20 @@ -using Test - -@testset "Progressive journey structure" begin - journey_root = joinpath(@__DIR__, "..", "src", "journeys") - user_pages = sort([ - joinpath(journey_root, "users", file) - for file in readdir(joinpath(journey_root, "users")) - if endswith(file, ".md") - ]) - modeler_pages = sort([ - joinpath(journey_root, "modelers", file) - for file in readdir(joinpath(journey_root, "modelers")) - if endswith(file, ".md") - ]) - - for page in user_pages - source = read(page, String) - @test occursin("New concept", source) - @test occursin("## Page recap", source) - @test occursin("**You added:**", source) - @test occursin("**PlantSimEngine infer", source) - @test occursin("**You keep explicit:**", source) - @test occursin("**New API names:**", source) - @test !occursin("```julia", source) - end - - for page in modeler_pages - source = read(page, String) - @test occursin("**New concept:**", source) - @test occursin("## Model-author recap", source) - @test occursin("**You implemented:**", source) - @test occursin("**PlantSimEngine inferred:**", source) - @test occursin("**The scenario author keeps explicit:**", source) - @test occursin("**New API names:**", source) - @test occursin("tested", lowercase(source)) - end -end +using Test, Markdown +# Documenter executes the @example blocks, their numerical assertions, and +# doctests. Avoid tests that prescribe headings or repeated editorial labels. @testset "PlantSimEngine documentation" begin ENV["PLANTSIMENGINE_DOCS_BUILD_ONLY"] = "true" @test include(joinpath(@__DIR__, "..", "make.jl")) === nothing end + +@testset "Generated Markdown keeps code and table structure" begin + writer = Base.get_extension(Bonito, :BonitoDocumenterExt) + markdown = Markdown.parse("```julia\nx = 1\ny = 2\n```\n\n| Variable | Value |\n| --- | --- |\n| LAI | 2 |") + root = convert(writer.MA.Node, markdown) + context = writer.DCtx(nothing, nothing, nothing, joinpath(@__DIR__, "..", "build")) + rendered = writer.domify(context, root) + html = repr(MIME"text/html"(), Bonito.DOM.div(rendered...)) + @test occursin("
 isfinite(x) && x >= zero(x), (leaf, wood)) ||
+            throw(ArgumentError("Allocation fractions must be finite and nonnegative."))
+        leaf + wood <= one(leaf) ||
+            throw(ArgumentError("Allocation fractions must sum to at most one."))
+        return new{typeof(leaf)}(leaf, wood)
+    end
+end
+
+"""
+    DemandAllocation()
+    DemandAllocation{Float32}()
+
+Allocate available carbon in proportion to leaf and wood demands, up to
+their combined demand. Keep any surplus in reserve. With no demand, keep
+all available carbon in reserve.
+
+This is a second uncalibrated hypothesis for the same `carbon_allocation`
+process as `FixedFractionAllocation`, with the same inputs, outputs, and
+units. The type parameter selects the initial output number type.
+"""
+struct DemandAllocation{T<:Real} <: AbstractCarbon_AllocationModel end
+DemandAllocation() = DemandAllocation{Float64}()
+
+const AllocationModel = Union{FixedFractionAllocation,DemandAllocation}
+
+PlantSimEngine.inputs_(::AllocationModel) = (
+    carbon_offer=Required(Real),
+    leaf_demand=Required(Real),
+    wood_demand=Required(Real),
+)
+
+function PlantSimEngine.outputs_(::Union{FixedFractionAllocation{T},DemandAllocation{T}}) where {T}
+    return (
+        leaf_growth=zero(T),
+        wood_growth=zero(T),
+        reserve_change=zero(T),
+        leaf_carbon=zero(T),
+        wood_carbon=zero(T),
+        reserve_carbon=zero(T),
+    )
+end
+
+PlantSimEngine.environment_inputs_(::AllocationModel) = NamedTuple()
+PlantSimEngine.environment_outputs_(::AllocationModel) = NamedTuple()
+PlantSimEngine.timestep_hint(::AllocationModel) = Day(1)
+
+const DAILY_CARBON = VariableContract(
+    unit=:g_carbon, basis=:plant, temporal=:day,
+    aggregation=:total, extent=:extensive,
+)
+const STORED_CARBON = VariableContract(
+    unit=:g_carbon, basis=:plant, temporal=:instantaneous,
+    aggregation=:state, extent=:extensive,
+)
+
+PlantSimEngine.variable_contracts_(::AllocationModel) = (
+    carbon_offer=DAILY_CARBON,
+    leaf_demand=DAILY_CARBON,
+    wood_demand=DAILY_CARBON,
+    leaf_growth=DAILY_CARBON,
+    wood_growth=DAILY_CARBON,
+    reserve_change=DAILY_CARBON,
+    leaf_carbon=STORED_CARBON,
+    wood_carbon=STORED_CARBON,
+    reserve_carbon=STORED_CARBON,
+)
+
+PlantSimEngine.Authoring.model_metadata(::FixedFractionAllocation) = (
+    hypothesis="Fixed fractions, capped by each organ's demand; unused shares go to reserve.",
+    reference=nothing,
+    maturity=:pedagogical_non_calibrated,
+    validation=:structural_tests_only,
+)
+PlantSimEngine.Authoring.model_metadata(::DemandAllocation) = (
+    hypothesis="Available carbon is shared in proportion to organ demands; surplus goes to reserve.",
+    reference=nothing,
+    maturity=:pedagogical_non_calibrated,
+    validation=:structural_tests_only,
+)
+PlantSimEngine.Authoring.parameter_metadata(::FixedFractionAllocation) = (
+    leaf_fraction=(
+        description="Fraction of available carbon offered to leaves before the demand cap.",
+        unit=:fraction, domain=(minimum=0, maximum=1),
+    ),
+    wood_fraction=(
+        description="Fraction of available carbon offered to wood before the demand cap.",
+        unit=:fraction, domain=(minimum=0, maximum=1),
+    ),
+)
+
+function _check_allocation_inputs(status)
+    for variable in (:carbon_offer, :leaf_demand, :wood_demand)
+        value = getproperty(status, variable)
+        isfinite(value) && value >= zero(value) || throw(ArgumentError(
+            "`$(variable)` must be finite and nonnegative in this teaching example.",
+        ))
+    end
+    return nothing
+end
+
+# Fixed-fraction allocation kernel
+function PlantSimEngine.run!(
+    model::FixedFractionAllocation,
+    status,
+    environment,
+    constants,
+    context,
+)
+    _check_allocation_inputs(status)
+    status.leaf_growth = min(model.leaf_fraction * status.carbon_offer, status.leaf_demand)
+    # The last bound prevents roundoff from creating a negative reserve.
+    status.wood_growth = min(
+        model.wood_fraction * status.carbon_offer,
+        status.wood_demand,
+        status.carbon_offer - status.leaf_growth,
+    )
+    status.reserve_change = status.carbon_offer - status.leaf_growth - status.wood_growth
+
+    status.leaf_carbon += status.leaf_growth
+    status.wood_carbon += status.wood_growth
+    status.reserve_carbon += status.reserve_change
+    return nothing
+end
+
+# Demand-based allocation kernel
+function PlantSimEngine.run!(
+    ::DemandAllocation,
+    status,
+    environment,
+    constants,
+    context,
+)
+    _check_allocation_inputs(status)
+    total_demand = status.leaf_demand + status.wood_demand
+    isfinite(total_demand) || throw(ArgumentError("Combined organ demand must be finite."))
+    growth = min(status.carbon_offer, total_demand)
+    status.leaf_growth = iszero(total_demand) ? zero(growth) :
+                         min(status.leaf_demand, growth,
+                             growth * (status.leaf_demand / total_demand))
+    # Keep the demand caps and carbon balance even after floating-point rounding.
+    status.wood_growth = min(status.wood_demand, growth - status.leaf_growth)
+    status.reserve_change = status.carbon_offer - status.leaf_growth - status.wood_growth
+
+    status.leaf_carbon += status.leaf_growth
+    status.wood_carbon += status.wood_growth
+    status.reserve_carbon += status.reserve_change
+    return nothing
+end
+
+"""Create a reusable configuration for one plant's allocation model."""
+allocation_template(model::AllocationModel) = CompositeModelTemplate((
+    ModelSpec(model; name=:allocation, on=One(scale=:Plant)),
+))
+
+"""Create one plant, optionally replacing the template's allocation model."""
+function allocation_plant(
+    name,
+    template;
+    carbon_offer=10.0,
+    leaf_demand=8.0,
+    wood_demand=2.0,
+    allocation=nothing,
+)
+    initial_values = Status(; carbon_offer, leaf_demand, wood_demand)
+    _check_allocation_inputs(initial_values)
+    return ObjectInstance(
+        name,
+        template;
+        root=Object(name; scale=:Plant, kind=:plant, status=initial_values),
+        overrides=isnothing(allocation) ? NamedTuple() : (allocation=allocation,),
+    )
+end
+
+"""
+    build_allocation_comparison(; fixed_model, demand_model, plant_a, plant_b)
+
+Build two plants in one `CompositeModel`. Both receive 10 g C per day and
+demands of 8 g C for leaves and 2 g C for wood by default. Override `plant_a`
+or `plant_b` with a named tuple of these inputs for an independent comparison.
+Each day supplies a new carbon offer and new demands; previous reserves are
+kept but cannot be withdrawn. Run with `run!(model; steps=1, outputs=:all)`.
+"""
+function build_allocation_comparison(;
+    fixed_model=FixedFractionAllocation(0.5, 0.3),
+    demand_model=DemandAllocation(),
+    plant_a=(carbon_offer=10.0, leaf_demand=8.0, wood_demand=2.0),
+    plant_b=(carbon_offer=10.0, leaf_demand=8.0, wood_demand=2.0),
+)
+    template = allocation_template(fixed_model)
+    return CompositeModel(
+        allocation_plant(:plant_a, template; plant_a...),
+        allocation_plant(:plant_b, template; plant_b..., allocation=demand_model);
+        environment=(duration=Day(1),),
+    )
+end
+
+end # module TwoPlantAllocationExample
diff --git a/src/PlantSimEngine.jl b/src/PlantSimEngine.jl
index 5888db4b0..a5112127f 100644
--- a/src/PlantSimEngine.jl
+++ b/src/PlantSimEngine.jl
@@ -49,6 +49,7 @@ include("component_models/TimeStepTable.jl")
 
 # Model application configuration:
 include("ModelSpec.jl")
+include("composite_model/display.jl")
 
 # Model evaluation (statistics):
 include("evaluation/statistics.jl")
diff --git a/src/composite_model/display.jl b/src/composite_model/display.jl
new file mode 100644
index 000000000..03102e1de
--- /dev/null
+++ b/src/composite_model/display.jl
@@ -0,0 +1,103 @@
+# Display authored configuration only. Inspecting a model must not compile it,
+# initialize its status, sample the environment, or refresh lifecycle caches.
+function Base.show(io::IO, model::CompositeModel)
+    print(io, "CompositeModel(objects=", length(model.registry.objects),
+        ", applications=", length(model.applications))
+    isempty(model.instances) || print(io, ", instances=", length(model.instances))
+    print(io, ")")
+end
+
+function _model_display_line(io::IO, text::AbstractString)
+    width = max(1, displaysize(io)[2])
+    if textwidth(text) <= width
+        print(io, text)
+        return
+    end
+    used = 0
+    for character in text
+        used + textwidth(character) > width - 1 && break
+        print(io, character)
+        used += textwidth(character)
+    end
+    print(io, '…')
+end
+
+_model_display_label(value) = escape_string(string(value))
+
+function _model_display_scales(model::CompositeModel)
+    by_scale = model.registry.by_scale
+    scales = sort!(collect(keys(by_scale)); by=string)
+    labels = [
+        string(_model_display_label(scale), ": ", length(by_scale[scale]))
+        for scale in Iterators.take(scales, 6)
+    ]
+    length(scales) > 6 && push!(labels, "…")
+    unlabelled = length(model.registry.objects) - sum(length, values(by_scale); init=0)
+    unlabelled > 0 && push!(labels, string("no scale label: ", unlabelled))
+    return join(labels, ", ")
+end
+
+function _model_display_environment(environment)
+    isnothing(environment) && return "none"
+    name = string(nameof(typeof(environment)))
+    if environment isa TimeStepTable
+        return string(name, " (", length(environment), " rows)")
+    end
+    return name
+end
+
+function _model_display_application(application)
+    spec = application isa ModelSpec ? application : nothing
+    model = isnothing(spec) ? application : spec.model
+    base_model = model isa ObjectModelOverrides ? model.base : model
+    label = string(nameof(typeof(base_model)))
+    if !isnothing(spec) && !isnothing(spec.name)
+        label = string(_model_display_label(spec.name), ": ", label)
+    end
+    if model isa ObjectModelOverrides
+        count = length(model.overrides)
+        label *= string(" (", count, " object override", count == 1 ? "" : "s", ")")
+    end
+    if !isnothing(spec) && !isnothing(spec.timestep)
+        cadence = spec.timestep isa Dates.Period ? string(spec.timestep) :
+                  string(nameof(typeof(spec.timestep)))
+        label *= string("; every ", cadence)
+    end
+    return label
+end
+
+function Base.show(io::IO, ::MIME"text/plain", model::CompositeModel)
+    if get(io, :compact, false)
+        show(io, model)
+        return
+    end
+    _model_display_line(io, "CompositeModel")
+    scales = _model_display_scales(model)
+    objects = string("  Objects: ", length(model.registry.objects))
+    isempty(scales) || (objects *= string(" (", scales, ")"))
+    print(io, '\n')
+    _model_display_line(io, objects)
+    if !isempty(model.instances)
+        print(io, '\n')
+        _model_display_line(io, string("  Template instances: ", length(model.instances)))
+    end
+    print(io, '\n')
+    _model_display_line(io, string("  Shared environment: ", _model_display_environment(model.environment)))
+    print(io, '\n')
+    _model_display_line(io, string("  Model applications: ", length(model.applications)))
+
+    # This is a summary even when :limit is false. In a small terminal, leave
+    # room for the header and the number of omitted applications.
+    header_lines = isempty(model.instances) ? 4 : 5
+    available = get(io, :limit, false) ? max(0, displaysize(io)[1] - header_lines - 1) : 8
+    shown = min(length(model.applications), 8, available)
+    for application in Iterators.take(model.applications, shown)
+        print(io, '\n')
+        _model_display_line(io, string("    ", _model_display_application(application)))
+    end
+    remaining = length(model.applications) - shown
+    if remaining > 0
+        print(io, '\n')
+        _model_display_line(io, string("    … ", remaining, " more"))
+    end
+end
diff --git a/src/composite_model/registry_topology.jl b/src/composite_model/registry_topology.jl
index 146bc38a4..b0a0849e9 100644
--- a/src/composite_model/registry_topology.jl
+++ b/src/composite_model/registry_topology.jl
@@ -25,6 +25,25 @@ end
 ObjectId(id::ObjectId) = id
 ObjectId(id::AbstractString) = ObjectId(Symbol(id))
 
+"""
+    Object(id; scale=nothing, kind=nothing, species=nothing, name=nothing,
+           parent=nothing, children=ObjectId[], geometry=nothing,
+           status=nothing, applications=())
+
+One simulated entity, such as a canopy, plant, leaf, or soil volume. `id` is
+its stable [`ObjectId`](@ref). Labels such as `scale`, `kind`, and `name` let
+selectors choose where models run; parent and child IDs describe topology.
+The scenario chooses these labels and relationships.
+
+Supply initial model values with [`Status`](@ref). Models can share fixed
+parameters while each object owns its changing state. `geometry` may hold
+the spatial information needed by an environment provider or visualization.
+
+Pass objects to [`CompositeModel`](@ref) with their model applications. For
+changes during a simulation, use [`register_object!`](@ref),
+`remove_object!`, and `reparent_object!` so the runtime can
+refresh affected connections.
+"""
 mutable struct Object
     id::ObjectId
     scale::Union{Nothing,Symbol}
diff --git a/test/runtests.jl b/test/runtests.jl
index 5a83d8f3d..7dfec9138 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -38,6 +38,10 @@ else
         include("test-model-object-id.jl")
     end
 
+    @testset "CompositeModel display" begin
+        include("test-model-display.jl")
+    end
+
     @testset "Composite Model/Object API stabilization" begin
         include("test-model-api-stabilization.jl")
     end
@@ -182,6 +186,10 @@ else
         include("test-maespa-model-example.jl")
     end
 
+    @testset "Two-plant allocation comparison" begin
+        include("test-two-plant-allocation.jl")
+    end
+
     @testset "Status" begin
         include("test-Status.jl")
     end
diff --git a/test/test-maespa-model-example.jl b/test/test-maespa-model-example.jl
index e17baba45..21ee2c23f 100644
--- a/test/test-maespa-model-example.jl
+++ b/test/test-maespa-model-example.jl
@@ -260,8 +260,8 @@ end
     @test low_wind.canopy_air_ms ≈ m.gbcan_min
     @test isfinite(low_wind.soil_canopy_ms)
 
-    meteo_above = Atmosphere(T=25.0, Rh=0.50, Wind=1.2, Ri_PAR_f=800.0, Ri_SW_f=400.0, duration=Dates.Hour(1))
-    canopy_meteo = Atmosphere(T=25.0, Rh=0.50, Wind=1.2, P=meteo_above.P, Ri_PAR_f=800.0, Ri_SW_f=400.0, duration=Dates.Hour(1))
+    meteo_above = Atmosphere(T=25.0, Rh=0.50, Wind=1.2, Ri_PAR_f=200.0, Ri_SW_f=400.0, duration=Dates.Hour(1))
+    canopy_meteo = Atmosphere(T=25.0, Rh=0.50, Wind=1.2, P=meteo_above.P, Ri_PAR_f=200.0, Ri_SW_f=400.0, duration=Dates.Hour(1))
     hot_fluxes = (rn=5000.0, lambda_e=-5000.0, a=0.0, lai=0.75, rad_interc=0.0)
     hot = canopy_air_update(m, hot_fluxes, meteo_above, canopy_meteo, PlantMeteo.Constants())
     @test hot.tair <= meteo_above.T + 10.0
@@ -276,3 +276,68 @@ end
     @test meteo_above.T == 25.0
     @test max(0.01, meteo_above.VPD) == meteo_above.VPD
 end
+
+@testset "MAESPA illustrative radiation units" begin
+    constants = PlantMeteo.Constants()
+    weather = maespa_meteo(; nhours=73)
+    @test all(row -> 0 <= row.Ri_PAR_f <= row.Ri_SW_f, weather)
+    @test all(row -> row.Ri_PAR_f ≈ row.Ri_SW_f * constants.PAR_fraction, weather)
+
+    status = Status(leaf_Ra_SW_f=zeros(2), leaf_aPPFD=zeros(2), Ψₗ=zeros(2))
+    noon = weather[12]
+    _prepare_model_leaf_inputs!(status, noon, -0.2, constants)
+    @test status.leaf_Ra_SW_f == fill(noon.Ri_SW_f, 2)
+    @test status.leaf_aPPFD ≈ fill(noon.Ri_PAR_f * constants.J_to_umol, 2)
+    @test status.Ψₗ == fill(-0.2, 2)
+
+    # The supplied run constants, rather than a hidden default, own the conversion.
+    _prepare_model_leaf_inputs!(status, noon, -0.2, (J_to_umol=2.0,))
+    @test status.leaf_aPPFD == fill(2 * noon.Ri_PAR_f, 2)
+end
+
+@testset "MAESPA allocation accounts each carbon increment once" begin
+    status = _maespa_plant_status()
+    model = AllocA(0.35, 0.55)
+    for (cumulative, increment) in ((3.0, 3.0), (8.0, 5.0), (15.0, 7.0), (15.0, 0.0), (14.0, -1.0))
+        status.leaf_carbon[1] = cumulative
+        PlantSimEngine.run!(model, status, nothing, nothing, nothing)
+        @test status.leaf_carbon == [cumulative]
+        @test status.daily_growth ≈ increment
+        @test status.accounted_carbon ≈ cumulative
+        @test status.leaf_pool + status.wood_pool + status.reserve_pool ≈ cumulative
+    end
+end
+
+@testset "MAESPA three-day elemental carbon balance" begin
+    result = run_maespa_example(; nhours=73, check=true)
+    rows = collect_outputs(result.simulation; sink=nothing)
+    for (plant_id, leaf_ids) in (
+        (:plant_A, (:plant_A_leaf_1, :plant_A_leaf_2)),
+        (:plant_B, (:plant_B_leaf_1, :plant_B_leaf_2, :plant_B_leaf_3)),
+    )
+        state = model_status(result.model, plant_id)
+        # Independently integrate the 73 accepted assimilation samples for each
+        # leaf. Trial iterations must neither publish nor accumulate extra C.
+        accepted_carbon = sum(leaf_ids) do leaf_id
+            leaf = model_status(result.model, leaf_id)
+            assimilation = [row.value for row in rows if row.object_id == leaf_id && row.variable == :A]
+            @test length(assimilation) == 73
+            carbon = sum(assimilation) * leaf.leaf_area * 3600 * 12e-6
+            @test leaf.leaf_carbon ≈ carbon
+            carbon
+        end
+        @test sum(state.leaf_carbon) ≈ accepted_carbon
+        pool_carbon = state.leaf_pool + state.wood_pool + state.reserve_pool
+        @test pool_carbon ≈ state.accounted_carbon
+        pending_carbon = accepted_carbon - state.accounted_carbon
+        @test pool_carbon + pending_carbon ≈ accepted_carbon
+
+        history(variable) = [row.value for row in rows if row.object_id == plant_id && row.variable == variable]
+        accounted = history(:accounted_carbon)
+        growth = history(:daily_growth)
+        @test length(growth) == length(accounted) == 4
+        @test growth ≈ diff([0.0; accounted])
+        @test sum(growth) ≈ last(accounted)
+        @test history(:leaf_pool) .+ history(:wood_pool) .+ history(:reserve_pool) ≈ accounted
+    end
+end
diff --git a/test/test-model-display.jl b/test/test-model-display.jl
new file mode 100644
index 000000000..83265820b
--- /dev/null
+++ b/test/test-model-display.jl
@@ -0,0 +1,109 @@
+using Dates
+
+PlantSimEngine.@process "display_probe" verbose = false
+
+struct DisplayProbeModel{T} <: AbstractDisplay_ProbeModel
+    payload::T
+end
+
+PlantSimEngine.inputs_(::DisplayProbeModel) = NamedTuple()
+PlantSimEngine.outputs_(::DisplayProbeModel) = (count=0,)
+function PlantSimEngine.run!(::DisplayProbeModel, status, environment, constants, context)
+    status.count += 1
+    return nothing
+end
+
+# Neither model parameters nor user-defined environment displays belong in the
+# summary. A raw model must not be normalized through ModelSpec just to show it.
+struct DisplayUnreadable end
+Base.show(::IO, ::DisplayUnreadable) = error("Display must not read this value")
+
+@testset "CompositeModel display does not prepare or run the model" begin
+    model = CompositeModel(DisplayProbeModel(DisplayUnreadable()))
+    status = model_status(model, :scene)
+    revision = model.revision
+    @test isnothing(model.binding_cache)
+    @test repr(model) == "CompositeModel(objects=1, applications=1)"
+    display = repr(MIME"text/plain"(), model)
+    @test occursin("Objects: 1 (Scene: 1)", display)
+    @test occursin("DisplayProbeModel", display)
+    @test occursin("Shared environment: none", display)
+    @test !occursin("DisplayUnreadable", display)
+    @test isnothing(model.binding_cache)
+    @test isnothing(model.environment_binding_cache)
+    @test model.bindings_dirty
+    @test model.revision == revision
+    @test model_status(model, :scene) === status
+
+    simulation = run!(model; steps=1)
+    cache = model.binding_cache
+    environment_cache = model.environment_binding_cache
+    @test final_state(simulation).count == 1
+    @test repr(MIME"text/plain"(), model) == display
+    @test final_state(simulation).count == 1
+    @test model.binding_cache === cache
+    @test model.environment_binding_cache === environment_cache
+    @test !model.bindings_dirty
+
+    register_object!(model, Object(:leaf; scale=:Leaf))
+    dirty_cache = model.binding_cache
+    @test occursin("Objects: 2 (Leaf: 1, Scene: 1)", repr(MIME"text/plain"(), model))
+    @test model.bindings_dirty
+    @test model.binding_cache === dirty_cache
+
+    # This setup cannot compile (no selector), but should still be inspectable.
+    incomplete = CompositeModel(Object(:scene);
+        applications=(DisplayProbeModel(DisplayUnreadable()),),
+        environment=DisplayUnreadable())
+    @test occursin("Shared environment: DisplayUnreadable", repr(MIME"text/plain"(), incomplete))
+    @test isnothing(incomplete.binding_cache)
+    @test occursin("Objects: 0", repr(MIME"text/plain"(), CompositeModel()))
+end
+
+@testset "CompositeModel display summarizes configuration" begin
+    weather = read_weather(joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"))
+    template = CompositeModelTemplate((
+        ModelSpec(DisplayProbeModel(zeros(10_000)); name=:growth,
+            on=Many(scale=:Leaf), every=Hour(1)),
+    ))
+    plant = Object(:plant; scale=:Plant)
+    leaf = Object(:leaf; scale=:Leaf, parent=:plant)
+    model = CompositeModel(
+        ObjectInstance(:plant, template; root=plant, objects=(leaf,),
+            object_overrides=(Override(object=:leaf, application=:growth,
+                model=DisplayProbeModel(ones(10_000))),));
+        environment=weather,
+    )
+    display = repr(MIME"text/plain"(), model)
+    @test repr(model) == "CompositeModel(objects=2, applications=1, instances=1)"
+    @test occursin("Objects: 2 (Leaf: 1, Plant: 1)", display)
+    @test occursin("Template instances: 1", display)
+    @test occursin("TimeStepTable (365 rows)", display)
+    @test occursin("plant__growth: DisplayProbeModel (1 object override); every 1 hour", display)
+    @test !occursin("ObjectModelOverrides", display)
+    @test length(display) < 500
+    @test repr(MIME"text/plain"(), model; context=:compact => true) == repr(model)
+    @test count(repr(model), repr([model, model])) == 2
+end
+
+@testset "CompositeModel display stays small" begin
+    applications = [ModelSpec(DisplayProbeModel(zeros(100));
+        name=Symbol("growth_", index), on=Many(scale=:Leaf)) for index in 1:100]
+    model = CompositeModel((Object(index; scale=:Leaf) for index in 1:100)...;
+        applications=applications)
+    display = repr(MIME"text/plain"(), model)
+    @test occursin("Objects: 100 (Leaf: 100)", display)
+    @test occursin("Model applications: 100", display)
+    @test occursin("92 more", display)
+    @test length(split(display, '\n')) <= 13
+    @test length(display) < 1000
+
+    pushfirst!(model.applications, ModelSpec(DisplayProbeModel(0);
+        name=Symbol(repeat("叶", 50), "\nnext line"), on=Many(scale=:Leaf)))
+    small = sprint(show, MIME"text/plain"(), model;
+        context=(:limit => true, :displaysize => (10, 32)))
+    @test length(split(small, '\n')) <= 10
+    @test all(line -> textwidth(line) <= 32, split(small, '\n'))
+    @test occursin("…", small)
+    @test occursin("96 more", small)
+end
diff --git a/test/test-two-plant-allocation.jl b/test/test-two-plant-allocation.jl
new file mode 100644
index 000000000..64720191e
--- /dev/null
+++ b/test/test-two-plant-allocation.jl
@@ -0,0 +1,306 @@
+module TwoPlantAllocationTests
+
+using Test, PlantSimEngine, Dates
+
+include(joinpath(@__DIR__, "..", "examples", "two_plant_allocation.jl"))
+using .TwoPlantAllocationExample
+
+function allocation_status(offer, leaf_demand, wood_demand; initial=(0, 0, 0))
+    Status(
+        carbon_offer=offer,
+        leaf_demand=leaf_demand,
+        wood_demand=wood_demand,
+        leaf_growth=zero(offer),
+        wood_growth=zero(offer),
+        reserve_change=zero(offer),
+        leaf_carbon=oftype(offer, initial[1]),
+        wood_carbon=oftype(offer, initial[2]),
+        reserve_carbon=oftype(offer, initial[3]),
+    )
+end
+
+allocation_amounts(status) =
+    (status.leaf_growth, status.wood_growth, status.reserve_change)
+carbon_stocks(status) =
+    (status.leaf_carbon, status.wood_carbon, status.reserve_carbon)
+
+function calculate!(model, status)
+    PlantSimEngine.run!(model, status, NamedTuple(), nothing, nothing)
+    return status
+end
+
+@testset "Allocation equations and carbon conservation" begin
+    cases = (
+        (name="balanced supply", offer=10.0, leaf=8.0, wood=2.0,
+            fixed=(5.0, 2.0, 3.0), demand=(8.0, 2.0, 0.0)),
+        (name="scarce supply", offer=4.0, leaf=8.0, wood=2.0,
+            fixed=(2.0, 1.2, 0.8), demand=(3.2, 0.8, 0.0)),
+        (name="supply exceeds both demands", offer=20.0, leaf=3.0, wood=2.0,
+            fixed=(3.0, 2.0, 15.0), demand=(3.0, 2.0, 15.0)),
+        (name="no supply", offer=0.0, leaf=8.0, wood=2.0,
+            fixed=(0.0, 0.0, 0.0), demand=(0.0, 0.0, 0.0)),
+        (name="no demand", offer=10.0, leaf=0.0, wood=0.0,
+            fixed=(0.0, 0.0, 10.0), demand=(0.0, 0.0, 10.0)),
+        (name="wood demand only", offer=10.0, leaf=0.0, wood=2.0,
+            fixed=(0.0, 2.0, 8.0), demand=(0.0, 2.0, 8.0)),
+    )
+
+    for case in cases
+        @testset "$(case.name)" begin
+            for (model, expected) in (
+                (FixedFractionAllocation(0.5, 0.3), case.fixed),
+                (DemandAllocation(), case.demand),
+            )
+                initial = (11.0, 17.0, 23.0)
+                status = allocation_status(case.offer, case.leaf, case.wood; initial)
+                calculate!(model, status)
+
+                @test all(isapprox.(allocation_amounts(status), expected))
+                @test all(isapprox.(carbon_stocks(status), initial .+ expected))
+                @test sum(allocation_amounts(status)) ≈ case.offer
+                @test sum(carbon_stocks(status)) - sum(initial) ≈ case.offer
+                @test 0 <= status.leaf_growth <= case.leaf
+                @test 0 <= status.wood_growth <= case.wood
+                @test status.reserve_change >= 0
+            end
+        end
+    end
+end
+
+@testset "Allocation rejects invalid fractions and inputs" begin
+    for fractions in ((-0.1, 0.3), (0.5, -0.1), (0.8, 0.3), (1.1, 0.0),
+                      (NaN, 0.3), (0.5, NaN), (Inf, 0.3), (0.5, Inf))
+        @test_throws ArgumentError FixedFractionAllocation(fractions...)
+    end
+
+    for model in (FixedFractionAllocation(0.5, 0.3), DemandAllocation())
+        for input in (:carbon_offer, :leaf_demand, :wood_demand)
+            for invalid in (-1.0, NaN, Inf, -Inf)
+                status = allocation_status(10.0, 8.0, 2.0)
+                calculate!(model, status)
+                saved_amounts = allocation_amounts(status)
+                saved_stocks = carbon_stocks(status)
+                setproperty!(status, input, invalid)
+                @test_throws ArgumentError calculate!(model, status)
+                @test allocation_amounts(status) == saved_amounts
+                @test carbon_stocks(status) == saved_stocks
+            end
+        end
+    end
+
+    overflow = allocation_status(10.0, floatmax(Float64), floatmax(Float64))
+    @test_throws ArgumentError calculate!(DemandAllocation(), overflow)
+    @test carbon_stocks(overflow) == (0.0, 0.0, 0.0)
+
+    template = allocation_template(FixedFractionAllocation(0.5, 0.3))
+    @test_throws ArgumentError allocation_plant(:invalid, template; carbon_offer=-1.0)
+    @test_throws ArgumentError allocation_plant(:invalid, template; leaf_demand=NaN)
+    @test_throws ArgumentError allocation_plant(:invalid, template; wood_demand=Inf)
+end
+
+@testset "Boundary allocation fractions remain valid" begin
+    for (fractions, expected) in (
+        ((0.0, 0.0), (0.0, 0.0, 10.0)),
+        ((1.0, 0.0), (8.0, 0.0, 2.0)),
+        ((0.0, 1.0), (0.0, 2.0, 8.0)),
+    )
+        status = allocation_status(10.0, 8.0, 2.0)
+        calculate!(FixedFractionAllocation(fractions...), status)
+        @test allocation_amounts(status) == expected
+        @test sum(carbon_stocks(status)) == 10.0
+    end
+end
+
+@testset "Roundoff preserves nonnegative allocation and demand caps" begin
+    cases = (
+        (FixedFractionAllocation(0.01f0, 0.99f0), 0.7f0, 10.0f0, 10.0f0),
+        (DemandAllocation{Float32}(), 0.3f0, 0.1f0, 0.2f0),
+        (DemandAllocation(), 1.0, 0.2, 0.1),
+    )
+    for (model, offer, leaf_demand, wood_demand) in cases
+        status = allocation_status(offer, leaf_demand, wood_demand)
+        calculate!(model, status)
+        # Exact inequalities catch a negative reserve or an allocation just
+        # above demand; approximate equality alone would hide these defects.
+        @test 0 <= status.leaf_growth <= leaf_demand
+        @test 0 <= status.wood_growth <= wood_demand
+        @test status.reserve_change >= 0
+        @test sum(allocation_amounts(status)) ≈ offer
+        @test sum(carbon_stocks(status)) ≈ offer
+    end
+end
+
+@testset "Repeated calculations replace step outputs and preserve stocks" begin
+    for model in (FixedFractionAllocation(0.5, 0.3), DemandAllocation())
+        status = allocation_status(10.0, 8.0, 2.0)
+        calculate!(model, status)
+        saved_stocks = carbon_stocks(status)
+
+        status.carbon_offer = 0.0
+        calculate!(model, status)
+        @test allocation_amounts(status) == (0.0, 0.0, 0.0)
+        @test carbon_stocks(status) == saved_stocks
+
+        status.carbon_offer = 4.0
+        status.leaf_demand = 0.0
+        status.wood_demand = 0.0
+        calculate!(model, status)
+        @test allocation_amounts(status) == (0.0, 0.0, 4.0)
+        @test carbon_stocks(status) == saved_stocks .+ (0.0, 0.0, 4.0)
+        @test sum(carbon_stocks(status)) ≈ 14.0
+    end
+end
+
+@testset "Float32 allocation and alternative-model declarations" begin
+    fixed = FixedFractionAllocation(0.5f0, 0.3f0)
+    demand = DemandAllocation{Float32}()
+    @test fixed isa PlantSimEngine.Examples.AbstractCarbon_AllocationModel
+    @test demand isa PlantSimEngine.Examples.AbstractCarbon_AllocationModel
+    @test typeof(fixed) != typeof(demand)
+    @test process(fixed) == process(demand) == :carbon_allocation
+
+    comparison = Authoring.compare_models(fixed, demand)
+    @test comparison.same_process
+    @test comparison.override_compatible
+    @test !comparison.requires_binding_changes
+
+    for (model, expected) in ((fixed, (5.0f0, 2.0f0, 3.0f0)),
+                              (demand, (8.0f0, 2.0f0, 0.0f0)))
+        status = allocation_status(10.0f0, 8.0f0, 2.0f0)
+        calculate!(model, status)
+        @test allocation_amounts(status) == expected
+        @test all(value -> value isa Float32, allocation_amounts(status))
+        @test all(value -> value isa Float32, carbon_stocks(status))
+        @test Authoring.validate_model(model; strict=true).valid
+    end
+end
+
+@testset "Daily carbon offers cannot be reapplied every hour" begin
+    for model in (FixedFractionAllocation(0.5, 0.3), DemandAllocation())
+        hourly = CompositeModel(model;
+            status=(carbon_offer=10.0, leaf_demand=8.0, wood_demand=2.0),
+            environment=(duration=Hour(1),))
+        @test_throws "timestep_hint.required=1 day" run!(hourly; steps=1)
+    end
+end
+
+@testset "Two plants compare different allocation models in one simulation" begin
+    scenario = build_allocation_comparison()
+    @test scenario isa CompositeModel
+    @test Set(object_ids(scenario)) == Set((ObjectId(:plant_a), ObjectId(:plant_b)))
+    @test Authoring.validate_scenario(scenario; strict=true).valid
+
+    applications = Diagnostics.explain_applications(scenario)
+    application_a = only(row for row in applications if row.application_id == :plant_a__allocation)
+    application_b = only(row for row in applications if row.application_id == :plant_b__allocation)
+    @test length(applications) == 2
+    @test application_a.process == application_b.process
+    @test application_a.model_type <: FixedFractionAllocation
+    @test application_b.model_type <: DemandAllocation
+    @test application_a.target_ids == [:plant_a]
+    @test application_b.target_ids == [:plant_b]
+
+    simulation = run!(scenario; outputs=:all)
+    state_a = final_state(simulation, :plant_a)
+    state_b = final_state(simulation, :plant_b)
+    @test current_step(simulation) == 1
+    @test allocation_amounts(state_a) == (5.0, 2.0, 3.0)
+    @test allocation_amounts(state_b) == (8.0, 2.0, 0.0)
+    @test carbon_stocks(state_a) == (5.0, 2.0, 3.0)
+    @test carbon_stocks(state_b) == (8.0, 2.0, 0.0)
+    @test sum(carbon_stocks(state_a)) + sum(carbon_stocks(state_b)) == 20.0
+
+    continue!(simulation; steps=2)
+    @test current_step(simulation) == 3
+    @test carbon_stocks(final_state(simulation, :plant_a)) == (15.0, 6.0, 9.0)
+    @test carbon_stocks(final_state(simulation, :plant_b)) == (24.0, 6.0, 0.0)
+
+    # With no new carbon, plant A must stop growing without reusing yesterday's
+    # outputs. Plant B still receives its own unchanged supply and demands.
+    status_a = model_status(scenario, :plant_a)
+    status_b = model_status(scenario, :plant_b)
+    status_a.carbon_offer = 0.0
+    @test (status_b.carbon_offer, status_b.leaf_demand, status_b.wood_demand) == (10.0, 8.0, 2.0)
+    step!(simulation)
+    @test current_step(simulation) == 4
+    @test allocation_amounts(final_state(simulation, :plant_a)) == (0.0, 0.0, 0.0)
+    @test carbon_stocks(final_state(simulation, :plant_a)) == (15.0, 6.0, 9.0)
+    @test carbon_stocks(final_state(simulation, :plant_b)) == (32.0, 8.0, 0.0)
+
+    # Carbon offered to a plant with no growth demand goes entirely to reserve.
+    status_a.carbon_offer = 4.0
+    status_a.leaf_demand = 0.0
+    status_a.wood_demand = 0.0
+    continue!(simulation; steps=2)
+    @test current_step(simulation) == 6
+    @test allocation_amounts(final_state(simulation, :plant_a)) == (0.0, 0.0, 4.0)
+    @test allocation_amounts(final_state(simulation, :plant_b)) == (8.0, 2.0, 0.0)
+    @test carbon_stocks(final_state(simulation, :plant_a)) == (15.0, 6.0, 17.0)
+    @test carbon_stocks(final_state(simulation, :plant_b)) == (48.0, 12.0, 0.0)
+    @test (status_b.carbon_offer, status_b.leaf_demand, status_b.wood_demand) == (10.0, 8.0, 2.0)
+
+    rows = collect_outputs(simulation; sink=nothing)
+    expected = (
+        plant_a=(
+            leaf_growth=[5.0, 5.0, 5.0, 0.0, 0.0, 0.0],
+            wood_growth=[2.0, 2.0, 2.0, 0.0, 0.0, 0.0],
+            reserve_change=[3.0, 3.0, 3.0, 0.0, 4.0, 4.0],
+            leaf_carbon=[5.0, 10.0, 15.0, 15.0, 15.0, 15.0],
+            wood_carbon=[2.0, 4.0, 6.0, 6.0, 6.0, 6.0],
+            reserve_carbon=[3.0, 6.0, 9.0, 9.0, 13.0, 17.0],
+        ),
+        plant_b=(
+            leaf_growth=fill(8.0, 6),
+            wood_growth=fill(2.0, 6),
+            reserve_change=zeros(6),
+            leaf_carbon=[8.0, 16.0, 24.0, 32.0, 40.0, 48.0],
+            wood_carbon=[2.0, 4.0, 6.0, 8.0, 10.0, 12.0],
+            reserve_carbon=zeros(6),
+        ),
+    )
+    @test length(rows) == 2 * 6 * 6
+    for (plant_id, plant_expected) in pairs(expected)
+        application_id = Symbol(plant_id, "__allocation")
+        for (variable, expected_values) in pairs(plant_expected)
+            stream = filter(row -> row.object_id == plant_id && row.variable == variable, rows)
+            @test getproperty.(stream, :application_id) == fill(application_id, 6)
+            @test getproperty.(stream, :timestep) == collect(1:6)
+            @test getproperty.(stream, :value) ≈ expected_values
+        end
+    end
+
+    cumulative_offers = (
+        plant_a=[10.0, 20.0, 30.0, 30.0, 34.0, 38.0],
+        plant_b=[10.0, 20.0, 30.0, 40.0, 50.0, 60.0],
+    )
+    stock_variables = (:leaf_carbon, :wood_carbon, :reserve_carbon)
+    for timestep in 1:6
+        scene_carbon = 0.0
+        for (plant_id, supplied) in pairs(cumulative_offers)
+            stored_carbon = sum(
+                row.value for row in rows
+                if row.object_id == plant_id && row.timestep == timestep &&
+                   row.variable in stock_variables
+            )
+            @test stored_carbon ≈ supplied[timestep]
+            scene_carbon += stored_carbon
+        end
+        @test scene_carbon ≈ cumulative_offers.plant_a[timestep] + cumulative_offers.plant_b[timestep]
+    end
+end
+
+@testset "Float32 survives plant templates and model replacement" begin
+    daily_inputs = (carbon_offer=10.0f0, leaf_demand=8.0f0, wood_demand=2.0f0)
+    scenario = build_allocation_comparison(
+        fixed_model=FixedFractionAllocation(0.5f0, 0.3f0),
+        demand_model=DemandAllocation{Float32}(),
+        plant_a=daily_inputs,
+        plant_b=daily_inputs,
+    )
+    simulation = run!(scenario; steps=2, outputs=:all)
+    @test carbon_stocks(final_state(simulation, :plant_a)) == (10.0f0, 4.0f0, 6.0f0)
+    @test carbon_stocks(final_state(simulation, :plant_b)) == (16.0f0, 4.0f0, 0.0f0)
+    @test all(row -> row.value isa Float32, collect_outputs(simulation; sink=nothing))
+end
+
+end # module TwoPlantAllocationTests