API - internal functions​#

TimeStepTable{Status}(df::DataFrame)

Method to build a TimeStepTable (from PlantMeteo.jl) from a DataFrame, but with each row being a Status.

Examples

using PlantSimEngine, DataFrames

# A TimeStepTable from a DataFrame:
df = DataFrame(
    Tₗ=[25.0, 26.0],
    aPPFD=[1000.0, 1200.0],
    Cₛ=[400.0, 400.0],
    Dₗ=[1.0, 1.2],
)
TimeStepTable{Status}(df)

# A TimeStepTable can also be built directly from Status values:
TimeStepTable(
    [
        Status(Tₗ=25.0, aPPFD=1000.0, Cₛ=400.0, Dₗ=1.0),
        Status(Tₗ=26.0, aPPFD=1200.0, Cₛ=400.0, Dₗ=1.2),
    ]
)

AbstractEnvironmentBackend

Backend protocol for meteorology and mutable microclimate providers.

PlantSimEngine defines the protocol, not the spatial indexing strategy. External packages subtype PlantSimEngine.EnvironmentAPI.AbstractEnvironmentBackend and extend the functions in PlantSimEngine.EnvironmentAPI, including sample, commit_environment!, update_index!, get_nsteps, and base_step_seconds.

Append-only object lifecycle events pending the next runtime refresh barrier. The dirty-id sets are derived indices shared by every runtime consumer.

Immutable scenario-level metadata for one model application. Runtime object membership is stored separately in CompiledModelApplication.

Immutable cadence definitions for root-scheduled applications.

One immutable root-scheduler rule in stable topological order.

Object-dependent runtime state for one compiled application.

Immutable authored hard-call declaration for one application.

Immutable authored input declaration for one application.

Compiled columnar references for one execution object and output group.

Immutable authored cross-object output declaration for one application.

A named topology scope resolved once while the scenario plan is compiled.

Immutable application, dependency-declaration, and timeline metadata shared by every lifecycle refresh of a compiled scenario.

Normalized selector criteria used by lifecycle membership checks without reinterpreting the authored selector at every structural refresh.

One declared owner of a status variable on a destination object.

CompositeModelCompilationReport

Best-effort result of compiling a CompositeModel for inspection. Unlike compile_composite_model, this representation preserves successful earlier phases when a later phase reports an invalid selector, binding, writer, or cycle.

DataFormat(T::Type)

Returns the data format of the type T. The data format is used to determine how to iterate over the data. The following data formats are supported:

• TableAlike: The data is a table-like object, e.g. a DataFrame or a TimeStepTable. The data is iterated over by rows using the Tables.jl interface.

• SingletonAlike: The data is a singleton-like object, e.g. a NamedTuple or a TimeStepRow. The data is iterated over by columns.

The default implementation returns TableAlike for AbstractDataFrame, TimeStepTable, AbstractVector, and Dict; and SingletonAlike for Status, NamedTuple, and TimeStepRow.

The default implementation for Any throws an error. Users that want to use another input should define this trait for the new data format, e.g.:

PlantSimEngine.DataFormat(::Type{<:MyType}) = TableAlike()

Examples

julia> using PlantSimEngine, PlantMeteo, DataFrames

julia> PlantSimEngine.DataFormat(DataFrame)
PlantSimEngine.TableAlike()

julia> PlantSimEngine.DataFormat(TimeStepTable([Status(a = 1, b = 2, c = 3)]))
PlantSimEngine.TableAlike()

julia> PlantSimEngine.DataFormat([1, 2, 3])
PlantSimEngine.TableAlike()

julia> PlantSimEngine.DataFormat(Dict(:a => 1, :b => 2))
PlantSimEngine.TableAlike()

julia> PlantSimEngine.DataFormat(Status(a = 1, b = 2, c = 3))
PlantSimEngine.SingletonAlike()

EnvironmentContext(application, object_id, scale, process)

Immutable model-target metadata passed to bind_environment. Backends return an opaque handle from that method and use the handle for all subsequent sampling and commits. Runtime status and geometry are intentionally absent: object-to-environment routing belongs to the compiled handle.

GlobalConstant(source)

Environment backend that preserves the current PlantSimEngine behavior: every model receives the same source object or source row at a given timestep.

One geometry mutation and every environment handle it can affect.

Labels and topology captured for one object at a lifecycle event.

One subtree reparenting recorded before runtime buffers refresh.

ModelApplicationRef(scope, application_id; instance=nothing)
GlobalApplicationRef(application_id)
TemplateApplicationRef(instance, application_id)

Identify the declaration that owns an editable model application. Global applications are owned directly by the CompositeModel; template applications are owned by the shared CompositeModelTemplate mounted by instance.

Compiled mounted ids such as plant_a__leaf_area are deliberately not accepted as declaration identities. The graph DTO carries both the compiled id and this owner reference.

ModelComparison

Comparison of two concrete model instances. override_compatible is computed from model_interface, the same representation enforced by runtime object and instance overrides. requires_binding_changes identifies port, contract, dependency, output-policy, or environment-binding changes; requires_reconfiguration also covers schedule-only trait differences.

Structured model-level Input, Call, or Initializer declaration.

ModelDescription

Versioned description of a model instance or type. Descriptions created from an instance have provenance == :exact; descriptions requested from a type are marked :best_effort and are complete only when a real zero-argument constructor exists. field_provenance qualifies each part independently so tooling never mistakes inferred source locations or best-effort constructor metadata for exact model declarations. Type descriptions never invent parameter values by dummy construction.

One structured difference between two model implementations.

ModelGraphDiagnostic

Structured diagnostic emitted while compiling a model for visualization. A graph report keeps diagnostics attached to stable application, object, and variable identities so an editor can present actionable controls.

ModelGraphView

JSON-oriented, renderer-independent representation of a Composite Model/Object graph. Applications are the default visual unit; executions optionally expands them into concrete (application, object) targets.

ModelInterface

Versioned representation of every model declaration that the compiler takes from the base application when it installs an object or instance override. Two model instances are directly override-compatible when their semantic fields are equal. provenance records whether the declarations were read from the supplied instance (:exact) or from a real zero-argument instance created for type-only inspection (:best_effort); it does not change compatibility.

Exact parameter value captured from a concrete model instance.

Structured status or environment port declared by a model instance.

Typed result of structurally validating one model instance.

Zero-cost marker used when a scenario has no distributed outputs.

Zero-cost marker used when a compiled scene has no distributed outputs.

ObjectAddress(selector)

Return the normalized, structured diagnostic address for an object selector. The address preserves scope, object labels, producer/callee routing, temporal policy/window, live-status ordering, and multiplicity.

Mutable row-mapping cache owned by one simulation execution target.

RefVector(field::Symbol, sts...)
RefVector(field::Symbol, sts::Vector{<:Status})
RefVector(v::Vector{Base.RefValue{T}})

A vector of references to a field of a vector of structs. This is used to efficiently pass the values between scales.

Arguments

• field: the field of the struct to reference

• sts...: the structs to reference

• sts::Vector{<:Status}: a vector of structs to reference

Examples

julia> using PlantSimEngine

Let's take two Status structs:

julia> status1 = Status(a = 1.0, b = 2.0, c = 3.0);

julia> status2 = Status(a = 2.0, b = 3.0, c = 4.0);

We can make a RefVector of the field a of the structs st1 and st2:

julia> rv = PlantSimEngine.RefVector(:a, status1, status2)
2-element PlantSimEngine.RefVector{Float64}:
 1.0
 2.0

Which is equivalent to:

julia> rv = PlantSimEngine.RefVector(:a, [status1, status2])
2-element PlantSimEngine.RefVector{Float64}:
 1.0
 2.0

We can access the values of the RefVector:

julia> rv[1]
1.0

Updating the value in the RefVector will update the value in the original struct:

julia> rv[1] = 10.0
10.0

julia> status1.a
10.0

We can also make a RefVector from a vector of references:

julia> vec = [Ref(1.0), Ref(2.0), Ref(3.0)]
3-element Vector{Base.RefValue{Float64}}:
 Base.RefValue{Float64}(1.0)
 Base.RefValue{Float64}(2.0)
 Base.RefValue{Float64}(3.0)

julia> rv = PlantSimEngine.RefVector(vec)
3-element PlantSimEngine.RefVector{Float64}:
 1.0
 2.0
 3.0

julia> rv[1]
1.0

Resolved destination membership before status references are constructed.

Columnar retained streams for one distributed output variable.

RuntimePerformanceCounters

Opt-in coarse runtime instrumentation used by the performance regression suite. Pass performance=true to run!, then inspect a copy of the recorded counters with runtime_performance.

The disabled path stores nothing in the simulation and does not call time_ns(). Counters deliberately cover compiler/runtime boundaries rather than individual scientific kernels so instrumentation does not change kernel dispatch or allocation behavior.

RuntimeTemporalInput

Per-simulation temporal input state compiled into an execution target. It shares direct references to the producer streams with every compatible consumer, avoiding a global stream-dictionary lookup in the per-target loop.

ScenarioValidationReport

Typed, versioned validation result for a CompositeModel. compilation retains the existing best-effort compilation report for Julia consumers; Authoring.to_dict and Authoring.to_json serialize its stable summary and diagnostics rather than compiler internals.

Reverse candidate index for compiled selector matchers.

TemporalDependencyBuffer{T} <: AbstractVector{Tuple{Float64,T}}

Typed, bounded storage for an output retained only to satisfy temporal model dependencies. Requested and outputs=:all streams continue to use append-only vectors. The logical indexing order is oldest to newest, independently of the physical circular-buffer layout.

Internal timing context for one model run.

ValidationDiagnostic

Stable diagnostic returned by the public authoring validation API. context contains structured identities supplied by the underlying compiler, such as an application, object, variable, or validation field.

Mutable, storage-neutral recipe used to assemble one canonical object status.

The recipe keeps existing field order and reference identity, stages additions or replacements in place, then materializes at most one new Status. Keeping the logical names separate from the current Ref backing also leaves a small seam for a future columnar status-storage experiment.

EF(obs,sim)

Returns the Efficiency Factor between observations obs and simulations sim using NSE (Nash-Sutcliffe efficiency) model. More information can be found at https://en.wikipedia.org/wiki/Nash%E2%80%93Sutcliffemodelefficiency_coefficient.

The closer to 1 the better.

Examples

using PlantSimEngine.Evaluation

obs = [1.0, 2.0, 3.0]
sim = [1.1, 2.1, 3.1]

EF(obs, sim)

NRMSE(obs,sim)

Returns the Normalized Root Mean Squared Error between observations obs and simulations sim. Normalization is performed using division by observations range (max-min).

Examples

using PlantSimEngine.Evaluation

obs = [1.0, 2.0, 3.0]
sim = [1.1, 2.1, 3.1]

NRMSE(obs, sim)

RMSE(obs,sim)

Returns the Root Mean Squared Error between observations obs and simulations sim.

The closer to 0 the better.

Examples

using PlantSimEngine.Evaluation

obs = [1.0, 2.0, 3.0]
sim = [1.1, 2.1, 3.1]

RMSE(obs, sim)

call_model(context::RunContext, name::Symbol)

Return the concrete model for a declared hard call that currently resolves to exactly one execution target. This is the allocation-free singular access path for a controller that needs to dispatch on or inspect its fixed dependency model before executing it.

Use call_targets when status access, selective execution, or more than one target is required. The returned model is the model stored in the compiled execution target and remains valid until a lifecycle refresh barrier.

apply_model_graph_edit(model, edit; preserve=())

Apply one declarative graph edit transactionally. The input model is not modified; a deep-copied, cache-invalidated CompositeModel is returned. Configuration that is temporarily incomplete or cyclic is retained so the editor can display and repair it. Structural edit errors leave the original model unchanged. Values listed in preserve retain their identity inside the copy; editor sessions use this for server-side template and environment catalogs.

Resolve one call binding against the model and compiled application set.

This helper is deliberately non-mutating. Cold manual Many bindings use it for diagnostics and graph inspection without enrolling themselves in lifecycle tracking.

run_call!(target::CallTarget; publish=false, sampled_environment)

Run one manually selected model call. By default, the call mutates its target status without publishing outputs or environment updates, which is suitable for trial iterations. Pass publish=true once for the accepted state. When sampled_environment is provided, it is forwarded directly to this target instead of using its compiled environment binding. This is the fine-grained escape hatch for one selected target; execute provider-aware trial states for all targets with run_call!(context, name; environment=state).

The method returns the same CallTarget.

Publication permission is inherited through the call stack. A descendant cannot publish outputs or environment writes while any ancestor is running as a trial.

For fine-grained control, obtain a collection with call_targets, then select or iterate its targets:

targets = call_targets(context, :leaf_energy)
for (target, target_environment) in zip(targets, environments_by_leaf)
    run_call!(
        target;
        sampled_environment=target_environment,
        publish=false,
    )
end

accepted = accepted_environment(model, status)
commit_environment!(context, accepted)
for target in targets
    run_call!(target; publish=true)
end

available_models()
available_models(process::Symbol)
available_models(process_type::Type{<:AbstractModel})

Return concrete model implementation types visible in the current Julia session.

available_processes()

Return process abstract model types visible in the current Julia session. Loading another package with using PackageName makes its process and model types discoverable without a separate registry.

base_step_seconds(backend)

Return the duration of one simulation base step in seconds.

bind_environment(backend, object, context, config=nothing)

Compile and return an opaque backend-specific handle for one model target. context contains immutable application/object metadata and config is the payload declared with Environment(...). Spatial backends should resolve the object's geometry here and store the resulting cell, voxel, layer, provider, or commit sink in a concrete handle. Runtime sampling and commits receive that handle directly.

compare_models(left::AbstractModel, right::AbstractModel)

Compare two concrete implementations. The report distinguishes a direct runtime override from a same-process alternative that requires scenario reconfiguration, and from a model for a different process. Direct compatibility uses the same complete ModelInterface enforced by runtime overrides: full port schemas, contracts, dependencies, and compiled timing/environment traits must all match.

compile_composite_model(model[, applications...])

Compile model applications, selectors, value bindings, hard calls, writer ordering, and schedules into the single Composite Model/Object runtime representation. Most callers can use run! directly, which compiles as needed.

compile_model_graph(model; level=:applications, strict=false,
                    templates=NamedTuple(), environments=NamedTuple())
compile_model_graph(compiled::CompiledCompositeModel; level=:applications,
                    templates=NamedTuple(), environments=NamedTuple())

Build a renderer-independent graph view from a Composite model or an existing compiled model. Named template and environment catalogs add schema-v2 descriptors without serializing runtime environment values.

compile_model_report(model; strict=false)

Compile a Composite model for visualization while retaining partial graph information and structured diagnostics. With strict=true, call the simulation compiler and propagate its errors unchanged.

compiled_model_source(model::CompositeModel;
                      function_name=:compiled_model!,
                      constants=PlantMeteo.Constants())
compiled_model_source(simulation::Simulation;
                      function_name=:compiled_model!)

Generate an executable Julia script that spells out the resolved application order of a CompositeModel, includes the source body of every model kernel, documents resolved inputs, manual calls, and newborn initializers, and executes those generated kernels through the normal PlantSimEngine state, environment, output, and lifecycle machinery.

The generated script defines two methods named by function_name: one starts a fresh simulation from a CompositeModel, and one advances an existing Simulation. The default output is intentionally optimized for reading and review rather than for replacing PlantSimEngine's normal optimized executor.

describe_model(model::AbstractModel)
describe_model(::Type{<:AbstractModel})

Describe a concrete instance exactly, including current parameter names, types, and values. The type method is explicitly best-effort: it uses a real zero-argument constructor when one exists and otherwise returns an incomplete description with a diagnostic. field_provenance distinguishes exact model declarations from inferred locations and constructor metadata. Neither method creates a dummy parameter instance; the instance method never calls another model constructor or relabels current parameter values as constructor defaults.

diff_vars(x, y)

Returns the names of variables that have different values in x and y.

dr(obs,sim)

Returns the Willmott’s refined index of agreement dᵣ. Willmot et al. 2011. A refined index of model performance. https://rmets.onlinelibrary.wiley.com/doi/10.1002/joc.2419

The closer to 1 the better.

Examples

using PlantSimEngine.Evaluation

obs = [1.0, 2.0, 3.0]
sim = [1.1, 2.1, 3.1]

dr(obs, sim)

edit_graph([model]; kwargs...)

Start the HTTP-backed interactive CompositeModel editor. Call edit_graph() to begin with an empty CompositeModel. The implementation is provided by the HTTP package extension.

environment_backend(environment_or_backend)

Return an environment backend. Plain environment data is wrapped in GlobalConstant; existing environment backends are returned unchanged.

environment_variables(backend)

Return a set of variable names that the backend can provide, or nothing when the backend cannot enumerate them cheaply.

explain_environment(simulation)

Return a compact description of the environment backend used by a model simulation.

explain_initialization(model::CompositeModel)

Return structured rows describing how every application variable is initialized. disposition is one of:

• :supplied: present on the object's status before compilation;

• :generated: created from a model output declaration;

• :producer_bound: connected through an explicit or inferred inputs binding;

• :environment_bound: provided by the selected environment backend;

• :unresolved: still requires user or scenario configuration.

Unlike compile_composite_model, this report does not fail solely because a required status or environment value is unresolved. Selector, writer, call, and other invalid configuration errors remain errors.

Diagnostics.explain_output_bindings(model_or_compiled)

Return one structured row per compiled cross-object output destination. Rows separate the application execution object from current destination object IDs and report declared variables, carrier types, coverage, and lifecycle generation.

explain_runtime_performance(simulation)

Group the opt-in counters produced by run!(...; performance=true) into immutable plan compilation, object-target instantiation, lifecycle buffer updates, steady-state execution, output collection, and initial-total rows. Each row reports either or both of count and elapsed_seconds. The function returns an empty vector when performance instrumentation was disabled.

fit()

Optimize the parameters of a model using measurements and (potentially) initialisation values.

Modellers should implement a method to fit for their model, with the following design pattern:

The call to the function should take the model type as the first argument (T::Type{<:AbstractModel}), the data as the second argument (as a Table.jl compatible type, such as DataFrame), and the parameters initializations as keyword arguments (with default values when necessary).

For example, the method for fitting the Beer model from the example script (see examples/Beer.jl) uses this mathematical identity after validating each observation:

J_to_umol = PlantMeteo.Constants().J_to_umol
incident_ppfd = J_to_umol .* df.Ri_PAR_f
f_abs = df.aPPFD ./ incident_ppfd
k = Statistics.mean(-log1p.(-f_abs) ./ df.LAI)

This is only the inversion, not a complete implementation to copy. The shipped Beer method also rejects empty data and invalid LAI, incident flux, and absorbed fractions with row-specific errors.

Here, Ri_PAR_f is incident PAR in W m[ground]⁻², aPPFD is the PAR absorbed by the canopy in μmol[PAR] m[ground]⁻² s⁻¹, and LAI is in m[leaf]² m[ground]⁻². A mean leaf-area-basis PPFD is a different quantity and must not be passed to this fit.

The function should return the optimized parameters as a NamedTuple of the form (parameter_name=parameter_value,).

Here is an example usage with the Beer model, where we fit the k parameter from "measurements" of aPPFD, LAI and Ri_PAR_f.

# Including example processes and models:
using PlantSimEngine.Examples;
using PlantSimEngine.Evaluation;

meteo = Atmosphere(
    T=20.0,
    Wind=1.0,
    P=101.3,
    Rh=0.65,
    Ri_PAR_f=300.0,
    duration=Hour(1),
)
model = CompositeModel(
    Beer(0.6);
    status=(LAI=2.0,),
    id=:plant,
    scale=:Plant,
    environment=meteo,
)
simulation = run!(model)
plant = final_state(simulation, One(scale=:Plant))
data = DataFrame(
    aPPFD=[plant.aPPFD],
    LAI=[plant.LAI],
    Ri_PAR_f=[meteo.Ri_PAR_f[1]],
)
Evaluation.fit(Beer, data)

This is a synthetic round trip: it simulates canopy-absorbed aPPFD with k=0.6, then recovers the same value from the ground-area-basis fluxes.

model_constructor_descriptor(::Type{<:AbstractModel})

Return best-effort constructor metadata inferred from struct fields, declared constructor methods, and an optional zero-argument constructor. Type inspection never executes a placeholder construction. Fields that share a type parameter share a type choice in the editor.

model_interface(model::AbstractModel)

Return the exact public interface enforced when model is used as an object or instance override. This method reads the supplied instance; it never creates a dummy model or guesses parameter values.

The interface includes the full status and environment schemas, scientific contracts, model-level dependencies, clock, output policy, timestep hint, and environment hint because object overrides execute behind declarations compiled from the base application.

model_interface(::Type{<:AbstractModel})

Return a best-effort interface only when the type has a real zero-argument constructor. If it does not, pass the concrete model instance instead; this method never constructs placeholder parameter values.

model_metadata(model)

Optional author-declared model metadata. Downstream packages may return a NamedTuple containing fields such as summary, hypothesis, references, or maturity. PlantSimEngine does not infer scientific metadata.

object_address(selector)

Return an ObjectAddress containing every normalized selector field.

parameter_metadata(model)

Optional metadata keyed by fields of model. Each value must be a NamedTuple; authors may use fields such as description, unit, domain, default, reference, or constraints. PlantSimEngine validates only the structure and never invents scientific metadata or constructor defaults.

runtime_performance(simulation)

Return a stable snapshot of opt-in runtime performance counters, or nothing when the simulation was not started with performance=true. Elapsed values are reported in seconds while the internal counters retain nanosecond resolution.

sample(backend, handle, variable, time)
sample(backend, handle, state, variable, time)

Sample one environmental variable through an opaque compiled backend handle. The four-argument method reads the backend's committed state. The five-argument method reads a transient backend-specific state supplied through run_call!(context, name; environment=state).

sample_environment(backend, handle, time, variables)
sample_environment(backend, handle, state, time, variables)

Sample a model-facing source row through a compiled backend handle. GlobalConstant returns the original row; other backends return a NamedTuple assembled from sample calls. The overload containing state preserves the same handle while sampling a transient environment.

scenario_source(model::CompositeModel; environments=Dict{Symbol,Any}())

Return Julia source that reconstructs model as a variable named model.

environments is an optional symbol-keyed catalog of runtime environment values. Catalog values are referenced by identity in the generated source as scenario_environments.<name> instead of being serialized. The generated source records the required catalog names in a leading comment so callers can check them before evaluation.

The source preserves model objects, object-local applications, templates, instances, model and object overrides, application configuration, effective status values, and safely reconstructible status-conversion policies. Values that cannot be represented safely are described with # WARNING: comments in the generated source.

to_dict(value)

Return the stable, JSON-compatible dictionary representation of an Authoring description, comparison, diagnostic, or validation report.

Return a JSON representation of any public Authoring description or report.

update_index!(backend, changed_entities, removed_object_ids)

Update the backend spatial/entity index after topology or geometry changes. changed_entities contains only new or changed objects and removed_object_ids contains stable ObjectIds that no longer exist. The initial compilation supplies every entity and an empty removal vector.

validate_model(model::AbstractModel; strict=false)

Validate a model's structural declarations without executing its scientific kernel. With strict=true, every declared status and environment port must have a VariableContract. The default remains incremental-adoption compatible.

validate_scenario(model::CompositeModel; strict=false)

Validate a scenario through the existing best-effort compiler and return its partial result even when an application, binding, writer, or schedule is invalid. strict=true additionally requires exact compiler acceptance and strict validation of each resolved model instance.

variable_contracts_(model::AbstractModel)

Trait declaring the scientific contracts of status and environment variables used by model. Return a named tuple whose keys are variables declared by inputs_, outputs_, environment_inputs_, or environment_outputs_, and whose values are VariableContracts. A model that produces values only through distributed output groups may also declare those names; each compiled ModelSpec must then include them in outputs_to.

The default is empty for incremental adoption. Once either side of a compiled model-to-model input binding declares a contract, the other side must declare the same complete contract. This prevents a contracted variable from silently falling back to name-only coupling.

variables_typed(model)
variables_typed(model, models...)

Returns a named tuple with the name and the types of the variables needed by a model, or a union of those for several models.

Examples

using PlantSimEngine;

# Load the dummy models given as example in the package:
using PlantSimEngine.Examples;

PlantSimEngine.variables_typed(Process1Model(1.0))
(var1 = Float64, var2 = Float64, var3 = Float64)

PlantSimEngine.variables_typed(Process1Model(1.0), Process2Model())

# output
(var4 = Float64, var5 = Float64, var1 = Float64, var2 = Float64, var3 = Float64)

See also

inputs, outputs and variables

write_compiled_model_source(path, model; kwargs...)

Write compiled_model_source output to path and return path.

write_model_graph_view(path, scene_or_view; level=:applications,
                       strict=false, renderer=:react)

Write a self-contained static Model graph viewer. The default renderer uses the bundled frontend when available and otherwise falls back to the standalone viewer.