The APSIM Manager Module (MANAGER)

What is the manager module?

The manager module provides the capability to specify a set of rules using conditional logic during simulations to control the actions of modules within APSIM. It does this by using “if” constructs created by the user. It also allows the user to create their own variables and define these as a function of other variables within APSIM. This documentation only gives a brief insight into the possibilities achievable via the APSIM manager module.

How does it manage?

This module manages by issuing messages to modules in the system, many of which are conditional upon states or events within the modules during simulation.

For example:-

if (day = 100) then

fertiliz apply amount = 10 (kg/ha), type = urea (), depth = 50(mm)

endif

Here the fertiliz module will be sent a message containing a directive to apply (the action) fertiliser when the condition is satisfied. It receives a data string (the underlined text) which further describes the action.

As of version 4 of APSIM, the manager module can broadcast a message to all modules by substituting the keyword 'act_mods' in the place of the module name. This capability is useful for multi-point simulations where a sow message needs to be sent to multiple points.

Parameter file settings

As shown above, the manager module input consists of a set of rules and calculations to be used during a simulation. There is no “parameters” data section for the manager module. The manager module is different to most other APSIM modules in that it breaks its input data into event sections. These sections can be the name of any event in APSIM, for example, init, prepare, process, post, tick and prenewmet. For convenience, the MANAGER module also allows “start_of_day ” and “end_of_day ” aliases for prepare and post respectively. The user can have a set of rules to be applied at the start of the day(PREPARE event) or end of the day (POST event) of any APSIM timestep. For example

[all_treatments.manager.start_of_day ]

. rules for evaluation during prepare stage

[all_treatments.manager.end_of_day]

. rules for evaluation during post stage

Now let's add some rules and calculations to this example.

[all_treatments.manager.start_of_day ]

total_n = no3(1) + nh4(1)

if (total_n < 5.0) then

fertiliz apply amount=60 (kg/ha), type=urea (), depth=50 (mm)

endif

avail_sw = sw_dep(1) - crop.ll_dep(1)

if (avail_sw < 10) then

if (rain < 20) then

irrigate apply amount = 50 (mm)

else

irrigate apply amount = 30 (mm)

endif

[all_treatments.manager.end_of_day ]

report do_output

if (crop.stage_name = ‘maturity') then

crop harvest

endif

Here, at the beginning of any day (ie. APSIM timestep ) the conditions of Nitrogen and soil water are used to determine whether irrigation or fertiliser should be applied. The rules above state that

if the total amount of Nitrogen (as nitrate or ammonia) in the top layer of the soil profile drops below 5 kg/ha then 60 kg/ha of urea is applied at a depth of 50 mm.
if the available soil water (ie. water content above a lower limit of plant extraction) drops below 10 mm then irrigation is applied. The amount of irrigation to apply depends on the amount of rainfall falling today. If there is less than 20 mm of rainfall then 50 mm or irrigation is applied whereas only 30 mm is applied when rainfall exceeds 20mm.

At the end of the day (ie. APSIM timestep ) there is a separate set of rules that are evaluated.

We have a direction for the report module to perform an output. No criteria is supplied and so the action will be performed at the end of every day resulting in an output file with columns of daily output.
if the current growth stage of the crop module is “maturity” then the crop is ready for harvest (“harvest” is a action that is recognised by the module called “crop”). The syntax “ module.variable_name ” allows the user to specify from which module to get a particular value instead of using the messaging system's ability to find an owner module.

Trapping another event

Let's consider another example where we modify some climate variables provided by the MET module to simulate a greenhouse effect.

Most modules in APSIM get their weather data from a newmet event that is produced by the MET module, so we need to change the weather variables before this event gets sent out. The MET module produces an event that makes this easy. It is called prenewmet . This event is fired just before a newmet . So all we have to do is to trap this event and change the weather variables.

From the manager\sample\manager.par file:

[modify_met.manager.preNewmet]

maxt = maxt + 2

mint = mint + 2

When the prenewmet event fires, we increase the maximum and minimum temperature by 2 degrees, which then gets propagated to all other APSIM modules when the newmet event is sent by the MET module.

Mathematical operators

The following mathematical operators and reserved words are allowed in APSIM manager files.

Operator	Description
-	Subtraction
+	Addition
*	Multiplication
/	Division
^ or **	Exponent (eg. x**2 is the same as x 2 )
=	Equality
<	Less than
>	Greater than
<>	Not equal to
<=	Less than or equal to
>=	Greater than or equal to
( )	Brackets
If	Logical IF
then	Logical THEN
elseif	Logical ELSEIF
else	Logical ELSE (for alternate logic)
endif	Logical ENDIF
or	Logical OR
and	Logical AND

Variable naming

The manager variable names may consist of the following characters:

Character	Description
a to z	letters – case insensitive
0 to 9	Digits
_	Underscore
%	Percent
.	Period – separator between module name and module variable name eg. input.rain
[]	Square brackets – enclose number of days to accumulate. eg. rain[3] see the accum module
()	Brackets – enclose array index number eg. x(1)

Names must begin with a letter.

Numbers must begin with a digit.

Literals must begin and end with an apostrophe.

Character set

The manager uses the following character set:

Character	Description
a to z	letters – case insensitive
0 to 9	Digits
_	Underscore
%	Percent sign
.	Period or decimal point
[]	Square brackets
()	Parentheses
-	Minus sign
+	Plus sign
*	Asterisk
/	Slash
‘	Apostrophe
=	Equal sign
<	Less than
>	Greater than
	Blank
^	Caret

Manager Functions

Manager functions may not have any spaces. This applies from the first character of the function name to the terminating bracket. The manager has the following functions:-

Function name	Description
date	returns the julian day number of specified date. eg. date(‘1-oct'). The date must be a literal enclosed in single quotes.
date_within	returns 1 if “today's” date is within the range specified, otherwise returns 0. eg. date_within('1-oct,31-oct') The pair of dates must be two date literals separated by a comma, and the whole argument must be enclosed in quotes. Note the lack of quotes near the comma.
nearest_int	Returns the nearest integer to the value specified. eg. nearest_int(var1) Here ‘var1' must be a numeric variable. It cannot be a literal or an expression.
paddock_is_fallow	Returns 1 if there are no crops in the ground. e.g. if (paddock_is_fallow() = 1 and today = date('1-jun')) then wheat sow ... endif
add_months	Takes 2 parameters, a date and the number of months to add to the date. The new date is then returned. e.g. gsrDate = date('1/9/2005') gsrDate = add_months('gsrDate, 1') The whole argument to add_months must be enclosed in single quotes. The number of months can be positive or negative.

Dates may take the following forms:

30/6/95

30/6/1995

Jun

30_Jun

30_Jun_1995

30-jun

30-jun-1995

For example:

date('30/6/95') -- returns the julian day number for 30 jun 1995

date('Jun') -- returns the julian day number for 1 jun for current year.

date('30_jun') -- returns the julian day number for 30 jun for current year.

date('30_jun_1995') -- returns the julian day number for 30 jun 1995

For related chronological or date variables which can be used by the manager module, see the documentation for the CLOCK module. For example

day - returns the day of the month

dd/mm/yyy - returns the day, month and year of the given day.

See the CLOCK module for further details.
Using the manager to send actions to other modules

The APSIM manager module can be used to invoke any action available by any module. Possible actions include:

Resetting individual module values
Reinitialising all data in modules to a given state
Sowing, harvesting or killing crops.
Applications of fertilizer, irrigation or tillage to soil.

Refer to the individual module's documentation for a list of available actions and examples of usage. Refer also to the module's sample files for further examples.