PlantSimEngine
Overview
PlantSimEngine
is a package for the simulation and modelling of plants, soil and atmosphere. It is designed to help researchers and practitioners prototype, implement, test plant/crop models at any scale, without the hassle of computer science technicality behind model coupling, running on several time-steps or objects.
The package defines a framework for declaring processes and implementing associated models for their simulation.
It focuses on key aspects of simulation and modeling such as:
- Easy definition of new processes, such as light interception, photosynthesis, growth, soil water transfer...
- Fast, interactive prototyping of models, with constraints to help users avoid errors, but sensible defaults to avoid over-complicating the model writing process
- No hassle, the package manages automatically input and output variables, time-steps, objects, soft and hard coupling of models with a dependency graph
- Switch between models without changing any code, with a simple syntax to define the model to use for a given process
- Reduce the degrees of freedom by fixing variables, passing measurements, or using a simpler model for a given process
๐ (very) fast computation๐ , think of 100th of nanoseconds for one model, two coupled models (see this benchmark script), or the full energy balance of a leaf using PlantBiophysics.jl that uses PlantSimEngine- Out of the box Sequential, Parallel (Multi-threaded) or Distributed (Multi-Process) computations over objects, time-steps and independent processes (thanks to Floops.jl)
- Easily scalable, with methods for computing over objects, time-steps and even Multi-Scale Tree Graphs
- Composable, allowing the use of any types as inputs such as Unitful to propagate units, or MonteCarloMeasurements.jl to propagate measurement error
Installation
To install the package, enter the Julia package manager mode by pressing ]
in the REPL, and execute the following command:
add PlantSimEngine
To use the package, execute this command from the Julia REPL:
using PlantSimEngine
Example usage
The package is designed to be easy to use, and to help users avoid errors when implementing, coupling and simulating models.
Simple example
Here's a simple example of a model that simulates the growth of a plant, using a simple exponential growth model:
# ] add PlantSimEngine
using PlantSimEngine
# Include the model definition from the examples folder:
include(joinpath(pkgdir(PlantSimEngine), "examples/ToyLAIModel.jl"))
# Define the model:
model = ModelList(
ToyLAIModel(),
status=(degree_days_cu=1.0:2000.0,), # Pass the cumulated degree-days as input to the model
)
run!(model) # run the model
status(model) # extract the status, i.e. the output of the model
Which gives:
TimeStepTable{Status{(:degree_days_cu, :LAI...}(1300 x 2):
โญโโโโโโฌโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโฎ
โ Row โ degree_days_cu โ LAI โ
โ โ Float64 โ Float64 โ
โโโโโโโผโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโค
โ 1 โ 1.0 โ 0.00560052 โ
โ 2 โ 2.0 โ 0.00565163 โ
โ 3 โ 3.0 โ 0.00570321 โ
โ 4 โ 4.0 โ 0.00575526 โ
โ 5 โ 5.0 โ 0.00580778 โ
โ โฎ โ โฎ โ โฎ โ
โฐโโโโโโดโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโฏ
1295 rows omitted
Note
TheToyLAIModel
is available from the examples folder, and is a simple exponential growth model. It is used here for the sake of simplicity, but you can use any model you want, as long as it followsPlantSimEngine
interface.
Of course you can plot the outputs quite easily:
# ] add CairoMakie
using CairoMakie
lines(model[:degree_days_cu], model[:LAI], color=:green, axis=(ylabel="LAI (mยฒ mโปยฒ)", xlabel="Cumulated growing degree days since sowing (ยฐC)"))
Model coupling
Model coupling is done automatically by the package, and is based on the dependency graph between the models. To couple models, we just have to add them to the ModelList
. For example, let's couple the ToyLAIModel
with a model for light interception based on Beer's law:
# ] add PlantSimEngine, DataFrames, CSV
using PlantSimEngine, PlantMeteo, DataFrames, CSV
# Include the model definition from the examples folder:
include(joinpath(pkgdir(PlantSimEngine), "examples/ToyLAIModel.jl"))
include(joinpath(pkgdir(PlantSimEngine), "examples/Beer.jl"))
# Import the example meteorological data:
meteo_day = CSV.read(joinpath(pkgdir(PlantSimEngine), "examples/meteo_day.csv"), DataFrame, header=18)
# Define the list of models for coupling:
model = ModelList(
ToyLAIModel(),
Beer(0.6),
status=(degree_days_cu=cumsum(meteo_day[:, :degree_days]),), # Pass the cumulated degree-days as input to `ToyLAIModel`, this could also be done using another model
)
The ModelList
couples the models by automatically computing the dependency graph of the models. The resulting dependency graph is:
โญโโโโ Dependency graph โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โญโโโโ LAI_Dynamic โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ โ
โ โ โญโโโโ Main model โโโโโโโโโฎ โ โ
โ โ โ Process: LAI_Dynamic โ โ โ
โ โ โ Model: ToyLAIModel โ โ โ
โ โ โ Dep: nothing โ โ โ
โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ โ
โ โ โ โญโโโโ Soft-coupled model โโโโโโโโโโฎ โ โ
โ โ โ โ Process: light_interception โ โ โ
โ โ โโโโ Model: Beer โ โ โ
โ โ โ Dep: (LAI_Dynamic = (:LAI,),) โ โ โ
โ โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ โ
โ โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
# Run the simulation:
run!(model, meteo_day)
status(model)
Which returns:
TimeStepTable{Status{(:degree_days_cu, :LAI...}(365 x 3):
โญโโโโโโฌโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโฌโโโโโโโโโโโโฎ
โ Row โ degree_days_cu โ LAI โ aPPFD โ
โ โ Float64 โ Float64 โ Float64 โ
โโโโโโโผโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโค
โ 1 โ 0.0 โ 0.00554988 โ 0.0476221 โ
โ 2 โ 0.0 โ 0.00554988 โ 0.0260688 โ
โ 3 โ 0.0 โ 0.00554988 โ 0.0377774 โ
โ 4 โ 0.0 โ 0.00554988 โ 0.0468871 โ
โ 5 โ 0.0 โ 0.00554988 โ 0.0545266 โ
โ โฎ โ โฎ โ โฎ โ โฎ โ
โฐโโโโโโดโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโฏ
360 rows omitted
# Plot the results:
using CairoMakie
fig = Figure(resolution=(800, 600))
ax = Axis(fig[1, 1], ylabel="LAI (mยฒ mโปยฒ)")
lines!(ax, model[:degree_days_cu], model[:LAI], color=:mediumseagreen)
ax2 = Axis(fig[2, 1], xlabel="Cumulated growing degree days since sowing (ยฐC)", ylabel="aPPFD (mol mโปยฒ dโปยน)")
lines!(ax2, model[:degree_days_cu], model[:aPPFD], color=:firebrick1)
fig
Projects that use PlantSimEngine
Take a look at these projects that use PlantSimEngine:
Make it yours
The package is developed so anyone can easily implement plant/crop models, use it freely and as you want thanks to its MIT license.
If you develop such tools and it is not on the list yet, please make a PR or contact me so we can add it!
TO DO
- Look into locks for parallel computations over "independent" processes that can maybe call a model when both parents are being computed, so both are set to 0 and the model is never called