Phenology

The Phenology model simulates the developmental progression of a plant through a series of defined growth stages and phases. It provides the central mechanism for managing crop stage transitions and coordinates developmental timing across all plant organs and processes in APSIM Next Generation.

Overview

In APSIM NG, the Phenology model manages plant development by organizing the crop lifecycle into distinct sequential phases. Each phase represents a physiological developmental period (e.g., germination, emergence, vegetative growth, flowering, grain filling, maturity). The model tracks developmental progress through phases, triggers stage-specific events, and maintains accumulated thermal time from sowing and emergence.

  • A phase is a period of development with specific environmental responses (e.g., “Vegetative” phase may respond to photoperiod)
  • A stage is a discrete developmental milestone that marks transitions between phases (e.g., “Emergence”, “Flowering”)

Phase transitions are driven by environmental factors including:

  • Thermal time (accumulated temperature above base threshold)
  • Photoperiod (daylength sensitivity for certain phases)
  • Vernalization (cold temperature requirement for certain crops)
  • Specific dates (calendar-based completion for management scenarios)

The Phenology model acts as the master clock for plant development, coordinating timing signals with other components such as leaf expansion, stem elongation, grain development, and senescence processes. This temporal coordination ensures that developmental events occur in biologically realistic sequences and at appropriate rates given environmental conditions.

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:

The Phenology model inherits from the following classes:

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
Plant Plant Link, First Available Provides structural and lifecycle information for the plant.
ThermalTime IFunction Child, By Name Calculates accumulated temperature used for phase progression.
ZadokPMFWheat ZadokPMFWheat Link, Optional Provides Zadok stage number for wheat crops.
Age Age Child, By Name, Optional Tracks plant age in years for perennial species.
Structure IStructure Field Provides access to plant structural information and child components.

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

No configurable properties are available for this model.

Read-Only Reportable Properties

Property Type Description
StageNames List<string> List of stage names in phenology progression
StageCodes List<int> List of numerical stage codes corresponding to each stage
AccumulatedTT double Thermal time accumulated since sowing (°Cd)
AccumulatedEmergedTT double Thermal time accumulated since emergence (°Cd)
Emerged bool Whether the plant has emerged from soil surface
Stage double One-based stage number with fractional completion
CurrentPhaseName string Name of the current phenological phase
CurrentStageName string Name of the current stage (only on first day of stage)
FractionInCurrentPhase double Proportion completed in current phase (0 to 1)
CurrentPhase IPhase The current phase object providing access to phase-specific properties
Zadok double Current Zadok stage number for wheat (0 if not applicable)

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 Phenology model listens for from other parts of the simulation:

Event Purpose
Commencing Initializes phenology, refreshes phase list, and clears state variables
PlantSowing Resets phenology and initializes the first phase at sowing
DoPhenology Core daily timestep to update phenological development and manage phase transitions
StartOfDay Clears temporary stage-tracking flags for new day
Harvesting Sets phenology directly to final phase (maturity)
PlantEnding Clears internal state when plant lifecycle ends
Pruning Event handler for pruning events (currently no action)

Events Raised

Event Purpose
PhaseChanged Indicates a new phase has started, providing the stage name
PlantEmerged Signals that the emergence phase has been completed
StageWasReset Signals a manual reset of stage via SetToStage(), providing the new stage number
PostPhenology Raised after daily phenological timestep completes, allowing dependent processes to respond

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.

Initialization and Setup

At the Commencing event, the Phenology model:

  1. Refreshes the list of phases from child components
  2. Clears all state variables including stage number, accumulated thermal time, and phase tracking

At PlantSowing, the model:

  1. Clears state variables and resets to initial conditions
  2. Marks the first stage (start of first phase) as having been passed today
  3. Initializes the current phase index to 0

Daily Phenological Development

The core phenological progression occurs during the DoPhenology event. This process only executes when the plant is alive. The algorithm proceeds as follows:

Step 1: Validate Thermal Time

The model first checks that thermal time is available and positive. If thermal time is negative, an error is raised as this indicates an issue with the ThermalTime function configuration.

Step 2: Progress Through Current Phase

The current phase’s DoTimeStep method is called, which:

  • Calculates phase-specific developmental progress based on environmental conditions
  • Returns true if the phase is complete and should transition to the next phase
  • Provides a proportion of the day to use for thermal time accumulation

Step 3: Handle Phase Transitions

When a phase completes:

  1. The completed stage name is added to the list of stages passed today
  2. The phase index increments to move to the next phase (unless already incremented by a GotoPhase)
  3. If the plant has just emerged, the PlantEmerged event is raised
  4. The PhaseChanged event is raised with the new stage name
  5. If the new phase is a GotoPhase, it immediately executes its stage-setting logic
  6. The new phase’s DoTimeStep is called to check if it also completes on the same day

This process repeats until a phase does not complete within the same timestep.

Step 4: Update Accumulated Thermal Time

Unless the stage was manually set via SetToStage today:

  • Total accumulated thermal time increases by today’s thermal time value
  • If the plant has emerged, emerged thermal time also increases

Step 5: Raise Post-Phenology Event

After all phenological calculations are complete, the PostPhenology event is raised, allowing other components to respond to the updated developmental state.

Stage Manipulation

SetToStage Method

The SetToStage method allows manual control of phenological development, either moving forward or backward through stages. This is used for management actions (harvest, cutting) or special phase logic (GotoPhase).

The method accepts either a stage name (string) or stage number (double) and performs different operations depending on direction:

Rewinding (Moving to Earlier Stage):

When setting to an earlier stage:

  1. Identifies all phases between the current and target stages
  2. Validates that each phase can be rewound (only specific phase types support rewinding)
  3. For each phase being rewound:
    • Subtracts the phase’s accumulated thermal time from total and emerged thermal time
    • Calls the phase’s ResetPhase method to clear internal state
  4. Ensures accumulated thermal time values remain non-negative

Fast-Forwarding (Moving to Later Stage):

When setting to a later stage:

  1. Identifies all phases between current and target stages
  2. For each phase to skip:
    • Adds the stage name to stages passed today
    • If the phase has a target, adds the remaining thermal time to reach the target
    • Raises PlantEmerged event if crossing emergence
    • Raises PhaseChanged event for each stage transition
  3. Sets the target phase’s progress to the appropriate fraction

Fractional Stage Setting:

When setting to a fractional stage (e.g., 3.5), the model:

  • Moves to the phase corresponding to the integer part (phase 3)
  • Sets progress within that phase to the fractional part (50% through phase 3)

The StageWasReset event is raised at the conclusion to signal that a manual stage change occurred.

Phase Completion by Date

For phases that implement IPhaseWithSetableCompletionDate, the model can force completion on a specific calendar date rather than using the phase’s normal progression mechanism. This is managed through:

  1. SetPhaseCompletionDate(completionDate, phaseName): Sets the target date for a named phase
  2. FractionComplete(): Calculates fractional progress based on days elapsed vs total days to completion date
  3. checkIfCompletionDate(): Determines if today matches the completion date

This mechanism is particularly useful for:

  • Matching observed phenological dates in calibration
  • Management overrides for specific calendar-based events
  • Ensuring germination occurs before a set emergence date

Utility Methods

The Phenology model provides several utility methods for querying developmental state:

  • OnStartDayOf(stageName): Returns true if today is the first day of the specified stage
  • InPhase(phaseName): Returns true if currently in the named phase
  • Between(start, end): Returns true if current phase is between start and end stages (inclusive)
  • Beyond(start): Returns true if current phase is at or past the specified start stage
  • PhaseStartingWith(start): Returns the phase object that begins with the specified stage name
  • IndexFromPhaseName(name): Returns the array index of a phase by name
  • StartStagePhaseIndex(stageName): Returns the index of the phase starting with the specified stage
  • EndStagePhaseIndex(stageName): Returns the index of the phase ending with the specified stage

Public Methods

The Phenology model exposes several public methods for interacting with phenological development:

Method Description
SetToStage(string newStage) Moves the crop to a specific development stage by name (e.g., “Flowering”)
SetToStage(double newStage) Moves the crop to a specific development stage by number (e.g., 3.5)
SetToEndStage() Sets phenology to the final stage (typically used at harvest)
SetAge(double newAge) Sets the age in years for perennial crops (if Age component present)
OnStartDayOf(string stageName) Returns true if today is the first day of the specified stage
InPhase(string phaseName) Returns true if currently in the named phase
Between(string start, string end) Returns true if between two stages (inclusive)
Beyond(string start) Returns true if at or past the specified start stage
PhaseStartingWith(string start) Returns the phase object beginning with specified stage
IndexFromPhaseName(string name) Returns array index of a phase by name
StartStagePhaseIndex(string stageName) Returns index of phase starting with specified stage
EndStagePhaseIndex(string stageName) Returns index of phase ending with specified stage
SetPhaseCompletionDate(string completionDate, string phaseName) Forces a phase to complete on a specific calendar date
GetPhaseTable() Returns a DataTable listing all phases with their start/end stages

User Interface

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

Required Child Components

The Phenology model requires the following child components:

  • ThermalTime: An IFunction that calculates daily thermal time accumulation. This is referenced by name and must be present.
  • Phase sequence: A series of phase components (implementing IPhase) that define the developmental progression. Phases must be added in sequential order.

Optional Child Components

  • ZadokPMFWheat: Provides Zadok stage numbering for wheat crops
  • Age: Tracks plant age for perennial species

Phases

A list of available phenology phases that can be added as children to the Phenology model:

Table 1: Phenology Phases Available
Phase Description
EmergingPhase The EmergingPhase represents a phenological sub-phase within a plant’s developmental timeline, res …
EndPhase EndPhase is the final phase in a crop’s phenological development …
GenericPhase The GenericPhase is a phenological phase used within a plant’s developmental sequence …
GerminatingPhase The GerminatingPhase represents a phenological sub-phase within a plant’s developmental timeline, …
LeafAppearancePhase The LeafAppearancePhase represents a developmental phase in a plant’s life cycle …
SimpleLeafAppearancePhase The SimpleLeafAppearancePhase represents a phenological phase where the duration of the phase is d …
VernalisationPhase The VernalisationPhase defines a phenological development phase that is completed when vernalisati …

See Also