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 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.

For scientific equations, explore packages such as PlantBiophysics.jl, for plant biophysical processes, and XPalm, 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.

For plant–environment interactions, the MAESPA-style example 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.

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. Follow the model replacement guide 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.

• 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.

• Follow changes in plant structure. Add or remove organs during a simulation and let PlantSimEngine update the affected model connections. Model a changing structure.

• Inspect what is connected. Find the source of an input, inspect the execution order and diagnose missing or ambiguous connections. Explore a model graph.

• 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.

• 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.

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, or use the same model descriptions and checks directly from Julia.

Choose your starting point​#

The examples introduce Julia as it is needed. If you are new to the language, start with installation and Julia basics.

A small simulation in Julia​#

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.

First follow the installation instructions to get the package version used by this manual and the tutorial dependencies.

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.

using PlantSimEngine, PlantMeteo, Dates, DataFrames
using PlantSimEngine.Examples

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,
)

Choose the models and run the full weather year:

model = CompositeModel(
    ToyDegreeDaysCumulModel(),
    ToyLAIModel(),
    Beer(0.6);
    environment=meteo_day,
)

simulation = run!(model; steps=length(meteo_day), outputs=:all)
results = collect_outputs(simulation; sink=DataFrame)

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 explains these connections and shows how to continue a simulation; the plotting guide explains how to display results.

Scientific models and further reading​#

PlantSimEngine provides the simulation tools. Model packages provide equations, parameters and their scientific validation. Examples of packages using PlantSimEngine include:

• PlantBiophysics.jl, for plant biophysical processes such as photosynthesis, stomatal conductance and energy balance.

• XPalm, for oil-palm growth and development.

Their documentation describes the models available, their assumptions and supported package versions. To choose an approach, read Why PlantSimEngine?. For a published application and its validation, see the PlantBiophysics paper.

PlantSimEngine is open source under the MIT license. For questions or feedback, open an issue or join the Virtual Plant Lab discussion.