SimpleLeafAppearancePhase

The SimpleLeafAppearancePhase represents a phenological phase where the duration of the phase is determined by the number of new leaves appearing to match final leaf number.

Overview

SimpleLeafAppearancePhase models a phenological phase that progresses based on leaf appearance rate and final leaf number. It is a simplified approach to tracking phenological development in crops, where the phase completes when the current number of leaves reaches the target leaf number. This phase is particularly useful for crops where leaf appearance is a key developmental milestone, such as cereals and grasses.

The phase progresses from a specified Start stage to a specified End stage. The duration is controlled by the difference between the target leaf number and the current leaf number. Once initialized, the target for completion is fixed based on the initial leaf count, meaning subsequent changes to the final leaf number do not affect when this phase will complete.

Model Structure

This section describes how this model is positioned within the APSIM framework. It outlines the broader structural and computational components that define its role and interactions in the simulation system.

This model inherits structural and functional behaviour from the following core APSIM components:

Connections to Other Components

This section describes how the model interacts with other components in the APSIM Next Generation framework.
These connections allow the model to exchange information—such as environmental conditions, developmental stage, or physiological responses—with other parts of the simulation system. For a general overview of how model components are connected in APSIM, see the Connections Overview.

Component	Model	Connection Type	Description
TargetLeafNumber	IFunction	Child, By Name	Provides the target final leaf number for the phase.
CurrentLeafNumber	IFunction	Child, By Name	Returns the current number of leaves that have appeared.
Clock	IClock	Link	Provides the current simulation date and time.

Model Variables

This section lists the key variables that describe or control the behaviour of this component. Some variables can be adjusted by the user to modify how the model behaves (configurable), while others are calculated internally and can be viewed as model outputs (reportable). For a general explanation of variable types and how they are used within the APSIM Next Generation framework, see the Model Variables Overview.

Configurable and Reportable Properties

Property	Type	Description
Start	string	Name of the phenological stage where this phase starts
End	string	Name of the phenological stage where this phase ends
IsEmerged	bool	Whether the phase starts after emergence (default: true)

Read-Only Reportable Properties

Property	Type	Description
ProgressThroughPhase	double	Accumulated units of progress through this phase (leaves appeared since start)
FractionComplete	double	The fraction of the phase that has been completed (0 to 1)
DateToProgress	string	Optional external completion date. If set, the phase ignores its normal mechanism and waits for this date

Events

This section describes the events associated with this component. Events are signals or notifications that indicate when a particular process occurs within the simulation, or when a component needs to respond to a change in another part of the system. Some events are listened for by this component to trigger its processes, while others are raised to inform other components about changes. For a general overview of how APSIM Next Generation uses events to coordinate processes between components, see the Events Overview.

Events Listened For

These are signals or notifications that the function listens for from other parts of the simulation:

Event	Purpose
Commencing	Reset the internal state before the simulation starts

Events Raised to

No events are raised by this function.

Processes and Algorithms

This section describes the scientific processes and algorithms represented by this component. Each process corresponds to a biological, physical, or chemical mechanism simulated during a model time step. Where appropriate, equations or conceptual summaries are provided to explain how the process operates within the APSIM Next Generation framework.

Phase Initialization

When the phase first becomes active (i.e., on the first timestep after entering this phase), the model records the current leaf number as the baseline:

\[ L_{\text{start}} = L_{\text{current}} \]

where \(L_{\text{start}}\) is the leaf number at the start of the phase and \(L_{\text{current}}\) is the current leaf number provided by the CurrentLeafNumber function.

The target number of leaves required to complete the phase is then calculated as:

\[ L_{\text{target}} = L_{\text{final}} - L_{\text{start}} \]

where \(L_{\text{final}}\) is the final target leaf number provided by the TargetLeafNumber function.

This initialization ensures that the phase completion target is locked in at the start of the phase. Any subsequent changes to the final leaf number will not affect the completion criteria for this phase.

Daily Progress Calculation

On each timestep, the model calculates the progress through the phase as:

\[ P = L_{\text{current}} - L_{\text{start}} \]

where \(P\) is the progress through the phase (in leaves).

The fraction complete is then calculated as:

\[ F = \frac{P}{L_{\text{target}}} \]

where \(F\) is the fraction of the phase completed (ranging from 0 to 1).

Phase Completion

The phase is considered complete when the fraction complete reaches or exceeds 1.0 (i.e., when \(F \geq 1\)). At this point:

The model sets the proportion of the day used to a very small value (0.00001), assuming most of the day’s thermal time was used to reach the final leaf
The phase signals that it is ready to proceed to the next phase
The phenology model advances to the next phase specified by the End property

External Date Override

If an external model sets the DateToProgress property, the phase will ignore its normal leaf-based progression mechanism and instead complete on the specified date. This allows for external control of phase timing when needed for specific experimental or management scenarios.

User Interface

SimpleLeafAppearancePhase can be added as a child of a Phenology node in the model tree. Right-click the parent node, select “Add Model…”, and search for SimpleLeafAppearancePhase in the Filter Box.