XPalm is a process-based model for simulating oil palm (Elaeis guineensis) growth and development. The model simulates key physiological processes including:

• Phenology and development
• Carbon assimilation and allocation
• Water balance
• Reproductive organ development
• Yield components

Figure 1. Simplified diagram of the component models used in XPalm. The numbering is associated to the computational flow, from the first models to execute to the last.

XPalm implements a multiscale approach, modeling processes at different organizational levels:

Scene: Environment and canopy-level processes Plant: Whole palm processes Phytomer: Individual growth unit processes Organ: Leaf, internode and reproductive organ processes

The model uses a daily time step and requires standard meteorological inputs (temperature, radiation, rainfall...).

The model also includes a submodule VPalm to design palm tree mockups from a set of architectural parameters and allometric equations. It is designed to integrate smoothly with the physiological models from the package.

The model is implemented in the Julia programming language, which is a high-level, high-performance dynamic programming language for technical computing.

Here are some example outputs from the model, showing the evolution of variables at different scales:

Scene level:

Leaf area index (LAI) at the scene level over time:

Plant level:

Maintenance respiration (Rm), absorbed PPFD (aPPFD), biomass of bunches harvested, and leaf area at the plant level over time:

Leaf level:

Leaf area at the level of the individual leaf over time:

Soil level:

Fraction of transpirable soil water (FTSW) over time:

Install XPalm using Julia's package manager, typing ] in the Julia REPL (i.e. the console) to enter the Pkg REPL mode and then typing:

pkg> add XPalm

To use the package, type the following in the Julia REPL:

using XPalm

From the Julia REPL, load the package:

using XPalm

The easiest way to run the model is to use the template notebook provided by the package. To run the notebook, you need to install the Pluto package first by running ] add Pluto. Then, you can run the notebook using the following commands in the Julia REPL:

using Pluto, XPalm
XPalm.notebook("xpalm_notebook.jl")

This command will create a new Pluto notebook (named "xpalm_notebook.jl") in the current directory, and open it automatically for you.

Once closed, you can re-open this notebook by running the same command again. If the file already exists, it will be opened automatically.

Run a simple simulation using default parameters and meteorological data:

using XPalm, CSV, DataFrames
# Load example meteorological data
meteo = CSV.read(joinpath(dirname(dirname(pathof(XPalm))), "0-data/meteo.csv"), DataFrame)
# Run simulation
df = xpalm(meteo, DataFrame;
    vars = Dict("Scene" => (:lai,)), # Request LAI as output
)

!!! note You need to install the CSV and DataFrames packages to run the example above. You can install them by running ] add CSV DataFrames.

Customize palm parameters and request multiple outputs:

# Read the parameters from a YAML file (provided in the example folder of the package).
using YAML
parameters = YAML.load_file(joinpath(dirname(dirname(pathof(XPalm))), "examples/xpalm_parameters.yml"))
# Load example meteorological data
meteo = CSV.read(joinpath(dirname(dirname(pathof(XPalm))), "0-data/meteo.csv"), DataFrame)
# Create palm with custom parameters
p = XPalm.Palm(parameters=parameters)
# Run simulation with multiple outputs
results = xpalm(
    meteo,
    DataFrame,
    vars = Dict(
        "Scene" => (:lai,),
        "Plant" => (:leaf_area, :biomass_bunch_harvested),
        "Soil" => (:ftsw,)
    ),
    palm = p,
)

You can also import the parameters from a JSON file using the JSON package:

using JSON # You first need to install the JSON package by running `] add JSON`
params = open(joinpath(dirname(dirname(pathof(XPalm))), "examples/xpalm_parameters.json"), "r") do io
    JSON.parse(io; dicttype=Dict{String,Any}, inttype=Int64)
end

!!! note The configuration file must contain all the parameters required by the model. Template files are available from the examples folder.

The models are available from the Models submodule. To import all models, you can use the following command:

using XPalm
using XPalm.Models

The package provides an example script in the examples folder. To run it, you first have to place your working directory inside the folder, and then activate its environement by running ] activate ..

You can also find example applications in the Xpalm applications Github repository.

The package also includes a submodule VPalm that is an automaton that builds 3d mockups of palm plants from architectural parameters and allometric equations. It also integrates a biomechanical model to compute the leaf bending and torsion using the biomass of each leaf.

You can run VPalm simply by loading the submodule. Here is an example to load VPalm default parameters and build a palm tree with a multiscale architecture defined using the Multiscale Tree Graph format (MTG).

using XPalm
using XPalm.VPalm
# Load example parameters
file = joinpath(dirname(dirname(pathof(XPalm))), "test", "references", "vpalm-parameter_file.yml")
parameters = read_parameters(file)
mtg = build_mockup(parameters)
viz(mtg, color = :green)

using XPalm
using XPalm.VPalm
file = joinpath(dirname(dirname(pathof(XPalm))), "test", "references", "vpalm-parameter_file.yml")
parameters = read_parameters(file)
mtg = build_mockup(parameters; merge_scale=:leaflet)
traverse!(mtg) do node
    if symbol(node) == "Petiole"
        petiole_and_rachis_segments = descendants(node, symbol=["PetioleSegment", "RachisSegment"])
        colormap = cgrad([colorant"peachpuff4", colorant"blanchedalmond"], length(petiole_and_rachis_segments), scale=:log2)
        for (i, seg) in enumerate(petiole_and_rachis_segments)
            seg[:color_type] = colormap[i]
        end
    elseif symbol(node) == "Leaflet"
        node[:color_type] = :mediumseagreen
    elseif symbol(node) == "Leaf" # This will color the snags
        node[:color_type] = :peachpuff4
    end
end
f, ax, p = viz(mtg, color=:color_type)
save("palm_mockup.png", f, size=(1200, 800), px_per_unit=3, update=false)

Note that the MTG is built with the following scales: ["Plant", "Stem", "Phytomer", "Internode", "Leaf", "Petiole", "PetioleSegment", "Rachis", "RachisSegment", "Leaflet", "LeafletSegment"].

This work is supported by the PalmStudio research project, funded by the SMART Research Institute and CIRAD.