Insight Maker API

Functions to manipulate Insight Maker models.

Introduction

The following is a set of API functions for Insight Maker. JavaScript is the language used for these interfaces. In addition to the Insight Maker specific functions listed here, standard JavaScript is also supported in buttons.

There are three primary avenues for making use of this API.

For the “Action” of Buttons embedded within models.
For a parent page to manipulate an embedded IFRAME containing an Insight Maker model.
Using the JavaScript console of the web browser to manipulate a model. To find the built-in JavaScript console for a web browser, see the relevant browser’s documentation.

Primitive Types

A number of the API function refer to primitives by their type. The following are the valid types. Types are usually quoted when used and should always be capitalized (e.g. “Stock”).

Stock
Variable
Converter
Flow
Link
Text
Picture
Folder
Button
Ghost

Examples

The following examples illustrate the usage of the API for certain scenarios.

Using Dialogs

Ask the user to specify a URL and opens a new web page at the location.

showURL(showPrompt("What page should I open?"));

Expanding and Collapsing Folders

This example expands all the folders in the model.

expandFolder(findType("Folder"));

And this collapses them.

collapseFolder(findType("Folder"));

Notes

Show the notes for all flow and link primitives in the model.

var connectors = findType(["Flow", "Link"]);
showNote(connectors);

Using Opacity

Makes the currently selected primitives partially transparent.

setOpacity(getSelected(), 50);

Rabbit Birth Rate

This example will work with the default Insight Maker model. It prompts the user to specify the birth rate for the rabbit population. It then sets the relevant primitive to that value and runs the model.

var birthRate = showPrompt("Enter the birth rate for the rabbits:", 0.1);
var birthPrimitive = findName("Rabbit Birth Rate");
setValue(birthPrimitive, birthRate);
runModel();

This could also be written more compactly as

setValue(findName("Rabbit Birth Rate"), showPrompt("Enter the birth rate for the rabbits:", 0.1));
runModel();

Building a Model

This example creates a new model with two stocks connected by a flow.

clearModel();

var source = createPrimitive("Source", "Stock", [100, 50], [140, 50]);
setValue(source, 100); //Give the source an initial value of 100

var sink = createPrimitive("Sink", "Stock", [100, 300], [140, 50]);

var myFlow = createConnector("Leakage", "Flow", source, sink);
setValue(myFlow, "0.1*[Source]"); //10% of the source's volume moves to the sink each time period

Manipulating a Model in an IFRAME

To access the API of an embedded IFRAME, first give the IFRAME an “id” property. This is not added by default in Insight Maker. For instance change

<IFRAME SRC="...

<IFRAME ID="InsightMakerModel1" SRC="...

Then from the parent page you can use the following JavaScript syntax to call API functions. This example calls the API’s clearModel function.

document.getElementById('InsightMakerModel1').contentWindow.postMessage("clearModel()", "*");

Summary

Insight Maker API	Functions to manipulate Insight Maker models.
Dialogs and User Input
showMessage	Shows a message in a dialog window.
showPrompt	Shows a prompt in a dialog window and provides a text input for the user to enter a value.
showChoice	Shows a prompt in a dialog window and provides the user the option to click “OK” or “Cancel”.
showURL	Creates a new web browser window and sets the URL.
downloadFile	Downloads a file.
showData	Creates a display to showcase data.
frontWindow	Gets the front-most window (if one exists).
closeAllWindows	Closes all open windows.
openFile	Prompts the user to select one or more files on their computer.
General Model Functions
runModel	Runs a simulation and optionally returns the results.
saveModel	Saves the model.
clearModel	Removes all primitives from the model.
layoutModel	Reorganizes the primitives in the model according to an algorithm.
setZoom	Sets the scale of the diagram display.
Simulation Settings
getTimeStep	Gets the time step used in the simulation.
setTimeStep	Sets the time step used in the simulation.
getTimeStart	Gets the start time for the simulation.
setTimeStart	Sets the start time for the simulation.
getTimeLength	Gets the length of the simulation.
setTimeLength	Sets the length of the simulation.
getPauseInterval	Gets the intervals at which to pause the simulation.
setPauseInterval	Sets the intervals at which to pause the simulation.
getTimeUnits	Gets the time units of the simulation.
setTimeUnits	Sets the time units of the simulation.
getAlgorithm	Gets the algorithm for the simulation.
setAlgorithm	Sets the algorithm of the simulation.
getMacros	Gets the macros for the insight.
setMacros	Sets the macros of the insight.
Finding and Accessing Specific Primitives
findName	Finds and returns a primitive by its name.
findAll	Finds and returns all primitives in the model.
findType	Finds and returns all primitives of a specific type.
findID	Finds and returns a primitive using its ID.
findValue	Finds and returns all primitives whose values match a regular expression.
findNote	Finds and returns all primitives whose notes match a regular expression.
Create and Delete Primitives
createPrimitive	Creates a new primitive and adds it to the model.
createConnector	Creates a new connector primitive and adds it to the model.
removePrimitive	Removes a primitive from the model.
Primitive Selections
highlight	Highlights a single primitive.
getSelected	Finds and returns the currently selected primitives.
setSelected	Sets the currently selected primitives.
isSelected	Indicates whether a primitive is selected.
General Primitive Functions
getID	Gets the ID of the passed primitive.
getType	Gets the type of the passed primitive.
getName	Gets the name of the passed primitive.
setName	Sets the name of the passed primitive.
getUnits	Gets the units of the passed primitive.
setUnits	Sets the units of the passed primitive.
getConstraints	Gets the upper and lower bounds on the passed primitive to test against during simulation.
setConstraints	Sets the upper and lower bounds on the passed primitive to test against during simulation.
getNote	Gets the note of the passed primitive.
setNote	Sets the note of the passed primitive.
showNote	Shows the note for the passed primitive.
hideNote	Hides the note for the passed primitive.
showEditor	Shows the value editor for the passed primitive.
getValue	Gets the value of the passed primitive.
setValue	Sets the value of the passed primitive.
getSize	Gets the size of the passed primitive.
getPosition	Gets the position of the passed primitive.
setPosition	Sets the position of the passed primitive.
Primitive Styling Functions
flash	Temporarily changes the opacity of a primitive.
getShowSlider	Gets the show slider property of the passed primitive.
setShowSlider	Sets the show slider property of the passed primitive.
getSliderMin	Gets the slider min property of the passed primitive.
setSliderMin	Sets the slider min property of the passed primitive.
getSliderMax	Gets the slider max property of the passed primitive.
setSliderMax	Sets the slider max property of the passed primitive.
getSliderStep	Gets the slider step property of the passed primitive.
setSliderStep	Sets the slider step property of the passed primitive.
getOpacity	Gets the opacity of the passed primitive.
setOpacity	Sets the opacity of the passed primitive.
getLineColor	Gets the line color of the passed primitive.
setLineColor	Sets the line color of the passed primitive.
getFontColor	Gets the font color of the passed primitive.
setFontColor	Sets the font color of the passed primitive.
getFillColor	Gets the fill color of the passed primitive.
setFillColor	Sets the fill color of the passed primitive.
getImage	Gets the image of the passed primitive.
setImage	Sets the image of the passed primitive.
Stocks
getNonNegative	Gets the non-negative property of stocks (also applicable to flows).
setNonNegative	Sets the non-negative value of the passed stocks (also applicable to flows).
getStockType	Gets the type of the stock.
setStockType	Sets the type of the passed stock.
getDelay	Gets the delay length of conveyor stocks.
setDelay	Sets the delay length of the passed conveyor stock.
Connectors	See getNonNegative and setNonNegative for setting the only-positive property of flows.
getEnds	Gets the alpha and omega for the connector
setEnds	Sets the alpha and omega for a connector.
connected	Determines two primitives are connected by a link, flow, or transition.
States
getResidency	Gets the residency property of a state primitive.
setResidency	Sets the residency property of a state primitive.
Transitions and Actions
getTriggerType	Gets the trigger type of a transition or action.
setTriggerType	Sets the trigger type for a transition or action.
getTriggerValue	Gets the trigger value equation of a transition or action.
setTriggerValue	Sets the trigger value for a transition or action.
getTriggerRepeat	Gets the trigger Repeat property of a transition or action.
setTriggerRepeat	Sets the trigger Repeat property for a transition or action.
getTriggerRecalculate	Gets the trigger Recalculate property of a transition or action.
setTriggerRecalculate	Sets the trigger Recalculate property for a transition or action.
Converters
getData	Gets the data of a converter.
setData	Sets the data of a converter.
getConverterInput	Gets the input source of a converter.
setConverterInput	Sets the input source of a converter.
getInterpolation	Gets the interpolation mode of a converter.
setInterpolation	Sets the interpolation mode of a converter.
Buttons
pressButton	Simulates a press of the passed button(s) firing its action.
Agents
getPopulationSize	Gets the size of the agent population.
setPopulationSize	Sets the size of the agent population.
getAgentBase	Gets the base agent for the population.
setAgentBase	Sets the base agent for the population.
getGeometryWrap	Whether the geometry should wrap across edges.
setGeometryWrap	Sets the wrap property for the population area geometry.
getGeometryUnits	Gets the units for the population area geometry.
setGeometryUnits	Sets the units for the population area geometry.
getGeometryWidth	Gets the width for the population area geometry.
setGeometryWidth	Sets the width for the population area geometry.
getGeometryHeight	Gets the height for the population area geometry.
setGeometryHeight	Sets the height for the population area geometry.
getAgentPlacement	The placement method for the agent population.
setAgentPlacement	Sets the placement method for the agent population.
getAgentPlacementFunction	A custom placement function for the agent population.
setAgentPlacementFunction	Sets the custom placement function for the agent population.
getAgentNetwork	The network method for the agent population.
setAgentNetwork	Sets the network method for the agent population.
getAgentNetworkFunction	A custom network function for the agent population.
setAgentNetworkFunction	Sets the custom network function for the agent population.
Folders
collapseFolder	Collapses a folder or an array of folders.
expandFolder	Expands a folder or an array of folders.
getCollapsed	Returns whether or not a given folder is collapsed.
getParent	Gets the parent folder for a primitive.
setParent	Sets the parent folder for a primitive.
getFrozen	Gets the frozen state for a primitive.
setFrozen	Sets the frozen state for a primitive.
getChildren	Returns the children of a folder.
getFolderType	Gets the type of a folder.
setFolderType	Sets the type of a folder.
getFolderAgentParent	Gets the agent parent of a folder.
setFolderAgentParent	Sets the agent parent of a folder.
getFolderSolver
setFolderSolver	Sets the solver object for a folder
Utility Functions
excludeType	Removes a specific type of primitive from an array of primitives.
primitiveIndex	Locates the index of a specific primitive in an array of primitives.
uniquePrimitives	Returns the passed array with duplicated primitives removed
setGlobal	Sets the value of a global variable.
getGlobal	Gets the value of a global variable.
Insight Maker Interface
topBarShown	Determines whether or not the Insight Maker top toolbar (which contains the Run Simulation button and other tools) is currently shown.
toggleTopBar	Toggles the visibility of the top toolbar.
sideBarShown	Determines whether or not the Insight Maker side panel (which contains parameter sliders and information about the selected primitive) is currently shown.
toggleSideBar	Toggles the visibility of the side panel.
updateSideBar	Refreshes the values in the side panel to reflect any changes in the model.

Dialogs and User Input

showMessage

function showMessage( message )

Shows a message in a dialog window.

Parameters

message

The string to show as the message.

showPrompt

function showPrompt( message,
defaultValue )

Shows a prompt in a dialog window and provides a text input for the user to enter a value.

Parameters

message	The string to show as the prompt.
defaultValue	The default value for the prompt. This parameter is optional.

Returns

The value entered by the user.

showChoice

function showChoice( message )

Shows a prompt in a dialog window and provides the user the option to click “OK” or “Cancel”. Returns the value the user clicked as a boolean.

Parameters

message

The string to show as the prompt.

Returns

The value of the button clicked by the user as a boolean. “OK” is true, “Cancel” is false.

showURL

function showURL( url )

Creates a new web browser window and sets the URL.

Parameters

url	The URL to show.

downloadFile

function downloadFile( fileName,
data,
type )

Downloads a file.

Parameters

fileName	The name of the file to download
data	The data to download
type	The type of file

showData

function showData( title,
tabs,
size )

Creates a display to showcase data. Multiple tabs of data may be shown. This function is passed an array of objects each representing an individual tab.

Parameters

title	The title for the data window
tabs	An array of tab objects
size	The dimensions of the window in the form [width, height] (optional)

Tab Objects

Each tab object contains several properties.

name	The name of the tab
type	The tab type. E.g. “text”, “HTML”, “table” or “chart”
data	The data for the tab

The different types of tabs are as follows.

Text Tab

A text tab displays a large amount of text. For a text tab, the data property should be the text string that will be displayed.

HTML Tab

An HTML tab displays HTML content. For an HTML tab, the data property should be the HTML content that will be displayed.

Table Tab

A table tab displays a grid of data. For a table tab, the data object should be an array of arrays. Each inner array represents a column in the resulting table. The following property is also supported for tables.

header

For a table, an array containing the titles of the columns (optional)

Returns

The window object that was created.

Example

showData("Sample Data",
 [
 {name: "I'm a Text Tab",
  type: "text",
  data: "This is a long data string..."
  },
 {name: "I'm an HTML Tab",
  type: "html",
  data: "<center><p>This is <b>HTML</b> content.</p></center>"
  },
 {name: "Here's a Grid",
  type: "table",
  data: [[1,2,3,4],[1,4,9,16]],
  header: ["Value", "Value^2"]
  }
 ]
)

frontWindow

function frontWindow()

Gets the front-most window (if one exists).

Returns

A window object.

closeAllWindows

function closeAllWindows()

Closes all open windows.

openFile

function openFile( config )

Prompts the user to select one or more files on their computer. Information about the selected files are made available and the contents of the files are optionally read into memory.

Note that this function needs to be called as a direct result of user actions (such as the user clicking on a button). Browser security restrictions will prevent the function from operating if it is not called in response a user actions. Note also that this function is not supported on Internet Explorer 9.

Parameters

config	A configuration object with the following optional properties:
multiple	If false, only a single file may be selected; if true, one or more files may be selected at a time.
accept	A string containing a MIME file type to filter file selection. If defined, only files matching the specified type may be selected. For example, “image/*” may be used to only accept image files.
read	If defined the selected files will be opened and their contents loaded. Read may either be “binary” in which case the contents is loaded as a binary string, “text” in which case the contents is loaded as a regular text string, or “xlsx” in which case an Excel file is loaded as an object.
onCompleted	A function to handle results. The openFile function is asynchronous. Once it completes, the callback function is called with the resulting data as a parameter.
onError	A function to handle the occurrence of an error.
onSelected	A function fired once files have been selected but before data has been read.

Returns

The openFile function is asynchronous and returns nothing directly. On the successful selection of files, the callback is called with the results.

If config.multiple is false, these results are a single file object. If config.multiple is true, then these results are an array of file objects. Each file object has the following properties

file	The original file object.
name	The name of the selected file.
type	The type of the selected file.
size	The size of the selected file.
contents	If config.read is true, the contents in the file is loaded with the specified type.

Examples

// Select a single text file and display its contents
openFile({
   read: "text",
   multiple: false,
   onCompleted: function(result){
       alert(result.contents);
   }
});

General Model Functions

runModel

function runModel( config )

Runs a simulation and optionally returns the results.

Parameters

config	A configuration object. For compatibility, if set to the Boolean value, equivalent to calling runModel with a configuration object with the silent property set to the boolean value.
config.silent	If false or undefined, behaves the same way as if the user clicked the run simulation button. If true, no visible response is shown to running the simulation and the results of the simulation are returned as an object.
config.selectedDisplay	The selected tab in the display, should be a display primitive.
config.rate	A multiplier to control the speed of the animation in the result window. Use -1 to skip animation.
config.onSuccess(results)	Callback called when the simulation completes successfully.
config.onError(results)	Callback called when an error occurs during the simulation.
config.onPause(results)	Callback called when the simulation is paused. If this is set and a pause interval is defined for the model, then the simulation will be asynchronous and a results object will not be returned directly by the function call.

Returns

If silent is true, returns the simulation results as a results object. If callbacks are defined, the callbacks are called with a results object. This object contains the following properties.

times	The times for each period of the simulation as an array.
value(primitive)	A function that takes a primitive reference and returns an array of the values that primitive took on over the course of the simulation.
lastValue(primitive)	A function that takes a primitive reference and returns the last value of the primitive during the simulation.
window	The results window object (if config.silent is false).
error	”none” if no simulation error occurred, otherwise an error message.
errorPrimitive	The primitive that caused the error.
resume()	If the simulation was paused, this function may be called to resume the simulation. Please note that Insight Maker currently only supports running a single simulation at a time. When a new simulation is started, any currently paused simulations will be terminated immediately.
setValue(primitive, value)	If the simulation is paused, allows changing the value of a primitive. Value can be any equation that does not depend on the model state. E.g. “{Cows: 1, Sheep: 2} * 2” is a valid Value, but “[Other Primitive] + 1” is not.
stochastic	True if the simulation contained an element of randomness.

Examples

# Runs a simulation, and displays the average value of the Stock named "Rabbits"
runModel({
  onSuccess: function(results){
     var sum = 0;
     for(var i = 0; i < results.times.length; i++){
         sum += results.value(findName("Rabbits"))[i];
     }
     showMessage("The average value is: " + sum/results.times.length);
  }
})

# Create interactive run of the model where the primitive "Rate" is adjusted each pause interval
runModel({
  silent: true,
  onPause: function(results){
      console.log("Simulation Step");
      results.setValue(findName("Rate"), prompt("Enter New 'Rate' Value"));
      results.resume();
  },
  onSuccess: function(results){
      console.log("Simulation Done");
      console.log(results);
  },
  onError: function(){
      alert("A simulation error occurred.");
  }
});

saveModel

function saveModel( dialog )

Saves the model.

Parameters

dialog

Pass true to show the properties dialog (e.g. name, description, tags). The dialog is always shown if this is the first save.

clearModel

function clearModel()

Removes all primitives from the model.

layoutModel

function layoutModel( algorithm )

Reorganizes the primitives in the model according to an algorithm.

Parameters

algorithm

The algorithm used to calculate the new positions of the primitive. Either “organic” or “circular”.

setZoom

function setZoom( scale )

Sets the scale of the diagram display.

Parameters

scale

The diagram scale. If this is a number, then it determine the scale level. 1 means 100%, 0.5 means 50%, 2 means 200% and so on. You also pass one of the following strings: “fit” to fit the model to the diagram area, “actual” to reset the scale, “in” to zoom further in based on the current scale, and “out” to further out based on the current scale.

Simulation Settings

getTimeStep

function getTimeStep()

Gets the time step used in the simulation.

Returns

The time step for the simulation as a floating point number.

Parameters

timeStep

The time step to be used in the simulation.

getTimeStart

function getTimeStart()

Gets the start time for the simulation.

Returns

The start time for the simulation as a floating point number.

Parameters

timeStart

The start time for the simulation.

getTimeLength

function getTimeLength()

Gets the length of the simulation.

Returns

The length of the simulation as a floating point number.

Parameters

timeLength

The length of the simulation.

getPauseInterval

function getPauseInterval()

Gets the intervals at which to pause the simulation.

Returns

The pause interval as a floating point number. Returns undefined if a pause interval has not been specified.

Parameters

pauseInterval

The pause interval for the simulation.

getTimeUnits

function getTimeUnits()

Gets the time units of the simulation.

Returns

The time units of the simulation (e.g. “Seconds”, “Minutes”, “Days”, “Years”).

Parameters

units

The time units of the simulation (e.g. “Seconds”, “Minutes”, “Days”, “Years”).

getAlgorithm

function getAlgorithm()

Gets the algorithm for the simulation.

Returns

The algorithm for the simulation as a string. “RK1” indicates Euler’s method. “RK4” indicates a 4th order Runge-Kutta method.

Parameters

algorithm

The algorithm for the simulation. “RK1” indicates Euler’s method. “RK4” indicates a 4th order Runge-Kutta method.

getMacros

function getMacros()

Gets the macros for the insight.

Returns

The macros for the insight as a string.

Parameters

macros

The macros for the insight.

Finding and Accessing Specific Primitives

findName

function findName( name )

Finds and returns a primitive by its name. If more than one primitive with the same name exists, returns an array of primitives.

Parameters

name	The name of the primitive to return as a string. Also accepts an array of strings in which case all the primitives named in the array will be returned.

Return

A primitive. If multiple primitives exist with the same name, an array of primitives will be returned. Returns null if no primitives are found.

findAll

function findAll()

Finds and returns all primitives in the model.

Return

An array of primitives.

findType

function findType( type )

Finds and returns all primitives of a specific type.

Parameters

type	The type of primitives to return. For instance: “Stock”, “Flow”, “Link”, “Text”, “Button”, “Picture”, “Converter” or “Variable”. An array of type strings may also be passed.

Return

An array of primitives of the specified type.

findID

function findID( id )

Finds and returns a primitive using its ID.

Parameters

ID	The ID of the primitive to find. May also be an array of IDs.

Return

A primitive. If an array of IDs was passed, returns an array of primitives.

findValue

function findValue( search )

Finds and returns all primitives whose values match a regular expression.

Parameters

The regular expression to search for. Can also be a string in which case the primitive values will be tested for strict case-sensitive equality against the string. May also be an array of regular expressions and strings in which case any primitive with a value that matches one element of the array will be returned.

Return

An array of primitives whose values match the regular expression. Returns an empty array if no primitives match.

Example

// Returns all primitives that use the log function
var containingLog = findValue(/log\(/i);

// Returns all primitives whose value is strictly "1"
var isOne = findValue("1");

findNote

function findNote( search )

Finds and returns all primitives whose notes match a regular expression.

Parameters

The regular expression to search for. Can also be a string in which case the primitive notes will be tested for strict case-sensitive equality against the string. May also be an array of regular expressions and strings in which case any primitive with a note that matches one element of the array will be returned.

Return

An array of primitives whose notes match the regular expression. Returns an empty array if no primitives match.

Create and Delete Primitives

createPrimitive

function createPrimitive( name,
type,
position,
size )

Creates a new primitive and adds it to the model. This function is only for node-type primitives not connectors (e.g. flows or links).

Parameters

name	The name of the primitive to add.
type	The type of the primitive to add. For example, “Variable” or “Stock”.
position	The location of the upper-left corner of the primitive in the form: [x, y].
size	The dimensions of the primitive in the form: [width, height].

Return

The newly created primitive.

createConnector

function createConnector( name,
type,
alpha,
omega )

Creates a new connector primitive and adds it to the model.

Parameters

name	The name of the primitive to add.
type	The type of the primitive to add: “Link” or “Flow”.
alpha	The primitive that will be at the start of the connector.
omega	The primitive that will be at the end of the connector.

Return

The newly created connector primitive.

removePrimitive

function removePrimitive( primitive )

Removes a primitive from the model. You should not attempt to access or modify a primitive once it has been removed.

Parameters

primitive

The primitive to delete, can also be an array of primitives.

Primitive Selections

highlight

function highlight( primitive )

Highlights a single primitive. Selects the primitive, expands any collapsed folders the primitive is in, and scrolls to the position of the primitive.

Parameters

primitive

The primitive to highlight.

getSelected

function getSelected()

Finds and returns the currently selected primitives.

Return

An array of the selected primitives.

setSelected

function setSelected( primitives )

Sets the currently selected primitives.

Parameters

primitives

An array of primitives to select. Can also be a single primitive.

isSelected

function isSelected( primitive )

Indicates whether a primitive is selected.

Parameters

primitive

A primitive to return the selection status for. May also be an array of primitives.

Return

Whether the primitive is selected or not as a boolean. If an array of primitives was passed to the function, an array of booleans is returned.

General Primitive Functions

getID

function getID( primitive )

Gets the ID of the passed primitive. The ID remains constant even if the name of a primitive changes. The ID is a string.

Parameters

primitive

The primitive for which the ID is requested. May also be an array of primitives.

Return

The ID of the primitive as a string. If an array of primitives was passed, returns an array of IDs.

getType

function getType( primitive )

Gets the type of the passed primitive.

Parameters

primitive

The primitive for which the type is requested. May also be an array of primitives.

Return

The type of the primitive as a string. If an array of primitives was passed, returns an array of IDs.

getName

function getName( primitive )

Gets the name of the passed primitive.

Parameters

primitive

The primitive for which the name is requested. May also be an array of primitives.

Return

The name of the primitive as a string. If an array of primitives was passed, returns an array of names.

Parameters

primitive	The primitive for which the name will be set. May also be an array of primitives in which case they will all be set to the same name.
name	The new name for the primitive.

getUnits

function getUnits( primitive )

Gets the units of the passed primitive.

Parameters

primitive

The primitive for which the units are requested. May also be an array of primitives.

Return

The units of the primitive as a string. If an array of primitives was passed, returns an array of units.

Parameters

primitive	The primitive for which the units will be set. May also be an array of primitives in which case they will all be set to the same units.
units	The new units for the primitive.

getConstraints

function getConstraints( primitive )

Gets the upper and lower bounds on the passed primitive to test against during simulation.

Parameters

primitive

The primitive for which the constraints are requested. May also be an array of primitives.

Return

The constraints of the primitive as an array. The format is [MinimumConstraint, MinimumConstraintMode, MaximumConstraint, MaximumConstraintMode]. Constraint mode is false to disable the constraint and true to enable it.

Parameters

primitive	The primitive for which the units will be set. May also be an array of primitives in which case they will all be set to the same constraints.
constraints	The constraints of the primitive as an array. The format is [MinimumConstraint, MinimumConstraintMode, MaximumConstraint, MaximumConstraintMode]. Constraint mode is false to disable the constraint and true to enable it.

getNote

function getNote( primitive )

Gets the note of the passed primitive.

Parameters

primitive

The primitive for which the note is requested. May also be an array of primitives.

Return

The note of the primitive as a string. If an array of primitives was passed, returns an array of notes.

Parameters

primitive	The primitive for which the note will be set. May also be an array of primitives in which case they will all be set to the same note.
note	The new note for the primitive.

showNote

function showNote( primitive )

Shows the note for the passed primitive. The note is shown as a closable tooltip next to the primitive. If the note is empty, the note will not be shown.

Parameters

primitive

The primitive for which the note will be shown. May also be an array of primitives in which case they will all have their notes shown.

Parameters

primitive

The primitive for which the note will be hidden. May also be an array of primitives in which case they will all have their notes hidden.

showEditor

function showEditor( primitive,
annotations )

Shows the value editor for the passed primitive.

Parameters

primitive	The primitive for which the editor will be shown.
annotations	An optional array containing a list of annotations. Only valid for primitives with equations.

Example

showEditor(primitive, [{type: "error", row: 7, text: "Incorrect syntax"}])

getValue

function getValue( primitive )

Gets the value of the passed primitive. The value depends on the type of the primitive. For instance, the value of stock is its initial value while the value of a flow is its rate.

Parameters

primitive

The primitive for which the value is requested. May also be an array of primitives.

Return

The value of the primitive as a string. If an array of primitives was passed, returns an array of values.

Parameters

primitive	The primitive for which the value will be set. May also be an array of primitives in which case they will all be set to the same value.
value	The new value for the primitive. Can be a number or a string.

getSize

function getSize( primitive )

Gets the size of the passed primitive.

Parameters

primitive

The primitive for which the position is requested. May also be an array of primitives.

Return

The size as an array of the form: [width, height].

getPosition

function getPosition( primitive )

Gets the position of the passed primitive.

Parameters

primitive

The primitive for which the position is requested. May also be an array of primitives.

Return

The position as an array of the form [x, y]. The position is measured from the top-left corner of the graph.

Parameters

primitive	The primitive for which the position will be set. May also be an array of primitives in which case they will all be set to the same position.
position	The new position for the primitive in the form [x, y]. The position is measured from the top-left corner of the graph.

Primitive Styling Functions

flash

function flash( primitive,
opacity,
duration )

Temporarily changes the opacity of a primitive. Opacity between 0 (invisible) to 100 (fully opaque).

Parameters

primitive	The primitive which will be flashed. May also be an array of primitives.
opacity	Optional temporary opacity for the primitive. Defaults to 0.
duration	Optional duration the primitive will be at the temporary opacity in milliseconds. Defaults to 100.

Example

flash(getSelected());

getShowSlider

function getShowSlider( primitive )

Gets the show slider property of the passed primitive.

Parameters

primitive

The primitive for which the show slider property will be returned. May also be an array of primitives.

Return

Whether to show the slider property of the primitive. A boolean.

setShowSlider

function setShowSlider( primitive,
showSlider )

Sets the show slider property of the passed primitive.

Parameters

primitive	The primitive for which the show slider property will be set. May also be an array of primitives in which case they will all be set to the same show slider value.
showSlider	Boolean whether to show the slider.

getSliderMin

function getSliderMin( primitive )

Gets the slider min property of the passed primitive.

Parameters

primitive

The primitive for which the slider min property will be returned. May also be an array of primitives.

Return

The minimum allowed value for the slider

setSliderMin

function setSliderMin( primitive,
sliderMin )

Sets the slider min property of the passed primitive.

Parameters

primitive	The primitive for which the slider property will be set. May also be an array of primitives in which case they will all be set to the same slider value.
sliderMin	The minimum value of the slider.

getSliderMax

function getSliderMax( primitive )

Gets the slider max property of the passed primitive.

Parameters

primitive

The primitive for which the slider max property will be returned. May also be an array of primitives.

Return

The maximum allowed value for the slider

setSliderMax

function setSliderMax( primitive,
sliderMax )

Sets the slider max property of the passed primitive.

Parameters

primitive	The primitive for which the slider property will be set. May also be an array of primitives in which case they will all be set to the same slider value.
sliderMax	The maximum value of the slider.

getSliderStep

function getSliderStep( primitive )

Gets the slider step property of the passed primitive.

Parameters

primitive

The primitive for which the slider property will be returned. May also be an array of primitives.

Return

The step value for the slider

setSliderStep

function setSliderStep( primitive,
sliderStep )

Sets the slider step property of the passed primitive.

Parameters

primitive	The primitive for which the slider property will be set. May also be an array of primitives in which case they will all be set to the same slider value.
sliderStep	The step value of the slider.

getOpacity

function getOpacity( primitive )

Gets the opacity of the passed primitive. Opacity is a value between 0 (invisible) to 100 (fully opaque).

Parameters

primitive

The primitive for which the opacity will be returned. May also be an array of primitives.

Return

The opacity of the primitive

setOpacity

function setOpacity( primitive,
opacity )

Sets the opacity of the passed primitive. Opacity is a value between 0 (invisible) to 100 (fully opaque).

Parameters

primitive	The primitive for which the opacity will be set. May also be an array of primitives in which case they will all be set to the same opacity.
opacity	The new opacity for the primitive.

getLineColor

function getLineColor( primitive )

Gets the line color of the passed primitive.

Parameters

primitive

The primitive for which the line color will be returned. May also be an array of primitives.

Return

The line color of the primitive

setLineColor

function setLineColor( primitive,
lineColor )

Sets the line color of the passed primitive.

Parameters

primitive	The primitive for which the line color will be set. May also be an array of primitives in which case they will all be set to the same color.
lineColor	The new line color for the primitive.

getFontColor

function getFontColor( primitive )

Gets the font color of the passed primitive.

Parameters

primitive

The primitive for which the font color will be returned. May also be an array of primitives.

Return

The font color of the primitive

setFontColor

function setFontColor( primitive,
fontColor )

Sets the font color of the passed primitive.

Parameters

primitive	The primitive for which the font color will be set. May also be an array of primitives in which case they will all be set to the same color.
fontColor	The new font color for the primitive.

getFillColor

function getFillColor( primitive )

Gets the fill color of the passed primitive.

Parameters

primitive

The primitive for which the fill color will be returned. May also be an array of primitives.

Return

The fill color of the primitive

setFillColor

function setFillColor( primitive,
fillColor )

Sets the fill color of the passed primitive.

Parameters

primitive	The primitive for which the fill color will be set. May also be an array of primitives in which case they will all be set to the same color.
fillColor	The new fill color for the primitive.

getImage

function getImage( primitive )

Gets the image of the passed primitive.

Parameters

primitive

The primitive for which the image will be returned. May also be an array of primitives.

Return

The image of the primitive as a string

setImage

function setImage( primitive,
image )

Sets the image of the passed primitive.

Parameters

primitive	The primitive for which the image will be set. May also be an array of primitives in which case they will all be set to the same image.
image	The image url or alias as a string.

Stocks

getNonNegative

function getNonNegative( primitive )

Gets the non-negative property of stocks (also applicable to flows). A non-negative stock will never become negative.

Parameters

primitive

The stock for which the value is requested. May also be an array of stock.

Return

The non-negative value of the stock. If an array of primitives was passed, returns an array of values.

Parameters

primitive	The stock for which the non-negative value will be set. May also be an array of stocks in which case they will all be set to the same value.
nonNegative	The new non-negative status for the stock. Either true or false.

getStockType

function getStockType( primitive )

Gets the type of the stock. The type affects the behavior of the stock and may either be “Store” (the default) or “Conveyor”.

Parameters

primitive

The stock for which the type is requested. May also be an array of stocks.

Return

The type of the stock as a string. If an array of stocks was passed, returns an array of strings.

Parameters

primitive	The stock for which the type will be set. May also be an array of stocks in which case they will all be set to the same type.
type	The type of the stock as a string. Either “Store” (the default) or “Conveyor”.

getDelay

function getDelay( primitive )

Gets the delay length of conveyor stocks.

Parameters

primitive

The stock for which the value is requested. May also be an array of stocks.

Return

The delay length of the stock. If an array of stocks was passed, returns an array of lengths.

Parameters

primitive	The stock for which the delay length will be set. May also be an array of stocks in which case they will all be set to the same value.
delay	The delay length for the stock.

Connectors

See getNonNegative and setNonNegative for setting the only-positive property of flows.

getEnds

function getEnds( connector )

Gets the alpha and omega for the connector

Parameters

connector

The connector for which the ends are requested. Can also be an array of connectors.

Return

The alpha and omega as an array: [alpha, omega]. Array elements are returned as null if no connection exists.

Parameters

connector	The connector for which the alpha and omega will be set. May also be an array of connectors.
ends	The new alpha and omega for the connector as an array: [alpha, omega]. Use null for either alpha or omega to disconnect an end.

connected

function connected( primitive1,
primitive2 )

Determines two primitives are connected by a link, flow, or transition. Alternatively if one of the primitives is a connector, checks if it connects directly to the other primitive.

Parameters

primitive1	A primitive.
primitive2	A primitive to test whether it is connected to primitive1.

Return

A boolean. True if the primitives are connected, false otherwise.

States

getResidency

function getResidency( state )

Gets the residency property of a state primitive.

Parameters

state

The state for which the residency property is requested. May also be an array of states.

Return

The residency property as a string.

Parameters

state	The state primitive for which the residency property will be set. May also be an array of states.
residency	The new value for the residency property.

Transitions and Actions

getTriggerType

function getTriggerType( primitive )

Gets the trigger type of a transition or action.

Parameters

primitive

The transition or action for which the trigger is requested. May also be an array of transitions or actions.

Return

The trigger mode as a string. May be “Timeout”, “Probability” or “Condition”.

Parameters

primitive	The transition or action for which the trigger will be set. May also be an array of transitions or actions.
trigger	The new trigger for the transition or action. May be “Timeout” “Probability” or “Condition”.

getTriggerValue

function getTriggerValue( primitive )

Gets the trigger value equation of a transition or action.

Parameters

primitive

The transition or action for which the trigger value equation is requested. May also be an array of transitions or actions.

Return

The trigger value equation as a string.

Parameters

primitive	The transition or action for which the trigger will be set. May also be an array of transitions or actions.
value	The new trigger value equation as a string.

getTriggerRepeat

function getTriggerRepeat( primitive )

Gets the trigger Repeat property of a transition or action.

Parameters

primitive

The transition or action for which the property is requested. May also be an array of transitions or actions.

Return

The trigger Repeat property as a boolean.

Parameters

primitive	The transition or action for which the Repeat property will be set. May also be an array of transitions or actions.
repeat	A boolean determining whether to repeat the trigger

getTriggerRecalculate

function getTriggerRecalculate( primitive )

Gets the trigger Recalculate property of a transition or action.

Parameters

primitive

The transition or action for which the property is requested. May also be an array of transitions or actions.

Return

The trigger Recalculate property as a boolean.

Parameters

primitive	The transition or action for which the Recalculate property will be set. May also be an array of transitions or actions.
recalculate	A boolean determining whether to recalculate each time step

Converters

getData

function getData( converter )

Gets the data of a converter.

Parameters

converter

The converter for which the data is requested. May also be an array of Converters.

Return

The Converter data as a string. A set of input/output pairs separated by semicolons. Example data form: “1,1;2,4;3,9”

Parameters

converter	The converter for which the data will be set. May also be an array of Converters in which case they will all be set to the same value.
data	The data for the converter as a string. A set of input/output pairs separated by semicolons. Example data form: “1,1;2,4;3,9”

getConverterInput

function getConverterInput( converter )

Gets the input source of a converter.

Parameters

converter

The converter for which the input source is requested. May also be an array of Converters.

Return

The input source. If the input source is a primitive, returns the primitive. Otherwise returns null (indicating the use of time as the input source).

setConverterInput

function setConverterInput( converter,
input )

Sets the input source of a converter.

Parameters

converter	The converter for which the input source will be set. May also be an array of Converters in which case they will all be set to the same value.
input	The input source. Pass either a primitive or use null to indicate the usage of time as the input.

getInterpolation

function getInterpolation( converter )

Gets the interpolation mode of a converter.

Parameters

converter

The converter for which the interpolation is requested. May also be an array of Converters.

Return

The interpolation mode as a string. May be “Linear” or “Discrete”.

Parameters

converter	The converter for which the interpolation will be set. May also be an array of Converters in which case they will all be set to the same value.
interpolation	The interpolation mode for the converter as a string. May either be “Linear” or “Discrete”.

Buttons

pressButton

function pressButton( button )

Simulates a press of the passed button(s) firing its action. Can be useful for chaining together methods.

Parameter

button

The button to be pressed. Can also be an array of buttons.

Agents

getPopulationSize

function getPopulationSize( agents )

Gets the size of the agent population.

Parameters

agents

The agent population for which the size will be returned. May also be an array of agent populations.

Return

The population size.

Parameters

agents	The agent population for which the size will be set. May also be an array of agent populations.
size	The new population size.

getAgentBase

function getAgentBase( agents )

Gets the base agent for the population.

Parameters

agents

The agent population for which the base agent will be returned. May also be an array of agent populations.

Return

The base agent folder.

Parameters

agents	The agent population for which the base agent will be set. May also be an array of agent populations.
folder	The base agent folder. The type for this folder should be set to “Agent”.

getGeometryWrap

function getGeometryWrap( agents )

Whether the geometry should wrap across edges.

Parameters

agents

The agent population for which the geometry wrap property will be returned. May also be an array of agent populations.

Return

The wrap property as a boolean

Parameters

agents	The agent population for which geometry wrap property will be set. May also be an array of agent populations.
wrap	The wrap property for the geometry.

getGeometryUnits

function getGeometryUnits( agents )

Gets the units for the population area geometry.

Parameters

agents

The agent population for which the units will be returned. May also be an array of agent populations.

Return

The units as a string

Parameters

agents	The agent population for which geometry units will be set. May also be an array of agent populations.
units	The units as a string.

getGeometryWidth

function getGeometryWidth( agents )

Gets the width for the population area geometry.

Parameters

agents

The agent population for which the width will be returned. May also be an array of agent populations.

Return

The width of the geometry

Parameters

agents	The agent population for which geometry width will be set. May also be an array of agent populations.
width	The desired width.

getGeometryHeight

function getGeometryHeight( agents )

Gets the height for the population area geometry.

Parameters

agents

The agent population for which the height will be returned. May also be an array of agent populations.

Return

The height of the geometry

Parameters

agents	The agent population for which geometry height will be set. May also be an array of agent populations.
height	The desired height.

getAgentPlacement

function getAgentPlacement( agents )

The placement method for the agent population.

Parameters

agents

The agent population for which the placement method will be returned. May also be an array of agent populations.

Return

The placement method for the agent population. One of “Random”, “Network”, “Grid” or “Custom Function”.

Parameters

agents	The agent population for which placement method will be set. May also be an array of agent populations.
method	The desired placemennt method. One of “Random”, “Network”, “Grid” or “Custom Function”.

getAgentPlacementFunction

function getAgentPlacementFunction( agents )

A custom placement function for the agent population.

Parameters

agents

The agent population for which the custom placement function will be returned. May also be an array of agent populations.

Return

The custom placement function for the agent population.

Parameters

agents	The agent population for which the custom placement function will be set. May also be an array of agent populations.
func	The desired custom placement function.

getAgentNetwork

function getAgentNetwork( agents )

The network method for the agent population.

Parameters

agents

The agent population for which the network method will be returned. May also be an array of agent populations.

Return

The network method for the agent population. One of “None” or “Custom Function”.

Parameters

agents	The agent population for which network method will be set. May also be an array of agent populations.
method	The desired placement method. One of “None” or “Custom Function”.

getAgentNetworkFunction

function getAgentNetworkFunction( agents )

A custom network function for the agent population.

Parameters

agents

The agent population for which the custom network function will be returned. May also be an array of agent populations.

Return

The custom network function for the agent population.

Parameters

agents	The agent population for which the custom network function will be set. May also be an array of agent populations.
func	The desired custom network function.

Folders

collapseFolder

function collapseFolder( folder )

Collapses a folder or an array of folders.

Parameter

folder

Either a single folder primitive or an array of folder primitives.

expandFolder

function expandFolder( folder )

Expands a folder or an array of folders.

Parameter

folder

Either a single folder primitive or an array of folder primitives.

getCollapsed

function getCollapsed( folder )

Returns whether or not a given folder is collapsed.

Parameter

folder

The folder for which the collapsed state is requested.

Return

True is the folder is collapsed, false if it is expanded.

getParent

function getParent( primitive )

Gets the parent folder for a primitive.

Parameters

primitive

The primitive for which the parent folder will be returned. May also be an array of primitives.

Return

The parent folder. Returns null if the primitive is not in a folder.

Parameters

primitive	The primitive for which the parent folder will be set. May also be an array of primitives in which case they will all be set to the same parent.
parent	The parent folder primitive. Use null to remove the primitive from all folders.

getFrozen

function getFrozen( primitive )

Gets the frozen state for a primitive.

Parameters

primitive

The primitive for which the frozen will be returned. May also be an array of primitives.

Return

The frozen state for the primitive.

Parameters

primitive	The primitive for which the frozen state will be set. May also be an array of primitives in which case they will all be set to the same frozen state.
frozen	The new frozen state for the primitive.

getChildren

function getChildren( folder,
recursive )

Returns the children of a folder.

Parameters

folder	The folder for which the children will be returned.
recursive	Optional. Whether the children of inner folders will be returned. Defaults to true.

Return

The children primitives of the folder.

getFolderType

function getFolderType( folder )

Gets the type of a folder.

Parameters

folder

The folder for which the type is requested. May also be an array of folders.

Return

The type mode as a string. May be “None” or “Agent”.

Parameters

folder	The folder for which the type will be set. May also be an array of folders.
type	The type mode as a string. May be “None” or “Agent”.

getFolderAgentParent

function getFolderAgentParent( folder )

Gets the agent parent of a folder.

Parameters

folder

The folder for which the agent parent is requested. May also be an array of folders.

Return

The agent parent as a string.

Parameters

folder	The folder for which the type will be set. May also be an array of folders.
agentParent	The agent parent as a string.

getFolderSolver

function getFolderSolver( folder )

Gets the solver configuration for a folder. The configuration is an object with the properties

enabled	true is the folder should have its own solver
algorithm	the solution algorithm. Current allowed values are “RK1” for Euler’s method and “RK4” for a fourth order Runge-Kutta method
timeStep	the time step for the folder’s solver

Parameters

folder

The folder for which the solver is requested. May also be an array of folders.

Return

The solver object

Parameters

folder	The folder for which the solver will be set. May also be an array of folders.
solver	The solver object

Utility Functions

excludeType

function excludeType( array,
type )

Removes a specific type of primitive from an array of primitives.

Parameter

array	An array of primitives.
type	The type of primitives to remove (e.g. “Flow” or “Stock”). May also be an array of types.

Return

A duplicate of the input array without any primitives of the specified type.

primitiveIndex

function primitiveIndex( array,
primitive )

Locates the index of a specific primitive in an array of primitives.

Parameter

array	An array of primitives.
primitive	The specific primitive to find.

Return

The index of the primitive in the array. Returns -1 if the primitive is not found.

uniquePrimitives

function uniquePrimitives( primitives )

Returns the passed array with duplicated primitives removed

Parameter

primitives

An array of primitives.

Return

An array of primitives with any duplicated elements removed.

setGlobal

Sets the value of a global variable. This can allow communication between buttons or the storing of some state.

Parameter

name	The name of the global variable.
value	The value of the global variable.

Parameter

name	The name of the global variable for which to get the value.

Return

The value of the global variable specified by name.

Example

setGlobal("Example Var 1", 42);
setGlobal("Example Var 2", "test");
var z = getGlobal("Example Var 1"); // z is now set to 42
var y = getGlobal("Example Var 2"); // y is now set to "test"

Insight Maker Interface

topBarShown

function topBarShown()

Determines whether or not the Insight Maker top toolbar (which contains the Run Simulation button and other tools) is currently shown.

Return

True if the top toolbar is shown, false otherwise.

sideBarShown

function sideBarShown()

Determines whether or not the Insight Maker side panel (which contains parameter sliders and information about the selected primitive) is currently shown.

Return

True if the side panel is shown, false otherwise.

updateSideBar

function updateSideBar()

Refreshes the values in the side panel to reflect any changes in the model.

Insight Maker API

Introduction

Primitive Types

Examples

Using Dialogs

Expanding and Collapsing Folders

Notes

Using Opacity

Rabbit Birth Rate

Building a Model

Manipulating a Model in an IFRAME

Dialogs and User Input

showMessage

Parameters

See also

showPrompt

Parameters

Returns

See also

showChoice

Parameters

Returns

See also

showURL

Parameters

downloadFile

Parameters

showData

Parameters

Tab Objects

Text Tab

HTML Tab

Table Tab

Returns

Example

frontWindow

Returns

closeAllWindows

openFile

Parameters

Returns

If config.multiple is false, these results are a single file object. If config.multiple is true, then these results are an array of file objects. Each file object has the following properties

Examples

General Model Functions

runModel

Parameters

Returns

Examples

saveModel

Parameters

clearModel

layoutModel

Parameters

setZoom

Parameters

Simulation Settings

getTimeStep

Returns

See also

setTimeStep

Parameters

See also

getTimeStart

Returns

See also

setTimeStart

Parameters

See also

getTimeLength

Returns

See also

setTimeLength

Parameters

See also

getPauseInterval

Returns

See also

setPauseInterval

Parameters

See also