Fundamentals

Fundamentally, CLEM is a simulation model that tracks farm Resources (such as land, labour, stock, crops and finances) as they are affected by a range of farm Activities. While the model can be used to simply track resources required, the user may choose to influence farm production when constrained resources such as finance and labour are limiting, if the shortfall cannot be overcome. This essentially mimics a farming enterprise and it's application is only limited by the range of resources and activities available to the user.

CLEM uses a modular modelling environment where the user builds a simulation by adding Components. While complex simulations can be built, CLEM is designed to be streamlined requiring only the minimum detail for any simulation resulting in optimal computation times, simplified output and avoiding unnecessary parameterisation. This allows the user to build simulations targeted to only what is needed. For example, if a researcher is interested in animal productivity, omitting the finance resource will avoid the overhead of tracking all economics in the model. This approach also allows additional functionality to be added such as adding advanced conception calculations for ruminants or including trucking rules, costs and emissions when buying and selling stock.

At the heart of this modelling environment is the visual user interface of APSIM Next generation and the visual tree structure. This tree structure not only holds all the required components, but the ordering and branching of the tree also influences the simulation by defining filtering, timing and the order in which activities are performed. You will need to understand this tree and how CLEM responds to the components in the tree to fully explore the flexibility of the model (see The user interface and Simulation tree).

The modular nature of APSIM Next Generation and CLEM also allows new components to be created for new functionality.

Another benefit of this approach is that the parameters needed to define the system can be located with the component they are most logically associated with. Rather than large tables of parameters to be entered, CLEM requests parameters as components are added. This also makes the model flexible in that the user decides how many crops, fees and even individual animals and family members are required, with no limits imposed by the model.

It may take a bit of time to understand this concept and how to build your simulation. We will go into greater detail in the Using CLEM section.

CLEM uses the event-based programming approach of APSIM Next generation. Essentially this means components are always listening for events to happen before performing some action. Events will either be fired by the modelling environment based on the simulation clock (e.g. on the start of the simulation, or on the start of the month) or by individual components to tell all other components that something has happened (e.g. crop has been harvested, ready to provide resources). This is in contrast to the precursor models that used the classic step-by-step programming approach where the developers specify the order of actions in the code, while this approach uses any number and order of events to determine when code is performed. The event-based approach adds a lot more flexibility and allows future versions of CLEM to communicate and interact with other agricultural models developed in APSIM Next generation and running at the same time. For a full list of events used in CLEM see Events.

Time step

Events in CLEM are tied to the simulation clock and therefore determine the dates to start and end the simulation and the time-step of the model. The time step is the smallest period of time between each repeated step of the model. Models in APSIM Next Generation run on a daily time step which allows detailed rainfall, soil water and plant growth simulations. While a smaller the time step in modelling allows for great detail and precision, it also increases the computational time of the model and parameter detail and data required to run the model. It is often difficult, and unnecessary, to model many management tasks at small time steps. For example, when we consider management decisions such as the allocation of labour, while daily decisions are made by the farmer, it is very difficult to model such fine scale rules. To solve this CLEM currently uses a monthly time step, although future development may allow for a smaller time step if required for management decisions (e.g. 10 days for dairy herd modelling).

Event order

The order events occur (or are "fired" by the model) is often critical to event-based programming. Events are designed to only fire when something particular happens. This may be the result of the action of the model (such as "harvest has just occurred") or may track actions of the user (such as "mouse button just clicked"). The majority of events in CLEM are managed by the APSIM Next Generation modelling environment. These have been designed to fire in a particular order to ensure tasks happen at the right time. For example, we need to ensure any activity that needs to perform cut and carry has the chance to do so before activities try and feed livestock and that stock management rules are applied before any activities can buy and sell stock. The assignment of tasks can be complicated to ensure everything happens at the right time, but this has all been done in the background code for CLEM. For more details on CLEM events you can see the Advanced section (coming soon).

One of the aims of CLEM has been to develop a flexible model that can be used by users with a range of computing skills from those who only wish to use a graphical software environment to those need to modify and expand the model's functionality. The first of these groups has been of particular focus realising that simulating even small holder farming systems can be a complex task and a flexible model aiming to answer a range of questions may, by nature, be confronting to use. For this reason we provide a number of features to assist the user in building the simulation and exploring the results, and troubleshooting when there is a problem. These are all outlined in detail in the section on Using CLEM.