Scripting: Simile scripting language reference

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.