VENLINK

Linking APSIM and VENSIM using the Venlink module

Patrick Smith and Dean Holzworth

Overview

The ability to integrate diverse modules through the so-called “plug-in-pull-out” approach is one of APSIM’s key strengths. This guide describes an enhancement of this functionality through the linkage of APSIM with VENSIM, an ‘off the shelf’ modelling package produced by Ventana Systems Inc. Enabling APSIM to call and execute VENSIM models allows researchers to quickly and easily develop new modules for APSIM, making full use of the functionality and intuitive icon-based interface of VENSIM. New VENSIM based modules fully interact with the APSIM Manager in the same manner as existing modules, but may be developed by the user without the need for significant interaction with the APSIM software engineers.

Procedure for producing a VENSIM-based module

To produce a new VENSIM-based module for APSIM the following three steps are recommended:

·         Construct and test a fully functional stand-alone model in VENSIM

·         Convert the ‘shared’ variables within the VENSIM model to ‘APSIM settable’ types

·         Add the necessary sections and commands to the APSIM files.

Step 1. Construct and test a fully functional stand-alone model in VENSIM

VENSIM is quite intuitive to use and previous users of icon-type modelling software should have little difficulty getting up to speed with it. New users are recommended to do the tutorials provided under VENSIM Help. As you design and build your model distinguish between two types of variables – those variables that will be used exclusively within the VENSIM module, and those variable that will be passed from VENSIM to APSIM and vice versa. It may be helpful to visually identify the latter “shared” variables in your VENSIM model diagram by using a special font, colour or outline.

Before attempting to link a VENSIM model to APSIM it is important to ensure that the model is working properly in isolation. This means that all variables that eventually will be shared between the programs will initially need to have values allocated within VENSIM. For constants this is simply a matter of specifying a value in the VENSIM equation editor. For variables that require sequential data it may be useful to dynamically link VENSIM to a spreadsheet using the GET XLS DATA or GET 123 DATA functions in VENSIM. Doing a dummy APSIM run may be a convenient way to generate the data you need to test your VENSIM model, and in many cases it may be the same data that is eventually passed to VENSIM by APSIM (e.g. daily rainfall, soil moisture or crop biomass).

The only rule that must be followed when constructing your VENSIM model is that:

The initial value of all ‘levels’ (= ‘stocks’ or ‘state variables’) in VENSIM must be set indirectly by means of a constant linked to the level with a connecting arrow.
This is because APSIM cannot set VENSIM levels directly.

In addition to the rule concerning levels, the following naming convention is encouraged:

Names of variables in VENSIM models should be as descriptive as possible to assist other users and to help ‘self document’ the model. Spaces are permitted in VENSIM and these will be automatically converted within APSIM to underscores (eg. initial htt in VENSIM will become initial_htt in APSIM..

Step 2. Convert the ‘shared’ variables within the VENSIM model to ‘APSIM settable’ types

Having established that your VENSIM model is working properly it is a simple matter to enable communication with APSIM. Variables that need to be set by APSIM during the course of a run should be converted to one of two variable types:

Variables that require only the initial value to be set by APSIM (namely constants, including those that specify the initial values of levels (as described in Step 1)) should be set to “Constant” and “Normal” under the variable type selectors in the equation editor

Variables that are required to be set by APSIM on a daily basis should be set to “Auxiliary” and “Gaming” under the variable type selectors in the equation editor.

Note that variables owned exclusively by VENSIM do not need to be changed from Auxiliary/Normal or Constant/Normal types. Such variables can still be retrieved by APSIM for calculations and reporting.

Step 3. Add necessary sections to the APSIM files

Firstly you need to drag and drop a VenLink component from the standard toolbox and drop it on your paddock.
Next you need to specify the model file name and the VENSIM variable names that you want to access from APSIM. This can be done by clicking on VenLink and editing the parameters on the right hand side.

Next you need to give the VENSIM “constants” an initial value. Click on the ini node under VenLink and browse to a .ini file. The contents of the .ini file should look something like the following example:

[standard.venlink.constants] 

initial_sum_htt = 0 
soil_moisture_threshold = -0.9 
ll15 = 0.5 
soil_temp_threshold = 20

Finally, VENSIM variables that need to be set every day must be done through a logic component.
After dropping a Logic component from the standard toolbox onto your paddock enter script in the “Start_of_day” tab that looks like this example: