Understanding the Power of Advanced Simulation Features: Harnessing Scripts, Distributions, and Controls for Precise Modeling and Analysis
Sections Available in Advanced Simulator Features
Function | Description |
---|---|
Scripts | Explore the power of scripts, allowing you to automate and customize simulations over system behavior and event sequences through action entities. |
Distributions | Utilize a wide range of supported probability distributions, enabling you to accurately model uncertainties and variations within your simulations. |
Controls | Take advantage of simulation controls in Innoslate, providing you with precise management and manipulation of simulation parameters, and etc. |
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:
Function | Description |
---|---|
addEnumInput(title, name, choices, value) | Prompts the user to choose from a set of predefined choices. |
addTextInput(title, name, value) | Prompts the user to enter text. |
addBigtitleTextInput(title, name, value) | Prompts the user to enter a large amount of text. |
addNumberInput(title, name, value) | Prompts the user to enter a number. |
addBooleanInput(title, name, value) | Prompts the user to choose from True or False. |
setTitle(title) | Sets the title of the prompt. |
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:
Function | Description |
---|---|
Sim.getEntitiesByNumber(number) | Returns a list of entities based on the entity’s number. |
Sim.getEntityByNumber(number) | Returns the first entity result based on the entity’s number. |
Sim.getEntitiesByName(name) | Returns a list of entities based on the entity’s name. |
Sim.getEntityByName(name) | Returns the first entity result based on the entity’s name. |
Sim.get(name) | Short-hand alias for GetEntityByName. |
Sim.getEntityById(id) | Returns an entity based on its id. |
Sim.setResourceByName(name, amount) | Sets the resource’s current amount based on the resource’s name. |
Sim.setResourceById(id, amount) | Sets the resource’s current amount based on the resource’s id. |
Sim.getResourceByName(name) | Returns the first resource based on its name. |
Sim.getAmount(name) | Returns the resource amount based on the resource’s name. |
Sim.getAmountById(id) | Returns the resource amount based on the resource’s id. |
Sim.getCurrentCost() | Returns the current cost of the simulation. |
Sim.getIOValueByNumber() | Returns the Input/Output value attribute based on entity number. |
Sim.getIOValueById() | Returns the Input/Output value attribute based on entity id. |
Sim.getIOValueByGlobalId() | Returns the Input/Output value attribute based on entity global id. |
Sim.getCurrentTime() | Returns the current time of the simulation. |
Sim.httpGet(url) | Allows the user to do a synchronous GET request which will get data from an external server. |
Sim.httpPost(url) | Allows the user to do a synchronous POST request which will create data on an external server. |
Sim.httpPut(url) | Allows the user to do a synchronous PUT request which will update data on an external server. |
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.
Color | State | Description |
---|---|---|
Gray | Inactive | The Action was not activated or has been killed by a SYNC point. |
Yellow | Input/Output Wait | The Action is waiting for an Input/Output(s). |
Purple | Resource Wait | The Action is waiting for a Resource Amount(s). |
Orange | Asset Utilization Wait | The Action is waiting for enough Asset performers to execute. |
Maroon | Cloning Operation | The Action is currently being executed through a cloning operation. |
Green | Executing | The Action is currently executing. |
Blue | Complete | The Action has completed execution. |
To continue learning about Simulators, Click Here.
(Next Article: Innoslate Scripting Guide)