PhotoperiodFunction

The PhotoperiodFunction calculates the duration of daylight (photoperiod) in hours for a given day and location. It is essential for simulating plant development processes that depend on day length within the APSIM NG framework.

Overview

The Photoperiod function determines the number of daylight hours based on the latitude (from the weather file) and a specified twilight sun angle threshold. This function is crucial for models where photoperiod sensitivity affects growth, flowering, or other physiological processes. If a variable called ClimateControl.PhotoPeriod is found in the simulation, it will be used instead of the calculated value.

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
Weather IWeather Link Provides latitude and meteorological information for day length calculation.
Clock IClock Link Supplies the current day of year for the calculation.

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
Twilight double The sun angle (in degrees) below the horizon for defining daylight.

Read-Only Reportable Properties

Property Type Description
DayLength double The calculated duration of daylight (hours) for the current day and location.

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
DoWeather Triggers calculation of day length for the current day.

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.

Day Length Calculation

The function calculates day length using three possible sources, with the following priority:

Controlled Environment

If the simulation includes a ClimateControl.PhotoPeriod variable, this specified day length value is used directly, overriding all other calculations.

Specified Day Length in Weather File

If the weather file contains actual day length data, these values are used directly.

Calculated Day Length

When no predetermined photoperiod is available, the day length is calculated using an astronomical formula. This calculation estimates the duration of daylight (in hours) for a given day of year, latitude, and twilight sun angle.

The calculation uses the following approach:

Let:

  • \(D\) = day of year
  • \(\phi\) = latitude (degrees)
  • \(\theta\) = twilight sun angle (degrees below the horizon; e.g., \(-6\) for civil twilight)
  1. Convert angles to radians:
    • \(\phi_{rad} = \phi \times \frac{\pi}{180}\)
    • \(\theta_{rad} = \theta \times \frac{\pi}{180}\)
  2. Calculate solar declination:
    • \(\delta = 0.4093 \times \sin\left(0.0172 \times (D - 79.25)\right)\)
  3. Compute intermediate values:
    • \(a = \sin(\phi_{rad}) \times \sin(\delta)\)
    • \(b = \cos(\phi_{rad}) \times \cos(\delta)\)
    • \(x = \frac{\sin(\theta_{rad}) - a}{b}\)
    • Clamp \(x\) to the range \([-1, 1]\) to avoid domain errors.
  4. Calculate day length (hours):

\[ \text{DayLength} = 2 \times \arccos(x) \times \frac{24}{2\pi} \]

This formula accounts for the Earth’s tilt and the observer’s latitude, providing an accurate estimate of daylight hours for any day and location.

The calculation is performed on the DoWeather event, ensuring the photoperiod is updated daily based on the current date and location.

User Interface

PhotoperiodFunction can be added as a child of a parent function node (e.g., a model requiring day length) in the model tree. Right-click the parent node, select “Add Model…”, and search for PhotoperiodFunction in the Filter Box.

Practical Example

No practical example is available for this function.

See Also