To start a simulation, the first step is to create a new simulation element.
<simulation duration="10" period="0.1" asynchronous="false"> </simulation>
The simulation element has several attributes that determine its behaviour:
- asynchronous is a flag that determines if the simulation should be run at a deterministic rate (synchronized to the timebase), or as quickly as possible. The default is false.
- duration specifies the duration of the full simulation in seconds. The default is for an infinite duration (-1).
- period is the period of the simulation loop in seconds. For example, a simulation that updates at 50Hz would have a period of 0.02s. We recommend not running simulations at rates faster than 100Hz or a period of 0.01s. The default is 0.01s.
- loop is a flag that determines if the simulation should loop after it has reached its duration. The default is false.
Simulations have four methods that can be used to control their state.
- Start - Starts the simulation at time zero
- Stop - Stops the simulation and re-initializes its blocks
- Pause - Pauses the execution of the simulation
- Play - Resumes the simulation from current time after pausing
Theses methods are called from script, and can be called from a simulation event (e.g. onActivePageChanged) or from a control (e.g. a button).
<simulation name="firstSim"> <onActivePageChanged> if active then firstSim:Start() else firstSim:Stop() end </onActivePageChanged> </simulation> <button name="myButton" content="Pause Simulation"> <onClick> if myButton.Text == "Pause Simulation" then firstSim:Pause() myButton.Text = "Resume Simulation" else firstSim:Play() myButton.Text = "Pause Simulation" end </onClick> </button>
You can also declare a script that you want to run in response to the events that are triggered by simulations. The events that are available are:
- onStateChanged - occurs when the simulation starts/stops or is paused/resumed
- onUpdate - triggered after each simulation loop is executed
- onDuration - triggered when the simulation is completed
- onActivePageChanged - occurs when the page is loaded on a device
- onDocumentOpened - occurs when the document is loaded on a device
Using the onUpdate event to create a custom script for a simulation with a specified period is a good way to create a deterministic simulation that does not involve a traditional block diagram. For example, if you wanted to update the position of a falling rock for a simple physics simulation you could easily create a simulation and script that solves for the position of the rock at each time step.
<label name="fall_distance">Distance fallen = 0 m</label> <label name="elapsed_time">Time Elapsed = 0 s</label> <button name="sim_button" content="Start"> <onClick> if sim_button.Text == "Start" then sim_button.Text = "Stop"; sim:Start(); else sim_button.Text = "Start"; sim:Stop(); end </onClick> </button> <simulation duration="10" name="sim" period="0.01"> <onUpdate> local distance = 0.5 * 9.81 * time^2; fall_distance.Text = string.format("Distance fallen = %.2f m", distance); elapsed_time.Text = string.format("Time Elapsed = %.2f s", time); </onUpdate> <onDuration> sim_button.Text = "Start"; </onDuration> </simulation>
When the button is pressed, the simulation runs for 10 seconds, updating the distance fallen by the rock every 0.01 seconds. The values are stored in a label at each time step. Note that time is the current simulation time and can be accessed inside of the onUpdate event. For information on inherent event variables, see the Scripting Reference.
The OutputsAt(int port) and OutputAt(int port, int signal) methods are also inherent methods that are members of simulation elements, and can be called in a script to access the current values at those locations in the model diagram.