Simulation

The Simulator executes the flow of an Action, as drawn in its Action Diagram, over simulated time. It runs in two modes:

• Discrete Event: one timed run that you can watch, step through and answer decisions in. It shows which actions run when, what they wait for, how resources rise and fall, which assets are busy and what the run costs.
• Monte Carlo: many independent runs with sampled durations and decisions. It shows the spread of total time and cost, percentiles, a cumulative probability curve, the decision paths taken and the probability of meeting a threshold.

The Simulator reads the model; it never changes it while running. Only three actions write to the project: Save Settings, Export Results… and Record Result….

Concepts

What the Simulator reads

Times are kept in seconds and shown in the most readable unit (ms, sec, min, hr, days, months or years).

Durations and distributions

• A Duration is a value and a unit (Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Years). A value with no unit is read as hours.
• The value can be a fixed number or a distribution such as =norm.dist(40, 6) or =triang.dist(4, 9, 6). Distributions are sampled on every execution. Sampled negative durations are drawn again, so a normal distribution behaves as if truncated at 0. See Attribute Types and Distributions for the ten distributions (beta, binomial, exponential, gamma, log normal, normal, Poisson, triangular, uniform, Weibull).
• Fixed-duration variation (a setting) adds spread to fixed numbers only: Uniform ±% samples evenly within ± the percentage, Triangular ±% samples a triangle peaking at the fixed value. Distributions are never varied further.
• A Duration whose distribution type is script calls the action's duration() hook.

Control constructs

OR decision types:

• Probability: each branch has a probability (%). Branches left blank share what remains of 100% equally; if every probability is 0, each branch is equally likely.
• Resource condition: each branch compares the current amount of the chosen Resource (==, !=, >, <, >=, <=); the first branch whose condition holds is taken, else the branch marked else.
• Script: the construct's onEnd() returns the name of the branch to take (or its index). An unknown name logs a warning and a random branch is taken.
• None (prompt or random): with Decisions set to Prompt on no script, a dialog asks which path to take; otherwise a branch is picked at random.

LOOP continue conditions:

• Iterations: a fixed number of passes (at least 1).
• Probability: before each pass, continue with this probability (%).
• Resource condition: continue while the Resource amount meets the comparison.
• Script: onEnd() is called before each pass; true runs the body again, false stops, and a number sets how many more passes to run.
• None (prompt or random): in prompt mode a dialog asks for the Number of Iterations: (default 3); otherwise 0, 1 or 2 passes at random.

Resources

• A Resource has Initial Amount, Minimum Amount, Maximum Amount and Units. The initial amount is clamped to the minimum and maximum.
• consumes: the amount is taken when the action starts and not returned.
• seizes: the amount is taken when the action starts and released when it ends.
• produces: the amount is added when the action ends. Amounts above the maximum are capped.
• An action that needs more than is available (the amount would fall below the Minimum Amount, or below 0 when no minimum is set) waits until other actions release or produce enough. Its Gantt bar shows a purple hatched wait.

Assets and utilization

• Every Asset that performs an action (performed by) is busy while the action runs. Busy (%) is the share of the simulated time in which at least one of its actions ran.
• Set an Amount on the performed by relationship to model capacity. The asset's capacity is the upper bound of the Multiplicity on its parent's decomposed by relationship (for example 0..2 gives 2). An action waits while the asset has no free capacity (orange hatched wait). With no Multiplicity, capacity is unlimited.

Costs

• A Cost entity has Amount, Rate and Units. With Rate Per Hour, the amount is multiplied by the action's duration in hours; otherwise it is charged once when the action ends.
• A Cost incurred by a performing Asset is charged for each action it performs, multiplied by the performed by Amount (1 when unset).
• The units of the first Cost found label every cost figure.

Random numbers and seeds

• Random seed makes a run repeatable. Leave it blank for a new random sequence each time.
• In Monte Carlo, each run draws its own seed from the study's seed, so any single run can be replayed in Discrete Event mode with View Run.
• Math.random() in scripts uses the same seeded generator.

How to use it

When and why

Simulate after the functional flow exists and its actions have durations, performers and resources, typically after functional analysis and during allocation and architecture trades. A simulation answers:

• How long does the operation take, and how much does the time vary?
• Which actions are on the critical path, and where do they wait (for data, resources or asset capacity)?
• Do resources such as battery charge or data storage stay within limits?
• Which assets are overloaded?
• What is the probability that a performance requirement (time, cost, a resource level) is met? This becomes a verification-by-analysis result linked to the requirement.

Run a Discrete Event simulation

1. Open the Action Diagram of the operation and choose ▶ Simulate ▾ → Discrete Event. Other ways in: Behavior → Simulator in the navigation rail, then choose the Root Action; or an Action's Open ▾ → Simulator.
2. Check the settings row: Decisions (Automate with no script or Prompt on no script), Speed, Fixed-duration variation and ± %, Random seed, Calendar Mode.
3. Press ▶ Play. The clock runs, the Action Trace panel colors actions green while they run, orange while they wait and grey when finished, and the Gantt Chart grows.
4. Press ⏸ Pause to stop and inspect. Press ⏭ Step to advance to the next event, or ⏩ Run to End to finish without animation.
5. When a dialog titled Prompt: … appears, choose the path or enter the value and click OK. The run continues as before (playing, stepping or running to the end).
6. Read Status (it shows 100% Complete, Deadlock or Stopped), Total Time, Total Cost, the resource and utilization panels, and the Console for warnings.
7. Click any bar or chart element to open the drawer on the right with the entity's attributes, relationships and how often it executed; Open Entity View opens the entity.
8. Press ⟲ Reset to clear the run and start again.

Run a Monte Carlo study

1. Switch the header to Monte Carlo (or choose ▶ Simulate ▾ → Monte Carlo in the Action Diagram).
2. Set Iterations (1 to 20,000; default 100), the Fixed-duration variation and a Random seed if the study must be repeatable.
3. Press ▶ Run Monte Carlo. If some ORs or LOOPs have no probability or count, the Unspecified Decisions dialog lists them; click Use Equal Probabilities to continue, or Cancel and set them in the Action Diagram.
4. Watch the progress bar and the running text (k / n · mean … · mean cost …). Click Cancel to stop; the toast reads "Monte Carlo cancelled".
5. When done, the text shows the number of simulations and the elapsed time. Read Status, Statistics, the Time Bar Chart, Cumulative Probability (S-Curve) and Decision Paths.
6. If any runs deadlocked or failed, a red box gives the count and P(failure) with its 95% confidence interval. Open Failed runs and click View Run to replay one in Discrete Event mode with its own seed; Back to Monte Carlo results returns.

Check a requirement and record the result

1. After a Monte Carlo study, click Check Against Requirement….
2. Choose the Output: Total time, Total cost, the minimum or final amount of each Resource, or a numeric script global (Global: …).
3. Optionally choose a Measure and Use (Threshold or Objective). The Measure's value fills Value and Units, its Improvement Direction picks the criterion (Negative gives ≤, Positive gives ≥), and the Requirement it specifies fills Requirement.
4. Otherwise set Criterion (≤ at most or ≥ at least), Value and Units, and choose the Requirement.
5. Set Required probability (%) (default 90).
6. Read the result table: Criterion, Runs, Mean (95% CI), P5 / P50 / P95, P(meet) with its 95% confidence interval, Margin (mean vs. threshold) and Result (Pass or Fail).
7. Click Record Result…. The Record Result preview lists the changes: the Measure's Projected Value (or Value) set to the mean, and a Test Case that verifies the requirement, either a new one named "Simulation check: <output> <criterion>" or an existing one you choose, with Status Passed or Failed and Actual Result set to the result text. Untick a row to skip it, then click Apply. All changes are one undo step.

Save and reopen results

1. Click Export Results…, enter a File Name and click Save.
2. The results are saved as an Artifact labeled Simulation Output with a .sim file. The Results Saved dialog offers Navigate to Artifact.
3. Reopen saved results from Saved Results ▾ in the top bar. A banner reads "Viewing saved results: …" with a Re-run on the model link that runs the current model with the same mode.

Worked example: the CubeSat EO-1 imaging pass

The demo project (Manage Projects → Project Files ▾ → Create Demo Project) contains the operation OPS Run Nominal Imaging Pass and requirement 6.5 Planning Cycle Time: "The mission shall complete each planning cycle, from target list uplink to product delivery, within 100 minutes."

The flow of OPS:

1. OPS.1 Transmit Imaging Plan (triangular 4 to 9 minutes, peak 6; Ground Station), OPS.2 Receive Imaging Plan (1 minute), OPS.3 Load Command Schedule (2 minutes).
2. A Parallel: OPS.4 Rotate to Target (normal, 3 ± 0.5 minutes) and OPS.5 Prepare Camera (5 minutes). Both are triggered by the Command Schedule I/O that OPS.3 generates.
3. A LOOP Each target, 4 iterations: OPS.6 Capture Image Strip (normal, 40 ± 6 seconds) then OPS.7 Encode and Store Image (uniform 20 to 40 seconds).
4. An OR Contact in view?: Yes 75% runs OPS.8 Transmit Image Data (normal, 8 ± 1.5 minutes); No 25% runs OPS.9 Hold Data Onboard.
5. A Parallel: OPS.10 Recharge Battery in Sunlight (35 minutes) and OPS.11 Receive Downlink (9 minutes) followed by OPS.12 Process Image Products (normal, 45 ± 10 minutes).

Resources: Battery Charge (62 Wh initial, 23 minimum, 77 maximum) is consumed by OPS.4 to OPS.8 and produced by OPS.10 (+30 Wh). Data Storage (1.5 GB initial) gains 2.5 GB per OPS.7 and loses 8 GB in OPS.8. The demo saved settings for OPS: seed 42, 200 Monte Carlo iterations with ±10% uniform variation on fixed durations.

1. Open Behavior → Simulator, choose OPS Run Nominal Imaging Pass as the Root Action and keep Discrete Event.
2. Press ⏩ Run to End. The Gantt Chart shows OPS.4 and OPS.5 side by side, four numbered iterations of OPS.6 and OPS.7 (#2, #3, #4), and the long OPS.11 → OPS.12 branch that sets the end time. Resource Over Time shows Battery Charge stepping down through imaging and recovering during OPS.10. Total Cost reads "No Costs incurred" because the demo has no Cost entities.
3. Switch to Monte Carlo and press ▶ Run Monte Carlo (200 runs). Decision Paths shows about three quarters of the runs on Yes.
4. Click Check Against Requirement…, keep Total time, choose Measure MOE-7 Planning Cycle Time and Use Threshold. Value becomes 100, Units Minutes, Criterion ≤, and Requirement 6.5 Planning Cycle Time. Keep 90%.
5. Read P(meet) and the verdict, then Record Result… → Apply. MOE-7's Projected Value gets the mean, and a Test Case verifying 6.5 gets Status Passed or Failed. The RVTM now lists that Test Case against 6.5.

Tips and good practice

• Give every leaf action a Duration. An action with no Duration takes no time and hides on the time axis.
• Use distributions for durations you are unsure of; use Fixed-duration variation only as a quick sensitivity check.
• Set probabilities on every OR and iterations on every LOOP before Monte Carlo; otherwise each run picks at random and the results say so.
• Set a Random seed before recording a verification result, so the result can be reproduced. The seed is included in the recorded text.
• Run enough iterations: when the required probability lies inside the confidence interval, the check says "Run more iterations for a firmer verdict."
• Use Save Settings on the root action you simulate often; the settings and the panel layout then travel with the project.

Common mistakes

How it connects

• Fed by: the Action Diagram flow and the attributes and relationships of its actions, I/Os, resources, conduits, assets and costs; the flow built in Functional Analysis is the same flow.
• Feeds: Measures (Projected Value or Value), Test Cases that verify requirements (and so the RVTM and Test Center), Artifacts with saved results, MS Project XML schedules and CSV reports.

The Simulator page

Header and top bar

• Root Action: the action whose flow runs. The list shows every Action with an action flow; an action without one appears as "(no flow)". Choosing another root reopens the page for it.
• Discrete Event / Monte Carlo: the mode. Switching keeps the settings of each mode.
• Top bar: Saved Results ▾ (saved result Artifacts, or "No saved results yet") and Open Action Diagram.

Settings row

• Settings are remembered in this browser as you change them.
• Save Settings stores the settings and the current panel layout with the root action in the project, so they apply for everyone who opens it. The toast reads "Simulator settings saved for this Action".
• Default Settings restores the defaults and the default panels and removes the saved settings of the root action.

Discrete Event controls

• ▶ Play / ⏸ Pause: animate the run at the chosen speed. Long stretches with no events are skipped at once.
• ⏭ Step: advance to the next event.
• ⏩ Run to End: run to the end without animation. It still stops for prompts.
• ⟲ Reset: discard the run.
• Clock: the current simulated time (a date and time in Calendar Mode).
• Export Results…, + Add Panel, Reset Layout.

Monte Carlo controls

• ▶ Run Monte Carlo, Cancel, the progress bar and progress text.
• Check Against Requirement… (enabled after a study with completed runs).
• Project Exports ▾: Longest Duration Export, Shortest Duration Export, Highest Cost Export, Lowest Cost Export. Each downloads the Gantt rows of that run (the run number is shown) as MS Project XML.
• Export Results…, + Add Panel, Reset Layout.

Notes above the panels

• "±n% uniform variation added to fixed durations." (or triangular) when variation is on.
• "Equal probabilities used for n unspecified constructs: …" after Use Equal Probabilities.
• The failed-runs box (Monte Carlo) and the replay banner "Replaying Monte Carlo run n (deadlock or error) with seed s and the study's settings."

Panels

Panels form a 12-column grid. Before a run, each panel shows its description.

Working with panels

• + Add Panel opens a searchable menu ("Find a panel…") grouped as Cost, Time, Resources and Other. Panels that can appear once are disabled when already placed.
• Drag a panel by its header to reorder it.
• Double-click the title to rename the panel (Panel Title).
• Drag the bottom edge of a panel to change its height.
• ⚙ on configurable panels, and Settings… in the panel menu, open Choose Entities: tick the Entities to graph (Add all, None), pick an Entity Color per entity, and for cost panels Show Total Cost or Choose Chart Style (Doughnut or Pie). Before any run it says "No candidate entities in the last run — all entities will be shown."
• The ⋯ panel menu has:
  • Reports: the panel's CSV reports (below).
  • Image: Transparent Image (PNG), Opaque Image (PNG), SVG Image. Images use light-theme colors.
  • Panel: Settings…, Width: Small/Medium/Large/Full → next, Lock Panel / Unlock Panel (a locked panel cannot be moved, resized or removed), Remove.
• Reset Layout restores the default panels for the mode.
• Most report items open a column picker: tick the Columns, choose Sort by and Order (Ascending, Descending), then Download CSV.

Discrete Event panels

Default layout: Status, Total Time, Total Cost, Action Trace, Gantt Chart, Resource Over Time, Asset Utilization Over Time, Cost Over Time, Console, Event Log.

Monte Carlo panels

Default layout: Status, Statistics, Time Bar Chart, Cost Bar Chart, Time Tree Map, Cost Tree Map, Cumulative Probability (S-Curve), Resources (Radar), Asset Utilization (Radar), Decision Paths.

Scripts

Scripts are JavaScript hooks on Actions, ORs and LOOPs. In the Action Diagram, select the element; the inspector offers Edit Action Script… for an action and an edit-script button in the OR and LOOP panels. The editor dialog (for example Action Script: Capture Image Strip or OR Script: …) has Add onStart(), Add prompt(), Add onEnd() and Add duration() to insert empty hooks, then Save or Cancel. Tab inserts two spaces.

Hooks

response holds the answers of the prompt dialog, keyed by input name. With Automate with no script, and in Monte Carlo, the prompt is not shown and the default values are used (a number's value or 0, a checkbox's value, the first choice).

Prompt builder

• p.setTitle(text): the dialog title (default "Prompt: <name>").
• p.addEnumInput(title, name, choices, default): a choice list.
• p.addTextInput(title, name, default), p.addBigtitleTextInput(title, name, default) (multi-line), p.addNumberInput(title, name, default), p.addBooleanInput(title, name, default) (checkbox).

The dialog reads "Simulation paused at <time>." and closes with OK.

Available in scripts

• print(x, …): writes to the Console. Objects print as JSON.
• globals.put(key, value), globals.get(key): values tracked over time in the Global Tracker. Numeric globals become Monte Carlo outputs (Global: key) in Statistics, the S-Curve and Check Against Requirement….
• Sim.getEntityById(id), Sim.getEntityByGlobalId(id), Sim.getEntityByName(name), Sim.getEntityByNumber(number), Sim.getEntitiesByName(name), Sim.getEntitiesByNumber(number): entity wrappers with id, name, number, description, className, getId(), getGlobalId(), getName(), getNumber(), getDescription(), getAttribute(name) (by attribute name, any case) and attributes().get(name).
• Sim.getIOValueById(id), Sim.getIOValueByGlobalId(id), Sim.getIOValueByName(name), Sim.getIOValueByNumber(number): the Value attribute of an Input/Output.
• Sim.getAmount(name), Sim.getAmountById(id), Sim.getAmountByGlobalId(id): a Resource's current amount. Sim.getResourceByName(name) returns {id, name, amount, units}.
• Sim.setResourceById(id, value), Sim.setResourceByGlobalId(id, value), Sim.setResourceByName(name, value): set a Resource's amount (logged as a Script change).
• Sim.getCurrentTime() (milliseconds since the start) and Sim.getCurrentCost().

Each script is compiled once per run, so top-level variables keep their values across passes of a loop. The model is read-only to scripts except for resource amounts.

Example: decide a branch from battery charge

function onEnd() {
  const wh = Sim.getAmount('Battery Charge');
  globals.put('Battery at decision', wh);
  return wh > 40 ? 'Yes' : 'No';
}

Put this on the OR Contact in view? with Decision type Script; the branch names must be Yes and No.

Sandbox and trust

• Every run executes in a separate sandbox with a read-only copy of the model. Scripts have no access to the page, other projects, files, browser storage or the network.
• A script call that runs longer than 8 seconds stops the run: "The script of <name> ran longer than 8 s and was stopped. Check it for an endless loop."
• Scripts you write or approve in this browser are trusted. Before a run that includes scripts from somewhere else (an imported file, another member's edits), the dialog Run Scripts From Another Author? lists how many there are and says that scripts run in a sandbox without access to your projects, files or the network. Open Show the scripts to review them, then click Run Scripts (they are trusted from then on in this browser) or Cancel. It appears before ▶ Play, ⏭ Step, ⏩ Run to End and ▶ Run Monte Carlo.

Keyboard and mouse

Messages

Limits

• Monte Carlo: 1 to 20,000 iterations per study.
• One run: at most 20,000 action executions, 500,000 events, and 10,000 passes of one LOOP.
• Script calls: 8 seconds each.
• Failed-runs table: the first 50 failed runs are listed; Runs CSV in Decision Paths lists them all.
• Monte Carlo statistics use completed runs only.
• Only the first Conduit that transfers an I/O sets its delay; only the first parent sets an asset's capacity.

Related

• Action Diagrams: build the flow, constructs, I/Os, resources and scripts.
• Functional Analysis: derive the functions and flow from requirements.
• Simulator, Simulation Scripts and Simulate and Check Against a Requirement in Help.
• Attribute Types and Distributions and Set Up Verification, Run Tests and Produce the RVTM.