Developing activities

Advanced topic - requires coding skills

Activities define all the tasks performed on the farm and are used to manage resources. Activities are derived from either the CLEMActivityBase or the CLEMRuminantActivityBase for activities relating to the ruminant herd.

The majority of model code (excluding user interface) is associated with activities.

Activities should contain all properties relevant to the activity for the ease of the user finding parameters. Only parameters associated with the resource that will be used across various activities should be included with the resource types. Ruminant breed parameters should be provided in parameter components and may be specific to an activity.

The Models.CLEM.Activities.CLEMActivityBase base model provides all the functionality needed for CLEM activities.

[Link]

public ResourcesHolder Resources = null;

This APSIM link provides the resources holder for all activities. This is used to request resources and avoids having to link this to every activity.

[XmlIgnore]

public List<ResourceRequest> ResourceRequestList { get; set; }

This list represents all resource requests for the current time step and tracks availability as well as where the activity may reduce the resources taken due to some shortfalls. For a full description of how to model activities interacting with resources see Using resources in activities.

[XmlIgnore]

public List<CLEMActivityBase> ActivityList { get; set; }

This list provides a list of activities associated with this activity that are not provided as children of the activity in the simulation tree. This occurs where an activity needs to create child activities at run-time.

[XmlIgnore]

public ActivityStatus Status { get; set; }

This property indicates the status of the activity. For full details on reporting status see Tracking activity status.

A range of other methods are provided to manage the clearing and cascade calling of all ReportActivityPerformed events

[XmlIgnore]

public ResourceAllocationStyle AllocationStyle { get; set; }

This property determines whether the activity is performed in the default CLEMGetResources method (see Using resources in activities) or elsewhere (set to ResourceAllocationStyle.Manual) as some activities need to perform their own management of resource allocation or perform actions in a custom event (see Using resources in activities). This is generally set to Manual in the CLEMInitialiseActivity of each activity if required.

A range of properties and methods are associated with determining the timing of the activity. See Timing of activities for more details.

A suite of methods are provided to check for, request and retrieve resources (including labour) and then perform the activity. These are fully outlined in Using resources in activities.

This base class also has the event handler and calls for reporting when any resource was is short supply (see Using resources in activities).

public OnPartialResourcesAvailableActionTypes OnPartialResourcesAvailableAction { get; set; }

Every activity has an OnPartialResourcesAvailableAction that determines what steps are taken if any of the requested resources are only partially available (see Using resources in activities and What to do when resources are limiting).

The Models.CLEM.Activities.CLEMRuminantActivityBase base model provides additional functionality needed for CLEM activities that relate to the ruminant herd.

public List<RuminantFilterGroup> HerdFilters { get; set; }

The herd filters relating to this activity are defined by all Ruminant groups at or above the activity in the simulation tree are stored in this list.

The private method GetHerdFilters(bool allowMultipleBreeds, bool allowMultipleHerds) is used to retrieve these filter during the initialiseHerd() method that every ruminant based activity needs to call when initialising.

public string PredictedHerdName { get; set; }

private void DetermineHerdName()

The herd name stores the name of the herd being managed by this activity. The private method DetermineHerdName() is used to get the name and also performs are range of validation tests. The private method HerdCheck() is also available for checking the herd elsewhere.

public List<Ruminant> CurrentHerd(bool includeCheckHerdMeetsCriteria)

This public method returns the list of individual ruminants for the activity as specified by any associated ruminant filter groups with validation warnings provided if problems are encountered.

A range of APSIM and CLEM attributes are available to provide additional details and functionality. These are provided above the class definition of an activity (APSIM model) and include Linking to user interface and Defining permitted parent models as well as the Description used to describe the model.

[HelpUri(string uri)]

The Help Uri attribute is used to provide a link between the CLEM component and the associated page in the online user guide. These Uris begin with "Content/" representing the upper level of the server path containing the web files.

[MinimumTimeStepPermitted(TimeStepType timestep)]

This attribute determines the minimum time-step supported by the CLEM component. With the roll-out of user defined time-steps less than the original monthly time-step it was necessary to restrict possible time-steps on some activities and ensure sub-monthly time-steps can not be used until a component has been checked to ensure the functionality is retained. The default (no attribute added) is Monthly.

The options for TimeStepType are Monthly, Fortnightly, Weekly and Daily.

[ModelAssociations(associatedModels:, associationStyles:, bool SingleInstance)]

This attribute defines the rules for the style of component and what other components must also be present in the simulation. It takes two arrays and a boolean value

associatedModels: new Type[] {typeof(CLEMComponentType)}

This list of CLEM component types determines a type of component that must accompany the class being defined. The association with with the component (class) is defined in the next array in the corresponding order to types defined here with the typeof() method.

associationStyle: new ModelAssociationStyle[] { modelAssociationStyle }

This list (Array) provides an association style for each component type provided in the Association models. The styles available include:

  • InScope: the associated component must be in scope of the model considered.

  • Descendent: the associated component must be found as a descendent of the model considered.

  • Child: the associated component must be a direct child of the model considered.

  • DescendentOfRuminantType: the associated component must be a descendent of the RuminantType component (such as a specific parameter component).