WOLFRAM SYSTEMMODELER LINK PACKAGE TUTORIAL

Advanced Simulation Control

Introduction

The SystemModeler Link functions WSMSimulate and WSMRealTimeSimulate are used to simulate models from Wolfram SystemModeler. They automate the most common use case of building a model, controlling parameters, initial values, and input variables, simulating the model, and collecting the result into a WSMSimulationData object.

In some cases, it can be useful to control these steps in greater detail. This tutorial describes how to gain more control over the simulation workflow, and how to control things in detail.

This is a hands-on tutorial. You are expected to evaluate all the input lines as you reach them and watch what happens. The accompanying text will not make sense without evaluating as you read.

To use the SystemModeler Link package, we need to load it with Needs.

In[1]:=
Click for copyable input

This tutorial will use the model in the package. The model is a simple addition of a sine wave and an input.

In[2]:=
Click for copyable input
In[7]:=
Click for copyable input
Out[7]=

Building and Launching

When simulating a model with WSMSimulate, the Modelica model is first translated into a simulation executable. A simulation file is also generated, which is used to control parameter values, initial values, and options for the simulation. The simulation executable is then started with the simulation file as input, and a connection between the simulation and SystemModeler Link is established. This connection uses a custom protocol built on TCP/IP. The simulation is now ready to be started.

To accomplish this first step, the following functions are available.

WSMLink`Simulate`Launch[mmodel,]build and launch a simulation
WSMLink`Simulate`Connect[port]connect to a running simulation on port
WSMLink`Simulate`Connect["ip",port]connect to a simulation on "ip":port

Get a connection to a simulation executable.

The function takes the same arguments as WSMSimulate. Instead of continuing the process of simulating and retrieving result data, this function instead returns a WSMSimulationConnection object, allowing more detailed control over the simulation. Build and start a real-time simulation of a basic model with inputs and an output.

In[4]:=
Click for copyable input
Out[4]=

It is possible to connect to a running simulation with its IP and port number. Create a second connection to the just-launched simulation using .

In[6]:=
Click for copyable input
Out[6]=

Configuring IP and Port

When launching a simulation, it is also possible to specify a specific interface and a port to listen to. This makes it possible to start a simulation on one computer and control it from another. The two relevant options are and .

Automaticlisten on local host
Alllisten on all interfaces
"ip"listen on ip

Possible settings for .

Automaticautomatically choose a port
portlisten on port

Possible settings for .

Start a simulation listening on port number , on all interfaces.

In[7]:=
Click for copyable input
Out[7]=

The connection is still listening on the localhost IP .

In[5]:=
Click for copyable input
Out[5]=

It is also possible to connect to it through the public IP found in $MachineAddresses:

In[6]:=
Click for copyable input
Out[6]=
In[7]:=
Click for copyable input
Out[7]=

Connection Control

Information Properties

The connection object conn representing the simulation can be queried for a number of properties.

conn["State"]current simulation state
conn["Time"]current simulation time
conn["StopTime"]simulation stop time
conn["ModelName"]name of simulated model
conn["NumberOfEvents"]number of events generated
conn["NumberOfEvaluations"]number of evaluations performed
conn["IP"]IP address of the simulation
conn["Port"]port of the simulation
conn["Diagram"]dynamic diagram of the model
conn["VariableNames"]list of variable names
conn["ParameterNames"]list of parameter names
conn["InputVariables"]list of input variables

Information of a running simulation.

The simulation launched above is not yet started.

In[10]:=
Click for copyable input
Out[10]=

There are a fixed number of possible simulation states, shown in this table.

"Unknown"the simulation is in an unknown state
"NotStarted"the initial state, when simulation time is 0
"Running"simulation time is increasing
"Paused"simulation is paused
"Disconnected"Mathematica is disconnected from simulation

Simulation states.

Simulation time is initially at .

In[11]:=
Click for copyable input
Out[11]=

The property of a connection will return the model diagram. If there are dynamic graphics on the diagram, these will use data for the time point conn["Time"]. If the simulation is in a state, the diagram will show the static version of any dynamic graphics.

Control Properties

The connection object conn can be used to control the simulation.

conn["Start"]start or resume the simulation
conn["Pause"]pause the simulation
conn["Stop"]stop the simulation
conn["Close"]disconnect Mathematica from the simulation

Controlling a simulation.

Start the simulation, let one second pass, and pause it again.

In[12]:=
Click for copyable input

As the simulation is in real time, the simulation time has also increased by a little over 1 second.

In[13]:=
Click for copyable input
Out[13]=

The simulation is now in a state.

In[14]:=
Click for copyable input
Out[14]=

Stopping the simulation will stop the simulation at the current simulation time, quit the simulation executable, and close the connection to Mathematica.

Closing the connection to the simulation will leave the simulation in its current state but remove the connection between Mathematica and the simulation.

Simulation Data

Reading Simulation Data

The connection to a simulation allows retrieving simulation result data while the simulation is running. The latest data point for a variable or list of variables can be retrieved.

conn[{"v1",}]variable values for
conn["SimulationData"]create a WSMSimulationData object

Retrieve simulation data.

Start a new simulation, and let it run for one second.

In[8]:=
Click for copyable input
Out[8]=
In[9]:=
Click for copyable input

Retrieve the current values for the input and output of the running simulation.

In[10]:=
Click for copyable input
Out[10]=

When the simulation has stopped or is otherwise unreachable, the result of is {None,}.

A complete WSMSimulationData object can be retrieved.

In[11]:=
Click for copyable input
Out[11]=
In[12]:=
Click for copyable input
Out[12]=

Another possibility is to register a function that will be called every time the data from the simulation is updated.

WSMLink`Simulate`AddDataMonitor[conn,fn,vars]call fn with time and values for vars each simulation step
WSMLink`Simulate`DeleteDataMonitor[dm]remove the data monitor dm

Handling simulation data monitors.

Start a new simulation.

In[20]:=
Click for copyable input
Out[20]=

Add a data monitor that stops the simulation when the value of goes below .

In[21]:=
Click for copyable input
Out[21]=

Resume the simulation and let it run until the data monitor above stops it.

In[22]:=
Click for copyable input

Plotting again will read in the new data from the result file.

In[23]:=
Click for copyable input
Out[23]=

The simulation data object can only be retrieved if the simulation was launched by . In other cases, SystemModeler Link has no control over where the file with the results is, so it cannot return a full result object. Start one simulation with , and connect to it with .

In[24]:=
Click for copyable input
Out[24]=
In[25]:=
Click for copyable input
Out[25]=

Run the simulation for a short while.

In[26]:=
Click for copyable input

Retrieving a result object from the connection received from works.

In[27]:=
Click for copyable input
Out[27]=

The connection received from lacks the necessary information.

In[28]:=
Click for copyable input
Out[28]=

Writing Simulation Data

It is also possible to feed input to a simulation from Mathematica, in a couple of different ways. Either an input can be set once to a given value, or a function can be specified that is called regularly to set an input. It is also possible to set parameter values through Mathematica.

Setting Input Variables

The simplest way to change an input variable in a running simulation is by setting it directly. First, launch a new simulation.

In[29]:=
Click for copyable input
Out[29]=

Start the simulation, and after seconds, change the input variable to . Let it simulate for more seconds, and then stop the simulation.

In[30]:=
Click for copyable input

Plot the input and output in the resulting simulation.

In[35]:=
Click for copyable input
Out[35]=

An input variable can also be continuously updated from Mathematica by giving a function as an argument to . In that case, the function will be evaluated for each communication with the simulation, and the resulting value will be fed back to the simulation.

In this basic example, after seconds, continuously update the input with a random number.

In[36]:=
Click for copyable input
Out[36]=
In[37]:=
Click for copyable input

Show the result in a plot.

In[42]:=
Click for copyable input
Out[42]=

If the RefreshRate option is not given, the update will occur every time Mathematica communicates with the simulation. This is controlled by the RefreshRate option given to .

It is also possible to set how often a sample of the input function is sent to the simulation, using the RefreshRate option to .

In[43]:=
Click for copyable input
Out[43]=

Send a new random number every 0.5 seconds.

In[44]:=
Click for copyable input
In[49]:=
Click for copyable input
Out[49]=

The RefreshRate default is Automatic, updating on every standard communication with the simulation. Above that, RefreshRate->timespec allows any timespec supported by RunScheduledTask.

Setting Parameter Values

To set a parameter in a simulation, use .

In[35]:=
Click for copyable input
Out[35]=

Start the simulation, and after seconds, change the input variable to . Let it simulate for more seconds, and then stop the simulation.

In[36]:=
Click for copyable input

Plot the input and output in the resulting simulation.

In[41]:=
Click for copyable input
Out[41]=

It is also possible to give a list of parameters to change.

In[54]:=
Click for copyable input
Out[54]=

Change both the amplitude and the offset.

In[55]:=
Click for copyable input
In[60]:=
Click for copyable input
Out[60]=

Visualization

The live connection to the simulation can be used to visualize data from a simulation interactively. This section gives a few examples of possible visualizations, but Mathematica offers many ways to visualize data that are not covered here.

WSMPlot

The plotting function in SystemModeler Link, WSMPlot, has built-in support for simulation connections. You can take a simulation connection and directly plot simulation data.

WSMPlot[conn,{v1,v2,}]plot from the connection conn
WSMPlot[conn,{},{tmin,tmax}]plot from to

Plotting directly from a simulation connection.

Launch a real-time simulation of a Newton cradle.

In[4]:=
Click for copyable input
In[5]:=
Click for copyable input
Out[5]=

Run the simulation for seconds, and then plot the variables through .

In[6]:=
Click for copyable input
In[9]:=
Click for copyable input
Out[9]=

Plot just the first seconds.

In[10]:=
Click for copyable input
Out[10]=

When the simulation progresses, new calls to WSMPlot will use the new results available. Run the simulation for more seconds, and plot again.

In[11]:=
Click for copyable input
In[14]:=
Click for copyable input
Out[14]=

It is also possible to use WSMRealTimePlot to create plots updating in real time.

In[15]:=
Click for copyable input

Start the simulation and see the plot above update when the simulation progresses.

In[16]:=
Click for copyable input

Gauges

Gauges can be used to dynamically display values from a simulation. Launch a new simulation of the Newton cradle.

In[26]:=
Click for copyable input
Out[26]=

Display a dynamic angular gauge, refreshing every seconds, and displaying the angles of the first and fifth ball in the Newton cradle.

In[27]:=
Click for copyable input
Out[27]=

Press the play button above or evaluate this to start the simulation.

In[28]:=
Click for copyable input

Observe how the balls bounce against each other, transferring all their momentum in the collision.

Dynamic Diagrams

Showing dynamic diagrams from a running simulation is straightforward, using Dynamic and Refresh to control the updating frequency. First, launch a simulation of a tank system with controllers.

In[70]:=
Click for copyable input
Out[70]=

Display the dynamic diagram of the simulation, refreshing every seconds. Press the start button above to start the simulation.

In[71]:=
Click for copyable input
Out[72]=

Simulation Input Sources

Gauges

In Mathematica, gauges can be used for input as well as output. This allows us to use gauges as an interactive way to control the input in a running simulation.

Launch a new simulation.

In[73]:=
Click for copyable input
Out[73]=

Display an input gauge, controlling the variable .

In[74]:=
Click for copyable input
Out[74]=

Set the input in the simulation to the variable . Use a function that returns to continually update the value.

In[75]:=
Click for copyable input

Display the output in a separate gauge.

In[76]:=
Click for copyable input
Out[76]=

Finally, start the simulation by pressing the play button above, then drag the handle in the first gauge and see how the output in the second gauge changes.

Control

Similarly to how you can use a gauge to control input, you can also use any type of Control.

In[77]:=
Click for copyable input
Out[77]=
In[78]:=
Click for copyable input
Out[78]=
In[79]:=
Click for copyable input
In[80]:=
Click for copyable input
Out[80]=

Start the simulation by pressing the play button, and drag the control slider to watch the output change in the gauge.

Gamepad and Device Input

Mathematica supports a wide variety of hardware controller and input devices, which can all be used to control inputs to SystemModeler simulations. The principle is the same as with gauges and Control objects above.

In[5]:=
Click for copyable input
Out[5]=
In[6]:=
Click for copyable input
In[7]:=
Click for copyable input
Out[7]=