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 arguement, 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.  smPath (submodel path) can be omitted if the parameter variables 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.

Makes a loaded model runable.

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).

 

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.

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.

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

File parameters may be read in from CSV files.  Once a model is made runable (by calling simileScript::ModelWindow Run) then in order to run a model with file parameters, use the command above before building the model. 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

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.