Clock

The APSIM Clock is a central component of the APSIM simulation framework, responsible for managing the simulation time and orchestrating the sequence of events that occur during a simulation. It defines the start and end dates of the simulation and raises various events at specific times to allow different models to perform their calculations.

Overview

The Clock model defines the simulation’s start and end dates, controls the passage of time, and raises numerous events used to coordinate actions across models. It forms the central timing mechanism within the APSIM NG framework, driving the daily timestep loop.

Inputs

  • Start: The start date of the simulation with format YYYY-MM-DD (optional if weather data is available).
  • End: The end date of the simulation with format YYYY-MM-DD (optional if weather data is available).
  • Weather: If no explicit start/end dates are defined, the model will attempt to derive them from the associated weather model.

Methodology

If Start or End are not defined, the model looks for a weather model in the scope and adopts its StartDate or EndDate. The simulation begins on the resolved start date and continues day by day until the end date. Each day, the Clock publishes multiple events to signal simulation actions across components. These include daily updates, management actions, soil processes, plant growth, CLEM processes, and reporting.

  1. DoInitialSummary – Initial summary at the start.
  2. StartOfSimulation – Marks the simulation’s beginning.
  3. FinalInitialise – Final initialisation before the first day.
  4. StartOfFirstDay – First day setup.
  5. For each day (from StartDate to EndDate), the following events are raised in sequence (some only on specific days): DoCatchYesterday, DoWeather, DoDailyInitialisation, StartOfDay, StartOfMonth, StartOfYear, StartOfWeek, DoManagement, DoFertiliserApplications, DoPestDiseaseDamage, DoEnergyArbitration, DoSoilErosion, DoSoilWaterMovement, DoSoilTemperature, DoSolute, DoSurfaceOrganicMatterPotentialDecomposition, DoSoilOrganicMatter, DoSurfaceOrganicMatterDecomposition, DoUpdateWaterDemand, DoDCAPST, DoWaterArbitration, PrePhenology, DoPhenology, DoPotentialPlantGrowth, DoPotentialPlantPartioning, DoPastureWater, DoNutrientArbitration, DoActualPlantPartioning, DoActualPlantGrowth, PartitioningComplete, DoStock, DoLifecycle, DoUpdate, DoManagementCalculations, DoEndPasture, DoReportCalculations, EndOfWeek, EndOfYear, EndOfMonth, EndOfDay, DoReport.
  6. After the last day, EndOfSimulation is raised.

Events

Events Listened For

Event Purpose
Commencing Set Today as StartDate
OnDoCommence The main function to run a simulation to trigger major loop

Events Raised To

Event Purpose
StartOfSimulation Occurs once at the start of the simulation
StartOfFirstDay Occurs once at the start of the first day of the simulation
StartOfDay Occurs at start of each day
StartOfMonth Occurs at start of each month
StartOfYear Occurs at start of each year
StartOfWeek Occurs at start of each week
EndOfDay Occurs at end of each day
EndOfMonth Occurs at end of each month
EndOfYear Occurs at end of each year
EndOfWeek Occurs at end of each week
EndOfSimulation Occurs at end of simulation
FinalInitialise Final Initialise event. Occurs once at start of simulation
DoCatchYesterday Occurs first each day to allow yesterdays values to be caught
DoWeather Occurs each day to calculate weather
DoDailyInitialisation Occurs each day to do daily updates to models
DoInitialSummary Occurs each day to make the initial summary
DoManagement Occurs each day to do management actions and changes
DoFertiliserApplications Invoked to perform all fertiliser applications
DoPestDiseaseDamage Occurs to do Pest/Disease actions
DoEnergyArbitration Occurs when the canopy energy balance needs to be calculated with MicroClimate
DoSoilWaterMovement Occurs each day to do water calculations such as irrigation, swim, water balance etc
DoSoilErosion Occurs to tell soil erosion to perform its calculations
DoSoilTemperature Occurs to perform soil temperature calculations to do solute processes
DoSolute Occurs each day
DoSurfaceOrganicMatterPotentialDecomposition Occurs each day to perform daily calculations of organic soil matter
DoSoilOrganicMatter Occurs each day to perform daily calculations of organic soil matter
DoSurfaceOrganicMatterDecomposition Occurs each day to do the daily residue decomposition
DoUpdateWaterDemand Occurs each day to do daily growth increment of total plant biomass
DoWaterArbitration Occurs each day to do water arbitration
DoPastureWater Initiates water calculations for the Pasture model
PrePhenology Occurs between DoWaterArbitration and DoPhenology. Performs sorghum final leaf no calcs
DoPhenology Occurs each day to perform phenology
DoPotentialPlantGrowth Occurs each day to do potential growth
DoPotentialPlantPartioning Occurs each day to do the water limited dm allocations. Water constraints to growth are accounted for in the calculation of DM supply and does initial N calculations to work out how much N uptake is required to pass to SoilArbitrator
DoNutrientArbitration Occurs each day to do nutrient arbitration
DoActualPlantPartioning Occurs each day to do nutrient allocations
DoActualPlantGrowth Occurs each day to do nutrient allocations. Pasture growth
PartitioningComplete Occurs each day to finish partitioning
DoUpdate Occurs near end of each day to do checks and finalising
DoStock Occurs each day to process stock methods in GrazPlan Stock
DoLifecycle Occurs each day to process a Pest and Disease lifecycle object
DoManagementCalculations Occurs each day after the simulation is done. Does management calculations
DoEndPasture Occurs after pasture growth and sends material to SOM
DoReportCalculations Occurs when do report calculations
DoReport Occurs at end of each day
DoDCAPST Occurs each day when dcaps performs its calculations. This must happen between DoPotentialPlantGrowth and DoPotentialPlantPartitioning
CLEMInitialiseResource CLEM initialise Resources occurs once at start of simulation
CLEMInitialiseActivity CLEM initialise Activity occurs once at start of simulation
CLEMValidate CLEM validate all data entry
CLEMStartOfTimeStep CLEM start of timestep event
CLEMUpdateLabourAvailability CLEM set labour availability after start of timestep and financial considerations
CLEMUpdatePasture CLEM update pasture
CLEMDetachPasture CLEM detach pasture
CLEMPastureReady CLEM pasture has been added and is ready for use
CLEMDoCutAndCarry CLEM cut and carry
CLEMAnimalBreeding CLEM Do Animal (Ruminant and Other) Breeding and milk calculations
CLEMPotentialIntake Get potential intake. This includes suckling milk consumption
CLEMCalculateManure Request and allocate resources to all Activities based on UI Tree order of priority. Some activities will obtain resources here and perform actions later
CLEMCollectManure Request and allocate resources to all Activities based on UI Tree order of priority. Some activities will obtain resources here and perform actions later
CLEMGetResourcesRequired Request and perform the collection of manure after resources are allocated and manure produced in time-step
CLEMAnimalMilkProduction CLEM Calculate Animals (Ruminant and Other) milk production
CLEMAnimalWeightGain CLEM Calculate Animals(Ruminant and Other) weight gain
CLEMAnimalDeath CLEM Do Animal (Ruminant and Other) death
CLEMAnimalMilking CLEM Do Animal (Ruminant and Other) milking
CLEMCalculateEcologicalState CLEM Calculate ecological state after all deaths and before management
CLEMAnimalMark CLEM Do animal marking so complete before undertaking management decisions
CLEMAnimalManage CLEM Do Animal (Ruminant and Other) Herd Management (adjust breeders and sires etc.)
CLEMAnimalStock CLEM stock animals to pasture availability or other metrics
CLEMAnimalSell CLEM sell animals to market including transporting and labour
CLEMAnimalBuy CLEM buy animals including transporting and labour
CLEMAgeResources CLEM Age your resources (eg. Decompose Fodder, Age your labour, Age your Animals)
CLEMHerdSummary CLEM event to calculate monthly herd summary
CLEMFinalizeTimeStep CLEM finalize time-step before end
CLEMEndOfTimeStep CLEM end of timestep event

Properties

Configurable and Reportable Properties

|————–|———–|————————————————-| | Start | DateTime? | Start date of the simulation with format YYYY-MM-DD | | End | DateTime? | End date of the simulation with format YYYY-MM-DD |

Read-Only Reportable Properties

Property Type Description
StartDate DateTime Derived start date
EndDate DateTime Derived end date
Today DateTime Current simulation date
FractionComplete double Fraction of the simulation completed
IsStartMonth bool Whether today is the first of the month
IsStartYear bool Whether today is the first day of the year
IsEndMonth bool Whether today is the last day of the month
IsEndYear bool Whether today is the last day of the year

User Interface

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

Practical Example

No practical example is provided for this function.

See Also