AccumulateFunction

AccumulateFunction sums the daily values from one or more child functions over a defined period between crop growth stages. It is commonly used to accumulate thermal time, biomass production, nutrient uptake, or water use during specific crop phases (e.g., from emergence to flowering). The function can reset at specified stages and adjust for management events such as harvest, cutting, grazing, or pruning.

Overview

AccumulateFunction tracks cumulative values that are essential for understanding crop development and resource use over time. It operates by evaluating child functions daily and adding their outputs to a running total, but only during a user-specified window of crop development.

This function is particularly valuable for: - Calculating total thermal time accumulated during a growth phase - Tracking cumulative biomass or nutrient demand - Monitoring water or radiation use efficiency over developmental periods - Simulating the impact of management practices (cutting, grazing) on accumulated reserves

In APSIM Next Generation, AccumulateFunction integrates with the crop phenology system to ensure accumulation occurs only between relevant developmental stages. It responds to crop lifecycle events, making it flexible for diverse cropping systems and management scenarios.

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:

  • Model - Base class for all APSIM models
  • IFunction - Provides the Value() method to return accumulated value
  • IStructureDependency - Enables discovery of child functions in the model tree

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 growth stage indices to determine when accumulation occurs
Child Functions IFunction Children One or more functions whose daily values are summed

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
StartStageName string Crop development stage name to begin accumulation (e.g., “Emergence”)
EndStageName string Crop development stage name to end accumulation (e.g., “Flowering”)
ResetStageName string Optional stage name to reset accumulated value to zero
FractionRemovedOnCut double Fraction of accumulated value removed when crop is cut (0-1)
FractionRemovedOnHarvest double Fraction of accumulated value removed at harvest (0-1)
FractionRemovedOnGraze double Fraction of accumulated value removed when grazed (0-1)
FractionRemovedOnPrune double Fraction of accumulated value removed when pruned (0-1)

Read-Only Reportable Properties

Property Type Description
Value double Current accumulated value (sum of all daily increments within the accumulation period)

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

At the start of simulation (Commencing event): 1. Accumulated value is set to zero 2. Start and end stage indices are determined from the phenology model based on StartStageName and EndStageName

Daily Accumulation

Each day after phenology calculations (PostPhenology event), the function checks if the current crop stage is between the start and end stages. If so:

  1. Each child function is evaluated to obtain its current daily value

  2. All child function values are summed: \[ \Delta V_{\text{day}} = \sum_{i=1}^{n} f_i(t) \] where \(f_i(t)\) is the value of child function \(i\) on day \(t\), and \(n\) is the number of child functions.

  3. The daily increment is added to the running total: \[ V_{\text{accumulated}}(t) = V_{\text{accumulated}}(t-1) + \Delta V_{\text{day}} \]

Accumulation only occurs when the crop is within the specified phenological window.

Stage-Based Reset

When a phenology stage change occurs (PhaseChanged event), if the new stage matches ResetStageName, the accumulated value resets: \[ V_{\text{accumulated}} = 0 \quad \text{when stage = ResetStageName} \]

This allows restarting accumulation at key developmental transitions.

Management Event Adjustments

The function responds to crop management events by reducing the accumulated value according to specified fractions:

Cutting (Cutting event): \[ V_{\text{accumulated}} = V_{\text{accumulated}} \times (1 - \text{FractionRemovedOnCut}) \]

Harvesting (PostHarvesting event): \[ V_{\text{accumulated}} = V_{\text{accumulated}} \times (1 - \text{FractionRemovedOnHarvest}) \]

Grazing (Grazing event): \[ V_{\text{accumulated}} = V_{\text{accumulated}} \times (1 - \text{FractionRemovedOnGraze}) \]

Pruning (Pruning event): \[ V_{\text{accumulated}} = V_{\text{accumulated}} \times (1 - \text{FractionRemovedOnPrune}) \]

Crop Cycle End

At the end of the crop cycle (PlantEnding event), the accumulated value is reset to zero, preparing for a new crop cycle.

Events

Events Listened For

AccumulateFunction listens to the following simulation events:

Event Purpose
Commencing Initializes accumulated value to zero and determines stage indices for accumulation window
PostPhenology Daily evaluation and summation of child functions if within accumulation window
PhaseChanged Resets accumulated value to zero if current stage matches ResetStageName
Cutting Reduces accumulated value by FractionRemovedOnCut
PostHarvesting Reduces accumulated value by FractionRemovedOnHarvest
Grazing Reduces accumulated value by FractionRemovedOnGraze
Pruning Reduces accumulated value by FractionRemovedOnPrune
PlantEnding Resets accumulated value to zero at end of crop cycle

Events Raised

No events are raised by this function.

User Interface

AccumulateFunction can be added to the model tree by right-clicking on a parent node (typically within a crop Plant model) and selecting “Add Model…”. Search for “AccumulateFunction” in the Filter Box. The function is represented by the following icon in the user interface:

After adding AccumulateFunction, you must: 1. Configure StartStageName and EndStageName to define the accumulation window 2. Add one or more child functions that will be summed daily 3. Optionally set management response fractions and reset stage

Practical Example

Example 1: Accumulating Thermal Time

A common use case is to track cumulative thermal time between emergence and flowering to predict when a crop reaches maturity:

Configuration: - StartStageName: “Emergence” - EndStageName: “Flowering” - Child Function: A thermal time calculation function (e.g., daily growing degree days)

The AccumulateFunction will sum daily thermal time values, and the accumulated total can be reported or used by other components to determine crop development progress.

Example 2: Tracking Biomass with Grazing

For a grazed pasture, you might accumulate biomass production but remove a portion during grazing events:

Configuration: - StartStageName: “Emergence” - EndStageName: “EndOfSeason” - FractionRemovedOnGraze: 0.6 (60% of accumulated biomass removed during grazing) - Child Function: Daily biomass production function

This simulates realistic pasture growth and utilization patterns under grazing management.

See Also