Companion components

Many Resource and Activity components either require additional components provided as children (relates to simulation tree structure) before they can proceed, or can have additional custom functionality added based on the components supplied. To achieve this functionality we supply a series of generic component types that can be used across CLEM. These companion components work alongside the parent and rely on some communication with the parent component. These include Filtering and sorting individuals, Relationships, Greenhouse gas emission, Activity fee and Labour requirement and are described in more detail below. An interface with common properties and features is implemented to allow this interaction which includes identifying the companions, passing resources quantities to companions to determine actions, sharing resources, and identifying implications when resources are limiting.

Identifying companion components

It is important that any parent component can identify a specific companion component. One approach to achieve this would be to identify the companion components using the name property provided in the simulation tree, but this is prone to mismatch errors and assumes the user knows all required naming conventions and parent requirements. The approach used is to determine whether a parent component supports companion components which will determine where you are able to add companion models in the tree structure. Each parent that supports companion will provide a list of identifier labels for each companion type supported. The companion types in turn have a property that will allow the user to select which identifier the companion relates to. The validation section of CLEM is then responsible for reporting when required components are missing. Not all parents will require this identification and so when no identifiers are specified for a given companion type, the property will not display in the user interface to avoid confusion and empty lists.

The name of the property relating to the identifier may be different across the various companion components.

Linking companion components to parent actions

Most of the companion models will be required at the time the parent component is performing its tasks and will likely need to know the current state of the parent's action. For this reason the companion mode also specifies a unit type that it expects to work with. The parent component that supports companions will provide the list of available units it can supply and these will appear in a drop down property list as a property of each companion.

An example would be a crop task such as planting that needs labour at the rate of 1 day for each hectare planted. This would be achieved by adding a Labour requirement companion component below the Crop task activity and setting the style property to per ha and the amount property to 1. As this task is needed the parent will provide the current area of the crop and the labour requirement will specify the individuals that can be used, adding this resource to the activities resources to be considered.

Examples of companion components

The following section outlines some of the companion components and how they utilise the interface to influence the parent model (e.g. activity)

Most Activities support adding fees and labour requirements as a function of the size of the activity task. These financial and labour resources are added to the parent activity's list of resources needed to complete the task and any shortfalls can be considered. These shortfalls can also influence the outcome of the task if the PerformOnPartialResourcesAction is UseAvailableWithImplications if this is supported by the parent activity. The level of support of this feature depends upon the activity, but most will support reduced activity tasks if labour or finances are limiting. The Labour requirement component will also specify the individuals who can perform the task.

Ruminant group and Labour group are used widely by activities. The filtering functionality of these groups is well suited to companion components as identifiers specified by the parent activity can identify the groups used to filter specific individuals needed by the parent activity. The parent activity can also determine how to treat multiple filter groups with the same identifier selected based on the tasks being performed. Most activities will allow multiple filter groups to be provided and will combine the individuals selected by each group into a list of unique individuals with ordering still respecting the order of the individual filter groups so the activity will respect the order in which individuals were specified for the task.

Some activities require relationships to be defined. This is now performed by the Relationship companion component that includes an identifier property to specify which of the expected relationships are being provided (see Manage pasture as an example).

In future, we aim to allow relationships to modify a specified property based on the amount of another resource in the simulation allowing for more dynamic management of property values. For example, the maximum number of breeders kept and used in Manage ruminants could be set as a function of pasture biomass and thus allow herd size to be set as a function of the pasture available (or a running mean).

Greenhouse gas emissions are another good example of a companion component where an identifier and specified units are used from the parent activity to calculate the amount of greenhouse gas created from the amount property and place this in specified Greenhouse gases store. This emission calculation is performed after the activity has determined the available resources and therefore the size of the task performed.

Any number of Apply trucking settings can be added when purchasing and selling animals (see RuminantBuySell.htm) to provide multiple trucking rules for trucks used for purchases and sales (specified by identifier).

See next section - Restricting activities and resources