The SimileScript language is object based. There are commands to create model window objects, run control objects and table display objects. Once an object is created, methods (or commands) of those objects can be used. (To those who know TclTk, the commands follow the same rules as the Tk graphical user interface widget commands.)

• ModelWindow
• RunControl
• TableHelper

Model window

Create model window object

For example:

similescript::ModelWindow modelWin

objectName commands (or methods in object based terminology) can now be used.

Model window object commands

Most of these commands correspond to Simile model window menu commands.

Load (open) an existing model file from disk. It takes one argument, modelFile,  that is the file name of the model to be loaded. Only one model may be loaded at any time. To remove the current model use: objectName New (see below).

 

 

Removes any existing model loaded (opened). This command corresponds to the Simile model window <strong>File</strong> -&gt; <strong>New</strong> command. Removing the current model allows another model to be loaded.

Opens a file open dialog box, allowing the script user to choose the model to load (open)

at script run-time.

In order to run a model with file parameters use the command above before building the model.  The filepath​ refers to a parameter metafile (.spf) which contains values or references to other files. smPath (submodel path) can be omitted if the parameter variables specified in the file are relative to the top level of the model.

bool must be either “true” or “false” (or other versions of Boolean values accepted by Tcl).  If “true” the single-window Model Run Environment is used. Otherwise, seperate windows will be produced for each helper (display). This command is only of use if the helpers are made visible.

(New in v5.5) Returns all the enumerated type definitions in the top level of the model, in the form of a nested list. Each sublist has the type name for its first element, and the type members for its remaining elements.

(New in v5.5) Returns a list of the members of the enumerated type given by typeName, if it exists in the top level of the model.

(New in v5.5) Changes the membership of the enumerated type given by typeName, if it exists in the top level of the model. The new members are the second and any subsequent arguments passed to this function. The model must be rerun before the new definition takes effect.

 

Makes a loaded model runnable.

Makes a loaded model runable using Tcl as the model execution environment. Tcl is slower than the usual compiled C++ executable but has more error checking. However, error checking (dubugging) is usually done from the graphical Simile user interface.

Makes the model window visible.

Hides the model window (default).

Removes the model window.

 

 

Run control

Create run control object

For example:

similescript::RunControl runControl

objectName commands (or methods in object based terminology) can now be used.

Run control object commands

Most of these commands correspond to edit fields and buttons on the regular Simile run control dialog box.

Path - Some of the methods (commands) below take a parameter path. Model component paths end with the name of the component (e.g. compartment, variable or

submodel preceeded by a string of all the submodels the component is contained by. The submodels are seperated by a slash “/”. The toplevel model (sometimes called the “desktop”) is refered to as “/”.  Since all components are contained by the toplevel model all paths start with a leading /, e.g. “/Number of Trees” is the variable “Number of Trees” in the top level model. “/Tree/Saplings” is the variable “Saplings” in the submodel “Tree” which is contained directly by the toplevel model.

Start running the simulation. The simulation will run for the time set by, objectName SetExecuteFor, or the default execution time stored in the model file.  Generally, your script will be clearer if you always use objectName SetExecuteFor.  Returns a string containing the elapsed real-time to run the simulation (not CPU time), e.g.

1.27 sec

Resets the simulation to time zero.

Set the simulation time for which the simulation will run when objectName Start is called.

Set the integration method. method may be either, “Runge-Kutta” or “Euler”

Sets the integration method to Euler

Sets the integration method to 4th-order Runge-Kutta.

New to Simile v5.8: Returns the current maximum proportional error used for adaptive stepsize variation. If adaptive step size variation is not in use, a value of zero is returned.

Sets the integration method to 4th-order Runge-Kutta.

New to Simile v5.8: Sets the current maximum proportional error used for adaptive stepsize variation. If an argument of zero is supplied, adaptive stepsize variation is turned off, otherwise it is turned on.

Different submodels in a model can be specified as operating on different time steps (in the submodel properties dialogue). Use this command to set timesteps.  

This setting is for use with physical units, to specify the particular time unit, rather than using abstract time units. If you have not specified consistent physical units for all flows, you should not change this setting from the default “unit”. If you have specified consistent physical units, you should choose the unit you wish to use to specify how long to execute the model for. Valid values are; unit, second, minute, hour, day, week, month, year and Ma.

Set the simulation time interval at which displays (helpers) are updated.

New to Simile v6.4: Initializes the state of the random number generator. This can be used to ensure that a model run produces exactly the same results each time, even if it contains random functions. The argument is used to build a state for the generator, so using the same argument will ensure the same subsequent sequence of randoms.

Returns the current simulation time.

Returns the simulation time interval at which displays (helpers) are updated.

Returns the simulation time for which the simulation will run when objectName Start is called.

Returns the current integration method.

Returns the number of different time steps used in the model.

A synonym for GetNumberOfTimeSteps.

Return the time interval for the given timestep index.

Returns the current time units.

Return the value of a model variable given by the variable path path

New to Simile v5.6: Requests that on each display update, a call be made to a procedure defined in the script, passing the values of the variables specified in the path arguments. If there are no arguments, there will be no callbacks. The procedure ReceiveValues is called, with the objectName making the request as the first argument, the model time as the second argument, and the values of the requested variables as the subsequent arguments.

This command is analogous to the model window object's LoadParams command.  Once a model is made runnable (by calling simileScript::ModelWindow Run) then in order to run a model with different file parameters, use the command above before resetting the model. The filepath​ refers to a parameter metafile (.spf) which contains values or references to other files. smPath (submodel path) can be omitted if the parameter variables in the file are relative to the top level of the model.

Set the value of a model variable given by the variable path path. This only makes sense for variable parameters. Constant parameters are set by scenario file and other variables are calculated each time step.

Returns the maximum value acceptable for the variable parameter given by path. (Values are returned for variables other than variable parameters but the values are not used.)

Returns the minimum value acceptable for the variable parameter given by path. (Values are returned for variables other than variable parameters but the values are not used.)

Returns the class of the model component given by  path. The class will be one of: SUBMODEL, VARIABLE, COMPARTMENT, FLOW, CONDITION, CREATION, REPRODUCTION, IMMIGRATION, LOSS or ALARM.

Returns the dimensions of a model component given by  path. Components of a variable instance submodel (population submodel)

Returns evaluation method of a model component given by  path. The evaluation method will be one of EXOGENOUS, DERIVED, TABLE, INPUT,
SPLIT or GHOST.

Returns the type of a model component given by  path. The type will be one of: VALUELESS, REAL, INTEGER, FLAG or EXTERNAL. FLAGs are Boolean types.

Returns a Tcl list of all model components (e.g. submodels as well as variables). E.g. {/Number of Trees} /r /Tree/Saplings /Tree {/Tree/Tree Size} {/Tree/Growth Rate}

{/Tree/Maximum Growth Rate} {/Tree/Chance of Death} {/Tree/X Position} {/Tree/Y Position} /Tree/ID

Note that paths with spaces will be returned wrapped by { }.

Make the run control dialogue box visible.

Hide the run control dialogue box.

Table helper object

Create table helper object

For example:

Version 5 and up

similescript::TableHelper tableHelper runControl "table1"

Version 4

similescript::TableHelper tableHelper modelWin "table1"

Table helper object commands

Adds the variable given by path to the list of variables to be written to the table.

Removes the variable given by path from the list of variables to be written to the table.

Causes the table to be updated. Use in conjunction with objectName SetUpdateAtDisplayInterval value.

If value is “true” the table updates its display every display interval (even if the table is hidden and so not visible on the screen). This takes a significant time and so the simulation will run faster if value is “false”. Use objectName Update to update the table at the end of the simulation.

Return “true” or 1 if the table is set to update its display every time interval or “false” or 0 if the table does not update its display. If “false” use objectName Update before saving the contents to file or viewing the table.

If value is “true” the table keeps a set of values for each time at which the contents are updated. This can create a large table which takes a significant time to update. If value is “false”, the table will contain only the set of values from when it was last updated. Use objectName AppendToFile to write these to file so they are gathered throughout the simulation.

Return “true” or 1 if the table is set to keep values for each time at which the contents are updated, or “false” or 0 if the table is set to show only current values. If “false” use objectName AppendToFile to save the contents to file without overwriting previous values.

Clear the table.

Save the table contents to a comma separated values (CSV) file named filename. Remember to call objectName Update if objectName SetUpdateAtDisplayInterval was set to “false”.

Append the table contents, preceeded by a line containing section_id, to a comma separated values (CSV) file named filename. The file will be created if it does not already exist. Remember to call objectName Update if objectName SetUpdateAtDisplayInterval was set to “false”.

Make the table display visible.

Hide the table display.

This template represents an agent or individual moving over a surface represented by a grid, for example, animals (agents) moving through vegetation represented by a grid to air parcels moving over a surface in a Langrangian model.

 

 

 

 

This very simple template of just 5 elements (2 input parameters and 3 variables) is a scheme for roughly estimating the average temperature during the day and during the night.

Model diagram

Equation listing

Excerpt from PnET

Aber, J.D. and C.A. Federer. 1992. A generalized, lumped-parameter model of photosynthesis, evapotranspiration and net primary production in temperate and boreal forest ecosystems. Oecologia 92:463-474

 
Variable   Tave
    Tave =         (tmin+tmax)/2.0
   
 
Variable   Tday
    Tday =         (tmax+Tave)/2.0
   
 
Variable   Tnight
    Tnight =         (Tave+tmin)/2.0
   
 
Variable   tmax
    tmax =         Variable parameter
    Minimum = -50, Maximum = 50
 
Variable   tmin
    tmin =         Variable parameter
    Minimum = -50, Maximum = 50

 

 

 

 

 

 

Simple non-sexual inheritance.

 

This model addresses the following problem:

You have a physical container with two substances, say water and salt.   You know the expression which governs the flow of water out of the container, and need to work out the rate at which salt flows out.  

Assuming that the salt in the outflow is at the same concentration as the salt in the container, the answer is to work out the salt concentration in the container, then use this, along with the water outflow, to calculate the rate of salt outflow.

Note that a single physical container is modelled using two Simile compartments.

In the template, the two substances are represented by substance1 (water) and substance2 (salt).

This template can be daisy-chained, to represent a chain of containers.  This can represent, for example, a food chain, where substance1 is biomass, and substance2 is some trace substance, e.g. DDT.   In this case, you would almost certainly want to have a separate outflow from each container, but only from the substance1 compartment, representing the loss of biomass through metabolic respiration, with the DDT being left behind.  This would result in an increase in the concentration of DDT as youmove along the food chain.

 

This template is for modelling the flow of some substance between multiple layers.  A typical application would be for modelling the flow of, for example, water or heat between soil layers.

The basic idea is to have a multiple-instance submodel for the layers, with each instance representing a single layer.   Each layer has a single compartment (stock) representing the amount of substance in that layer.   At least two flows are associated with teh compartment, an inflow representing the rate at which the substance flows into the layer from the layer above, and an outflow representing the rate at which the substance flows into the layer below. 

I say "at least two flows...", because the modeller might choose to add additonal flows, e.g. for rainfall into the first layer and drainage flow out of the last layer.  Alternatively, the inflow into the top layer can be considered to be rainfall, and the outflow from the bottom layer can be considered to be drainage out of the system.

We need to link the outflows and inflows of neighbouring layers together, so that the inflow of layer i+1 is set equal to the outflow of layer i (counting the top layer as number 1).   There are two ways of doing this.  One method is to use an array variable outside the submodel: this should be illustrated in another template.  In this template, however, we use an association submodel to link neighbouring layers together.  This has considerable benefits when there are many layers, since Simile needs to handle only as many values as there are interflows between layers.

Equations

Below/condition = layer_number_lower==layer_number_upper+1

Below/interflow = outflow_lower

Layer/inflow = sum({interflow_upper})