Scripted

Scripted Rules allow users to create scripts that call on functions and variables used in the EFMSim application. A scripted rule allows for more flexibility in manipulating model variables from other rules.

Scripted Rules tab

When the Scripted Rules tab is first loaded, the scripting areas are disabled. These scripting areas also include example scripts that may be used as starting points for creating scripts as needed by users. After a scripted rule is created, the scripting areas become editable.  

There are 3 tabs available in the Scripted Rules tab. The script entered for each of these tabs are executed before, during, and after the simulation computes.

• Initialize – Scripts in this tab are called before the simulation computes.
• Main – Scripts in this tab are called during the compute at every time step.
• Finalize – Scripts in this tab are called after the simulation is computed.

After a script has been written, the Compile Script button enables the user to compile the script. This step is not required. If a script does not compile, the simulation will fail at computation. Each tab in the Scripted Rules tab has its own Compile Script button (Figure).

Figure.  The Scripted Rules interface.

Available Variables

For scripted rules, the following variables are available and are envisioned to be the most typically involved in the scripts. These variables are passed into the script and can be accessed directly without having to be defined in the script.

• elements: references the elements in the layout.
• ModelVariableStorage: references the data created by the simulation. These correspond to the variables that can be found in the results simulation HDF file.
• alternative: references the alternative passed into the scripted rule.
• DATE: references the date.

Available APIs

When creating a script, any public method can be called. The following sections summarize the available functions for a Scripted Rule. These are a subset of available functions and the most typically used.

The available APIs can be selected from the APIs tree then inserted into the script by clicking the Insert in Script button.

The available APIs are grouped in the following folders:

• Alternative
• Layout
• elements
• ModelVariableStorage
• Community
• currentRule

Alternative

A community is not a readily available variable to work with for a script. The following functions work with the current alternative and retrieves the community from the alternative. If the community being retrieved exists but is not assigned to the current alternative, that community is not retrieved.

This example defines a community variable, passes in the community ID, and retrieves the community with ID number 2 in the study’s database.

community = alternative.getCommunity(2);

This example defines a community variable, passes in the community name of “Frogs”, and retrieves the community with that given name in the study’s database.

community = alternative.getCommunity(“Frogs”);

Layout

Like a community variable, the layout variable is not a readily available variable to work with for a script. The following functions can be used to retrieve the layout ID or layout name of the layout assigned to an alternative.

In the following examples, alternative.getLayout() retrieves the layout associated to the alternative. The getId() and getName() methods are then applied to the retrieved layout variable.

The following example defines an integer variable “layoutID” and retrieves an integer that corresponds to the layout associated to the alternative.

layoutID = alternative.getLayout().getId();

The following example defines a string variable “layoutName” and retrieves the layout name associated with the alternative.

layoutName = alternative.getLayout().getName();

Elements

The following functions work with an elements variable. These functions retrieve the count of elements or a list of elements of a given layout.

The following example defines a count variable; the layout ID is passed in to retrieve the count of elements in the associated layout.

count = elements.getElementCount(alternative.getLayout().getId());

The following example defines a computingElements variable; the index of the first row of elements, the number of elements, and the layout ID are passed in to retrieve the list of elements in the layout starting from the index of the first row of elements.

computingElements = elements.getElements(0, count, alternative.getLayout().getId());

ModelVariableStorage

The following functions work with a given model variable.  

The following example retrieves the model variable “SIZE”. Other examples of model variables are “DENSITY” and “STRESS”.

ModelVariableStorage.getModelVariable(“SIZE”);

The following example retrieves the placeholder for the undefined value (1.4E-45) in the model variable.

ModelVariableStorage.getUndefinedValue;

The following example retrieves the model variable “SIZE” of the community and size class in an element for a given date.

ModelVariableStorage.getValue(community, sizeClass, DATE, element, ModelVariableStorage.getModelVariable(“SIZE”));

The following example retrieves the value of the model variable “SIZE” of the community in an element for a given date.

ModelVariableStorage.getValue(community, DATE, element, ModelVariableStorage.getModelVariable(“SIZE”));

The following example sets the model variable of “SIZE” to 6.0 for the community and size class in an element for a given date.

ModelVariableStorage.setValue(community, sizeClass, DATE, element, ModelVariableStorage.getModelVariable(“SIZE”),6.0);

The following example sets the model variable “SIZE” to 6.0 for the community in an element for a given date.

ModelVariableStorage.setValue(community, DATE, element, ModelVariableStorage.getModelVariable(“SIZE”),6.0);

Community

The following function works with a retrieved community and returns size class based on the size class name.

The following example defines a sizeClass variable and retrieves the size class of the community given the size class name of “Newborn”.

sizeClass = community.findSizeClass(“Newborn”);

currentRule

The following functions work with the current scripted rule.

The following example adds the obj variable into the current scripted rule and assigns it the “Example” variable name.

currentRule.varPut(“Example”,obj);

The following example defines an object variable, passes in the variable name of “Example”, and retrieves that variable from the current scripted rule.

object = currentRule.varGet(“Example”);