flowchart LR accTitle: Biology and population dynamics in plant accDescr: A strategy converts plant state and surroundings into demographic rates. The demographic solver applies those rates to the population through time. A["Plant state<br/>and surroundings"] --> B["Strategy<br/>individual biology"] B --> C["Growth, mortality,<br/>and fecundity rates"] C --> D["Demographic solver<br/>population change"] D --> E["Patch structure<br/>through time"]
The big picture
theory · start here
plant is an R package for modelling how plants grow and compete within forest patches. Rather than simulating every tree as an independent object, its main solver describes a population by the distribution of plant sizes and follows how that distribution changes through growth, mortality, and recruitment.
The biological details are supplied by a strategy. A strategy determines how an individual plant responds to its size and surroundings: how quickly it grows, how likely it is to die, how many seeds it produces, and how it affects its competitors. The population solver then applies those rates across all the plants in a patch.
This page introduces that structure without equations. Most examples use FF16, the default trait-based strategy. The same demographic machinery also supports strategies with different biology, including TF24, which adds explicit plant hydraulics, and K93, which represents size and competition differently.
What goes into the model
A plant simulation combines several choices:
| Component | What you provide | What it controls |
|---|---|---|
| Strategy | A model such as FF16, TF24, or K93 | How individual plants grow, reproduce, die, and affect competitors |
| Traits and parameters | Values describing the simulated plants | Differences among plant strategies |
| External environment | For example, above-canopy light; TF24 can also use rainfall and atmospheric drivers | Conditions experienced by the plants |
| Seed input | A birth rate for each strategy | Recruitment into the patch |
| Disturbance regime | The duration and age weighting of patches | How a patch trajectory is scaled up to a landscape |
These inputs are specified by the user. What is not specified directly is the resulting stand structure. Plant sizes, population densities, canopy structure, self-thinning, and changes in community composition arise from the simulated growth, death, recruitment, and competition.
Biology and population dynamics
It helps to separate two parts of the model.
The strategy contains the biology. Given the state of a plant and its environmental and competitive conditions, it returns instantaneous rates of growth, mortality, and fecundity. Depending on the strategy, this calculation may include photosynthesis, tissue turnover, carbon allocation, hydraulics, or phenomenological relationships fitted directly to size and competition.
The demographic solver keeps track of how those individual rates change the population. It integrates growth and mortality through time, introduces new recruits, and updates the competitive environment as the population changes. The solver does not need to know how photosynthesis or hydraulics were calculated; it only needs the rates supplied by the strategy.
This separation is central to plant. Changing the strategy changes the individual biology, while leaving the size-structured demographic machinery in place.
The FF16 example: traits affect many processes
In the default FF16 workflow, a strategy is commonly specified by a small set of functional traits. These are measurable plant properties that affect several parts of the model at once.
| Trait | Symbol | Contrast represented in FF16 |
|---|---|---|
| Leaf mass per area (LMA) | \(\phi\) | Thin, inexpensive, short-lived leaves versus denser, longer-lived leaves |
| Wood density | \(\rho\) | Less construction-expensive wood versus denser, more construction-expensive wood |
| Seed mass | \(\omega\) | Many small seeds versus fewer, better-provisioned seeds |
| Maximum height | \(H_{\rm mat}\) | Shorter understorey plants versus taller canopy plants |
Changing one of these traits can change several physiological parameters. For example, LMA affects leaf construction cost, turnover, and respiration. Leaf nitrogen per area, which can also be supplied to the hyper-parameterisation, controls the photosynthetic response. plant uses a mapping from these input values to the lower-level physiological parameters needed by FF16. This mapping is called a hyper-parameterisation and is described in the Strategies and traits guide.
Wood density also changes construction costs and respiration per unit mass. Although the hyper-parameterisation can link wood density to mortality and sapwood turnover, those two relationships are switched off in the current default settings. Denser wood should therefore not automatically be interpreted as more durable in a default FF16 run.
This trait-based parameterisation is an important use of plant, but it is not the definition of a strategy. More generally, a strategy is the complete set of functions and parameters that produces a plant’s demographic rates. K93, for example, uses direct relationships between stem diameter, competition, growth, mortality, and fecundity rather than the FF16 trait-based carbon model.
The FF16 carbon balance
In FF16, growth and seed production are derived from net biomass production. The plant gains carbon through photosynthesis and loses carbon through tissue respiration and turnover. The remaining production can be allocated to new growth or reproduction.
flowchart LR accTitle: Carbon balance in the FF16 strategy accDescr: Photosynthesis supplies carbon. Respiration and tissue turnover reduce it. Remaining biomass production is allocated between growth and seed production, while low production can increase one component of mortality. L["Light captured<br/>by leaves"] --> P["Photosynthesis"] P --> B["Net biomass production"] R["Respiration and<br/>tissue turnover"] -->|"subtracted"| B B --> G["Growth"] B --> F["Seed production"] B -.-> D["Growth-dependent<br/>mortality"]
Young plants allocate most of their production to growth. As a plant approaches its maximum height, a larger share is allocated to reproduction. Low production per unit leaf area also increases the growth-dependent component of mortality. FF16 includes a separate background mortality component that does not depend on current production.
The FF16 model page gives the full carbon-allocation model. The Assimilation and hydraulics page explains the leaf-level calculations used by the hydraulically explicit strategies.
From an individual to a landscape
The ecological model is organised at three scales: individuals, patches, and the metacommunity. Nodes are not a fourth ecological scale. They are the numerical objects that the solver uses to represent groups of similar plants within a patch.
flowchart LR accTitle: Ecological scales and their numerical representation in plant accDescr: Similar individuals are grouped into cohorts represented numerically by nodes. Nodes describe a size-structured population within one patch. Patch states at different ages are weighted together to represent the landscape-scale metacommunity. I["Individuals<br/>biological plants"] --> C["Cohorts<br/>same strategy and recruitment time"] C -. "represented by" .-> N["Nodes<br/>numerical objects"] N --> P["Patch<br/>one local competing population"] P --> M["Metacommunity<br/>implicit landscape representation"]
The distinction can be summarised as follows:
| Term | What it is | What makes another one different? |
|---|---|---|
| Node | One numerical representation of a cohort within a patch | A different strategy or recruitment time produces a different cohort and therefore a different node |
| Patch | One local community followed through time after disturbance | A different time since disturbance gives a different patch age and community state |
| Metacommunity | The landscape represented by patches of different ages, connected through a shared seed pool | It combines patch-level states rather than adding more nodes to a single patch |
Here is a concrete way to picture the nesting. Consider a patch that is 40 years old. It contains plants that recruited at different times during those 40 years. For each strategy, the solver uses nodes to represent these cohorts: an early node might represent a small number of large survivors, while a recent node might represent many small recruits. Together, all the nodes describe the current population in that one patch.
Now zoom out to the landscape. Some patches were disturbed recently and are young; others have developed for decades. The metacommunity combines the modelled states of these different patch ages, weighting each age by how common it is. This is an implicit representation: the deterministic solver does not create a separate object for every physical patch or for the metacommunity. Instead, one patch trajectory supplies the community state at each possible patch age. Thus, nodes are combined to describe a patch, while patch ages are combined to describe the metacommunity.
Individual
An individual is one biological plant governed by a strategy. Its state includes a size coordinate and, for some strategies, additional physiological variables. FF16, TF24, and TF24f use height as the main size coordinate. K93 uses stem diameter.
One implementation detail can otherwise be confusing when reading K93 output. The shared solver calls its first size state height for every strategy, so K93’s stem diameter is stored in a column named height, even though its biological meaning and units are DBH in centimetres.
The strategy uses that state and the plant’s surroundings to calculate growth, mortality, fecundity, and its contribution to competition.
Patch
A patch is a local population of competing plants. The deterministic size-structured solver does not store every literal individual. It represents the population by a size distribution: the density of plants at each size, for each strategy, at a given patch age.
The numerical method follows a finite set of nodes along this distribution. Each node belongs to one strategy and represents plants that recruited at a particular patch age, so those plants follow the same deterministic trajectory. As the patch develops, the node’s position records the cohort’s changing size, while its density records how many plants from that cohort remain per unit area. New nodes are introduced to represent continuing recruitment.
The words individual, cohort, and node therefore refer to related but different things:
- an individual is one biological plant;
- a cohort is a group of plants sharing a recruitment time and strategy;
- a node is the numerical point used to represent that cohort and sample the continuous size distribution.
Following nodes as they grow is an application of the method of characteristics. The node-spacing algorithm chooses enough node introduction times to approximate the distribution accurately without making the calculation unnecessarily expensive.
Metacommunity
At the landscape scale, plant represents a forest as a collection of patches with different ages since their last disturbance. Seed dispersal connects these patches, producing a shared seed pool for each strategy.
The prefix meta- signals that this is a community of communities: each patch contains its own local plant community, and the metacommunity connects those local communities at the landscape scale. In the standard model, this connection occurs through seeds rather than through nodes. A node never moves from one patch to another; it is only part of the numerical description of one patch trajectory.
Under the standard metacommunity assumptions, patches begin from the same empty state after disturbance, receive the same constant seed rain, and differ only in age. In that setting, one simulated patch trajectory can represent all patch ages. Patch-level results are averaged using the frequency of patches at each age to obtain landscape-level quantities. Demographic equilibrium adds a further condition: the seed rain must be consistent with the seeds produced across the metacommunity.
Constant seed rain is the usual assumption for the demographic-equilibrium calculation, not a restriction of the solver. plant can also accept birth rates that vary with patch age when a different ecological scenario requires them.
This reduction depends on those assumptions. It is not a general claim that one physical forest patch represents every heterogeneous landscape.
Competition within a patch
FF16, TF24, and TF24f all include competition for light. Plants add leaf area to the canopy. The combined leaf area determines a vertical profile of canopy openness, and that profile affects later photosynthesis, growth, reproduction, and survival.
flowchart LR accTitle: Feedback between plants and the canopy light profile accDescr: Plant leaf area changes the canopy light profile. The light profile changes demographic rates, which alter the size distribution and therefore future leaf area. A["Plant leaf area"] --> B["Vertical canopy<br/>light profile"] B --> C["Growth, mortality,<br/>and fecundity"] C --> D["Population size<br/>distribution"] D --> A
All plants in the patch contribute to one shared canopy-light profile, but they do not all receive the same amount of light. The light available to a plant depends on its height and on how its leaves are distributed through its crown.
This competition is strongly size-asymmetric. Taller plants usually shade a larger fraction of a shorter plant’s crown than the shorter plant shades of the taller plant’s crown. As a result, small initial differences can grow through time. The feedback can produce self-thinning, canopy stratification, and changes in which strategies dominate as a patch ages.
TF24 and TF24f add another shared resource. Plants take up water from the same soil profile, so their density-weighted root uptake changes soil moisture for the rest of the patch. The updated soil-water state then feeds back into plant hydraulics and carbon gain.
K93 uses a different competitive environment. Its demographic rates depend on stem diameter and the cumulative basal area of larger neighbours rather than an explicit canopy-light profile. This is an example of how the demographic solver can support different biological models of competition.
Disturbance and patch age
Disturbance resets a patch and begins a new patch trajectory. In the standard model, this is a stand-replacing event: all plants are removed and the patch starts empty. At any one time, the landscape contains young, intermediate, and old patches.
The default plant parameters use a Weibull disturbance regime with a fixed shape. The user-facing max_patch_lifetime parameter sets the duration of the simulated patch and parameterises this regime; its mean disturbance interval is a derived quantity. The model uses the resulting patch-age distribution to weight outputs from different points along the patch trajectory.
For example, suppose biomass in a simulated patch rises as the stand develops. Landscape-average biomass is not the biomass at one chosen patch age. It is the average across the complete trajectory, weighted by how common patches of each age are under the disturbance regime.
The size-structured PDE page develops this age weighting formally. The Emergent properties guide shows how to calculate landscape summaries from model output.
Seed input and demographic equilibrium
Each strategy has a birth rate describing the arrival of seeds into a patch. Given these birth rates, run_scm() simulates the patch and reports offspring production and the net reproduction ratio for each strategy.
At demographic equilibrium, the seed input must be consistent with the seed output from the metacommunity. For each resident strategy, one incoming seed must produce one successful dispersing seed on average. In terms of the net reproduction ratio, equilibrium requires a value of one.
This is a fixed-point problem in the birth rates, but it is separate from running a patch once. The current plant API does not expose a general function that automatically finds equilibrium birth rates. A user must supply birth rates or perform an outer search based on the reported reproduction ratios.
The option run_scm(..., refine_schedule = TRUE) has a different purpose: it adaptively refines the numerical node-introduction schedule. It improves the accuracy with which the size distribution is integrated; it does not adjust the birth rates.
What can be learned from a simulation?
Different questions use different parts of the model.
Patch development
A run with supplied birth rates describes how a patch changes through time. Its outputs can be used to examine:
- plant height or diameter distributions;
- population density and self-thinning;
- canopy structure and light availability;
- growth, mortality, and fecundity;
- biomass and its allocation among tissues;
- changes in the relative abundance of strategies.
These are transient patch dynamics. They do not require solving for demographic equilibrium first.
Landscape averages
Patch outputs can be integrated over the patch-age distribution to estimate landscape-level means, such as mean biomass, density, or productivity across a disturbance mosaic.
Evolutionary and community questions
If a resident community is at demographic equilibrium, plant can also be used to ask whether a rare alternative strategy could invade. The rare strategy is evaluated in the environment created by the residents without being allowed to alter that environment itself.
Its basic reproduction ratio is the expected number of dispersing offspring produced per incoming seed. A value greater than one indicates that the rare strategy can increase; a value below one indicates that it cannot invade.
Repeating this calculation across trait values can identify several kinds of evolutionary outcome. Some resident strategies are uninvadable evolutionary stable strategies. Other trait values can be evolutionary branching points, and community assembly can produce several coexisting strategies. The Adaptive dynamics section explains these distinctions and the assumptions behind the analysis.
A basic plant workflow
For an FF16 patch, the main code path is short:
library(plant)
p <- scm_base_parameters("FF16")
p <- add_strategies(
p,
trait_matrix(0.0825, "lma"),
birth_rate = 20
)
result <- run_scm(p, collect = TRUE)
result <- expand_state(result)This example:
- creates the default FF16 parameters;
- adds one strategy with a specified LMA and birth rate;
- simulates the patch through time;
- collects and expands the state variables into analysis-ready output.
run_scm() constructs the matching environment when one is not supplied. To configure an environment explicitly, use a typed constructor such as Environment("FF16") or Environment("TF24"). The TF24 environment includes default soil-water and atmospheric conditions, which can be changed for a particular scenario.
| Task | Main plant interface |
Detailed guide |
|---|---|---|
| Choose a strategy and parameters | scm_base_parameters("FF16") |
Strategies and traits |
| Add trait values and seed input | trait_matrix(), add_strategies() |
Strategies and traits |
| Configure external drivers | Environment("FF16") or Environment("TF24") |
Extrinsic drivers |
| Simulate a patch | run_scm() |
Patch dynamics |
| Refine numerical node spacing | run_scm(..., refine_schedule = TRUE) |
Node-spacing algorithm |
| Collect and expand outputs | collect = TRUE, expand_state() |
Example analysis |
Important assumptions and limits
Every model simplifies. The main assumptions to keep in mind when interpreting the standard deterministic plant workflow are:
- The population is represented as a continuous size distribution. This is appropriate for large populations;
plantalso contains a stochastic solver for questions about finite populations and demographic randomness. - FF16 represents competition through canopy light. TF24 and TF24f add a shared soil-water balance, while K93 uses the basal area of larger neighbours. None of these strategies represents every possible interaction among plants.
- The standard metacommunity has well-mixed seed dispersal, identical empty patches after stand-replacing disturbance, and an equilibrium distribution of patch ages.
- Strategy equations and parameters are hypotheses about plant biology. Stand structure emerges from those assumptions; it is not assumption-free.
- A simulation produces conditional model output, not a calibrated forecast with uncertainty bounds.
plantdoes not currently provide a complete calibration, uncertainty-propagation, or forecasting workflow.
Glossary
| Term | Meaning here |
|---|---|
| Strategy | The functions and parameters that translate a plant’s state and surroundings into growth, mortality, fecundity, and competition effects |
| Trait | A measurable plant property used to distinguish strategies or derive physiological parameters |
| Individual | One biological plant governed by a strategy |
| Cohort | Plants with the same strategy and recruitment time following the same deterministic trajectory |
| Node | A numerical point representing a cohort and sampling the continuous size distribution |
| Patch | A local population of competing plants followed from disturbance onward |
| Size distribution | Plant density across the model’s size coordinate: height for FF16/TF24 or stem diameter for K93 (stored under the generic state name height) |
| Competitive environment | The shared quantity through which plants interact, such as the canopy-light profile or basal area of larger neighbours |
| Metacommunity | A landscape of patches of different ages connected by seed dispersal |
| Birth rate / seed rain | The rate at which seeds of a strategy arrive in a patch |
| Demographic equilibrium | A state in which resident seed input and seed output are self-consistent, giving a net reproduction ratio of one |
| Invasion criterion | Whether a rare strategy produces more than one dispersing offspring per incoming seed in the resident environment |
Where to go next
Choose the path that matches your question:
- I want to run the model. Start with Your first individual, then continue to Patch dynamics.
- I want to understand the mathematics. Read The maths, gently, followed by The maths, worked through and the full size-structured PDE.
- I want to understand a biological strategy. See the models overview, then the pages for FF16, K93, or TF24.
- I want to study evolution or community assembly. Continue to Adaptive dynamics.