Advanced Simulation Features

Scripts

The simulator has three JavaScript functions, shown below, which are called during execution and can be overridden by the user to run custom scripts. A script can have one or all three of these functions in addition to any other helper functions necessary.

Each of these functions executes at a different time during the course of a construct being executed. The “onStart” function is executed after all the ‘Input/Output’ triggers have been completed but before any ‘Resource’ consumption and/or Asset utilization. The “prompt” function is executed after the ‘Resource’ consumption and/or Asset utilization but before the construct begins its Duration. The “onEnd” function executes after the construct’s Duration has ended.

Note: Any other functions must be called from within one of these three functions or they will not be executed by the simulator.

Predefined Scripts

‘LOOP’ and ‘OR’ constructs have a special ‘Edit Script’ dialog which gives the user the option to choose one of the predefined scripts in addition to the option to write a custom script. The available predefined scripts include “Loop Probability,” “Loop Iterations,” and “Loop Resource.” These predefined scripts allow the user to quickly create a script for three of the most common use cases without having to write any code.

• Loop Probability Script

  When added to a ‘LOOP’ (shown below), this predefined script allows the user to assign the probability the ‘LOOP’ will continue or exit. When added to an ‘OR,’ it allows the user to assign the probability that each branch of the ‘OR’ will be executed.

  

• Loop Iterations Script

  When added to a ‘LOOP,’ this predefined script allows the user to assign exactly how many times the ‘LOOP’ will continue before it exits.

  

• Loop Resource Script

  When added to a ‘LOOP’ (shown below), this predefined script allows the user to assign a condition on a ‘Resource’ which will cause the ‘LOOP’ to exit when the condition has been met. When added to an ‘OR,’ it allows the user to assign a condition on a ‘Resource’ for each branch of the ‘OR’ so that when the condition has been met, that particular branch of the ‘OR’ will execute.

  

Scripting Prompts

Prompts allow the simulator to get input directly from the user. A prompt will cause the simulator to wait until input from the user has been received. Prompts are used in ‘OR’ and ‘LOOP’ constructs if no scripts are found and the simulator is in “Prompt Mode.” Prompts can be created by using one or more of these functions inside the “prompt” function. The title variable sets the title of the prompt. The name variable is the key that the response from the user will be stored under. The choices variable is the array of options for the user to choose from. The value variable is the default value entered in the prompt field. Below is a table of the types of prompts available to be scripted:

The “onEnd” function will receive the response from a scripted prompt in the form of a map. Below is an example of a simple prompt script that prompts for the user’s name and then prints their name from the response map to the web browser’s console within the “onEnd” function:

Simulator Scripting API

The simulator has a scripting API to allow users to gain access to data contained in the model being executed. The table below identifies each of the functions available in the API and what they return:

Distributions

Distributions are vital in making a computer model more accurately represent a real-world system. Innoslate natively supports eight continuous distributions (Beta, Exponential, Gamma, Log-Normal, Normal, Triangular, Uniform, and Weibull) and two discrete distributions (Binomial and Poisson). Any of these distributions can be used in place of a simple value in any attribute of an entity or relationship which is of the type Number in your project’s database schema.

During a simulation run, Innoslate will use the distribution on an attribute to generate a random number for that attribute that falls within the bounds of the distribution. For example, when using a Uniform distribution where a = 15 and b = 20, the simulator could return a value of 16.835 in the first simulation run and a value of 19.015 in the second simulation run.

Adding a Distribution

Distributions can be added to any attribute of Number or Duration type, such as an Action class’s Duration or the Initial, Minimum, or Maximum Amount of a Resource. To add distribution to an attribute just start by typing in an “=”.  You will see a drop-down list of the supported distributions appear that you can select from.

More information on each of the supported distributions including parameters and common uses can be found below:

Continuous Distributions

Each distribution has a plot of the distribution with multiple parameter options shown. The plot has an x value along the horizontal axis and the associated Probability Density Function (PDF) along the vertical axis. A higher PDF implies there will be a larger concentration of random numbers which fall within a given x range. Information on calculating the probability of a random number falling within a given range can be found at: http://en.wikipedia.org/wiki/Probability_density_function

During simulation Innoslate will return a random real value, x, such that a set of the values when plotted as a histogram will produce a shape nearing the shape of the distribution.

Beta Distribution

The Beta distribution is useful for generating a continuous random distribution between the fixed bounds of 0 and 1. The Beta distribution is best for predicting probabilities, calculating failure rates, or time allocation. For more information, see http://en.wikipedia.org/wiki/Beta_distribution.

Exponential Distribution

The Exponential distribution describes the time intervals between a Poisson process. The return value, x, returns the next random interval between Poisson events. The Exponential distribution is best for describing the time between customer arrivals, service times, or time until the next particle decay. For more information, see http://en.wikipedia.org/wiki/Exponential_distribution.

Gamma Distribution

The Gamma distribution has many different uses including modeling the time required for k events to occur in a Poisson process, modeling waiting times, or resource consumption. For more information, see http://en.wikipedia.org/wiki/Gamma_distribution.

Note the Gamma distribution has two common formats. Innoslate uses the format of Gamma(k, θ) where k is the shape and θ is the scale. The second format is Gamma(α, β) where α is the shape and β is the rate. This second format can be transformed into the first format using the following equations: k = α, θ = 1/β

Log-Normal Distribution

The Log-Normal distribution generates a number equal to eN(μ, σ), where N(μ, σ) is a Normal distribution. The Log-normal distribution is best for describing the volume of gas in a reserve, incubation periods, or system repair time. For more information, see http://en.wikipedia.org/wiki/Log-normal_distribution.

Normal Distribution

The Normal distribution returns a value that will 95% of the time fall within 2 standard deviations (σ) of the mean (μ). This distribution is best for modeling natural processes, task completion time, or randomness of characteristics. For more information, see http://en.wikipedia.org/wiki/Normal_distribution.

Triangular Distribution

The Triangular distribution is best used when a minimum, maximum, and most likely outcome are known; providing basic randomness; or early estimation of task completion time. For more information, see http://en.wikipedia.org/wiki/Triangular_distribution.

Uniform Distribution

The Uniform distribution is commonly used in risk analysis, to calculate an unknown wait time, or randomly choose a selection in a set. For more information, see http://en.wikipedia.org/wiki/Uniform_distribution_(continuous).

Weibull Distribution

The Weibull distribution is a very versatile distribution, with the ability to be right-skewed, left-skewed, or symmetric. Due to this ability, the Weibull distribution is often used to model component reliability or characteristics, an increase or decrease in capability, or a system’s lifetime. For more information, see http://en.wikipedia.org/wiki/Weibull_distribution.

Discrete Distributions

Each distribution has a plot of the distribution with multiple parameter options shown. The plot has a k value along the horizontal axis and the associated Probability Mass Function (PMF) along the vertical axis. A higher PMF implies there will be a larger concentration of random numbers which fall on a specific value. Information on calculating the probability of a random number falling within a given range can be found at: http://en.wikipedia.org/wiki/Probability_mass_function

During simulation Innoslate will return a random whole value, k, such that a set of the values when plotted as a bar graph will produce a shape nearing the shape of the distribution.

Binomial Distribution

The Binomial distribution models the number of successes from n independent trials where there is the same probability p of success in each trial. The Binomial distribution is best for counting the number of part failures based on n attempts, the number of failures generated from a repeated process, or the number of successful transmissions between wireless devices. For more information, see http://en.wikipedia.org/wiki/Binomial_distribution.

Poisson Distribution

The Poisson distribution models the number of events occurring over an interval of time, where λ is the mean number of events in that interval. Common uses of the Poisson distribution include counting the number of arrivals per day, ideal vehicle distance in traffic flow, or counting the number of resources needed to be consumed. For more information, see http://en.wikipedia.org/wiki/Poisson_distribution.

Controls

Innoslate offers additional simulator capabilities, which allow a user to further control and/or customize model execution.

Asset Utilization

Asset Utilization prevents over-allocating a particular ‘Asset’ to an ‘Action.’ Asset Utilization will capture an ‘Asset’ until an ‘Action’ has completed execution. The usage of each ‘Asset’ is monitored during the simulation and graphically displayed in the simulation results.

To control simulation flow, each ‘Asset’ utilized must have a parent ‘Asset.’ Typically, an Innoslate model will have a Physical Hierarchy of ‘Assets.’ ‘Assets’ in this hierarchy have a Multiplicity relationship attribute. If the ‘Asset’ is part of this hierarchy and the Multiplicity relationship attribute is set then the ‘Asset’ can be utilized. To utilize an ‘Asset,’ set the Amount attribute on the performed by relationship. In the simulation, if an ‘Asset’ is over-utilized then the simulator will block all other ‘Actions’ that ‘Asset’ performs until an adequate amount is available.

Capacity

Innoslate can simulate throughput and latency utilizing the Conduit class. A Conduit transfers/transferred by an Input/Output. The simulated delay of an Input/Output is equal to the Size of the Input/Output over the Capacity of the Conduit which transfers the Input/Output plus the Latency of the Conduit. This is expressed in the equation below:

For example, if the Input/Output Size is 20, the Conduit Capacity is 5, and the Conduit Latency is 2 hours the duration will be as follows.

The time units of the Input/Output Size over Conduit Capacity conversion will default to hours. The simulator can also automatically convert and calculate units by utilizing the time units following a slash (“/”) in the Conduit’s Unit attribute.  If the time units equal “s” or “sec” or “seconds” then the delay units will equal seconds.  If the time units equal “m” or “min” or “minutes” then the delay units will be equal to minutes.  If there is no slash (“/”) or the time units are not understood, the time units will be hours. For example, if the Conduit Latency is 1 minute, the Conduit Capacity is 100, the Conduit Units are gallons/second, and the Input/Size is 500 then the resultant Duration will equal 65 seconds (500/100 seconds + 1 minute).

Note: If an Input/Output is transferred by multiple Conduits the simulator will output a warning message to the ‘Console’ panel.

Cloning

Cloning creates copies of an existing Action and its decomposition at simulation run-time. The simulator will copy an Action and execute each copy as if each copy was its own parallel branch. The number of clones can be set by modifying the decomposes/decomposed by Multiplicity relationship attribute. To set this attribute select the Action to be cloned in the ‘Action Diagram’ and click the ‘Open’ drop-down and then select the ‘Entity View’ menu item to navigate to the Action’s ‘Entity View.’ Then click the ‘Attributes’ button under the decomposes/decomposed by relationship. Set the relationship’s Multiplicity attribute to the number of clones desired.

Cost

Total Cost will be automatically calculated based on the incurs/incurred by relationship during a simulation run. A Cost’s Amount is added to the simulation’s total running costs. If an entity has multiple incurs Cost relationships the simulator will add the costs individually.

The simulator can calculate “Fixed” or “Per Hour” costs by setting the ‘Rate’ attribute. If ‘Rate’ equals “Fixed” then the cost will be added to the simulation’s cost at the value specified regardless of the duration of the associated model element. If ‘Rate’ equals “Per Hour” then the Cost’s Amount will be multiplied by the duration of the model element. Below is the equation representation of this.

Note: The Units of the first Cost the simulator encounters will be used as the units for that simulation run.

Simulation Scripts

Scripts are a powerful method of controlling the underlying functional logic of a simulation written in JavaScript. Each script is unique to a given Action entity and only interacts with other scripts via global variables. Script entry is done in the ‘Edit Script’ dialog, accessed by clicking on the ‘Script’ button when you have an ‘Action’ selected in an ‘Action Diagram.’

For more information on how to script the simulator, see Simulation Scripts.

Wait States

The simulator panels utilize colors to identify the Action’s state during simulation. The table below identifies each state and its appropriate color.

To continue learning about Simulators, Click Here.

(Next Article: Innoslate Scripting Guide)