PhaseLookupValue

PhaseLookupValue defines a value or function that applies only within a specified phase range in a crop’s development. It is used as a child of PhaseLookup to provide values that change according to phenological stages.

Overview

This function enables conditional logic based on crop development stage. When the crop is between two specified stages—such as Emergence to FloralInitiation—PhaseLookupValue activates and returns the value of its child function. Outside this phase range, the function returns zero.

In APSIM NG, PhaseLookupValue is typically used under PhaseLookup to define phase-specific values for key processes like growth rates, stress responses, or developmental signals.

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:

This function inherits from the following parent 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
Phenology Phenology Link Provides current phenological stage information to determine if the crop is within the specified phase range.
Child Function IFunction Child, First Available Any function model that provides the value to return when the phase is active. Only the first child is used.
PhaseLookup PhaseLookup Parent (typical) Parent function that evaluates multiple PhaseLookupValue children to select the appropriate value based on current phase.

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 stage when activation begins
End string Name of the stage when activation ends

Read-Only Reportable Properties

Property Type Description
InPhase boolean true if current crop stage is within range

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

Event Purpose
Commencing Convert stage names to internal indices at the beginning of simulation

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 Range Initialization

At the beginning of the simulation (triggered by the Commencing event), the function converts the user-specified Start and End stage names into internal phenology indices:

  • startStageIndex = index corresponding to the Start stage name
  • endStageIndex = index corresponding to the End stage name

This conversion is performed once at initialization and cached for efficient evaluation during the simulation.

Value Calculation

During each simulation time step, the function evaluates whether the current phenological stage falls within the specified range and returns the appropriate value:

\[ V = \begin{cases} F_{\text{child}}(i), & \text{if } S_{\text{start}} \leq S_{\text{current}} \leq S_{\text{end}} \\ 0, & \text{otherwise} \end{cases} \]

where:

  • \(V\) is the returned value
  • \(F_{\text{child}}(i)\) is the value of the first child function (with optional array index \(i\))
  • \(S_{\text{start}}\) is the start stage index
  • \(S_{\text{current}}\) is the current phenological stage index
  • \(S_{\text{end}}\) is the end stage index

Important notes:

  • If Start or End stage names are not set (empty strings), the function throws an exception.
  • Only the first child function is evaluated, even if multiple children are present.
  • The function returns 0.0 if no child functions are defined or if the current stage is outside the specified range.
  • The phenology check uses the Between() method which includes both start and end stages (inclusive range).

User Interface

PhaseLookupValue is used as a child of a PhaseLookup node. To use it:

  1. Right-click on the PhaseLookup in the model tree.
  2. Select “Add Model…”.
  3. Choose “PhaseLookupValue”.
  4. Set Start and End crop stages in the property view, and add a child function such as Constant or MultiplyFunction.

Practical Example

Suppose you want to return a value of 1.0 during the vegetative phase and 0.5 during grain filling:

  • First PhaseLookupValue:
    • Start = “Emergence”, End = “FloralInitiation”
    • Child = Constant (1.0)
  • Second PhaseLookupValue:
    • Start = “FloralInitiation”, End = “Maturity”
    • Child = Constant (0.5)

Together, under a parent PhaseLookup, these values define different behavior for the crop across development. This approach could be used to model radiation use efficiency that decreases after floral initiation, or to adjust partitioning coefficients that change with developmental stage.

See Also