WOLFRAM SYSTEMMODELER TUTORIAL

Communication with Simulation via TCP

Introduction | Options | Experiment Browser | Plot Windows | 3D Animation | Initializing Experiments | FFT Analysis | Importing and Exporting | Keyboard Shortcuts | Input Variable Data Files | Simulation Settings Files | Simulation Result Files | Communication with Simulation

This appendix describes the protocol used for the interface to a SystemModeler simulation that can be used for reading and writing data to a running simulation. A network protocol with two sessions is used: Wolfram SystemModelerSimulation Control Session (WSMSCS) and Wolfram SystemModelerSimulation Data Session (WSMSDS). The figure below illustrates the setup.

1.gif

SystemModeler simulation sessions.

The protocol allows for setting both parameter and input variables and retrieving (output) variables from each integration step. If a real-time simulation should be achieved, the XML input file to the simulator is set up to use a single step solver with a fixed step size, which determines the sample rate of the simulator. An option can be given to state that the simulator should synchronize with the computer's real-time clock, if desired.

WSMSCS/WSMSDS

The SystemModelerSimulation Control Session is used to control a running simulation server by issuing start/stop commands and setting input variable values. The protocol runs over TCP and a message consists of a header and a payload.

The SystemModelerSimulation Data Session is used to receive simulation data from a running simulation server. An SDS session must be paired with an SCS session that is used to set up the variable subscriptions.

WSMCOM Packets

Each packet consists of a header describing the type of package as well as the length of the payload.

WSMCOM Header

The header consists of information about which protocol to use, which type of package is sent, packet-specific data, and the length of the payload.

bits
0-7protocol version
8-15packet type1 - 2 - 3 - 4 - 5 - 6 - 8 -
16-31packet specific
32-63payload length

HELLO_SCS Packet

The client initiates an SCS session by sending a packet; the payload should be empty. Upon successful initiation, the server will reply with a packet where the payload will be . If it fails, the server will reply with a packet where the payload will be a description of the problem.

HELLO_SDS Packet

The client initiates an SDS session by sending a packet; the payload should be the given to the corresponding SCS session. If successful, the server will reply with a packet where the payload will be . If it fails, the server will reply with a packet where the payload will be a description of the problem.

After the simulation has been started, the server will start to stream packets to the client after every time step according the subscription setup with the corresponding SCS session. The SDS session cannot be used to send commands to the server.

CMD Packet

The client sends an interactive command to the server by sending a CMD packet; the payload should contain the command. On success, the server will reply with a packet and the payload will contain the result of the command. On failure, the server will reply with a packet where the payload will be a description of the problem. For a list of commands, see this section.

CMD_REPLY Packet

The server sends a packet as a reply to a , , or packet.

CMD_ERROR Packet

The server sends a packet as a reply to a , , or packet that results in an error on the server. The payload will contain a description of the problem.

CMD_REPLY and CMD_ERROR Payloads

All payloads in and packets are formatted as arrays enclosed in . The elements in the array are separated with a comma. Valid array elements are:

  • Strings enclosed in double quotes
  • Integer values
  • Real values
  • Other arrays enclosed in

Example: array with string values:

Example: array with real values:

Example: array with nested array, strings, and numbers:

SDS_OUTPUT_DATA Packet

When an SDS session has been initiated by sending a packet, the server will start to send packets with the values of the subscribed variables after each solver step. Bit 16-23 in the packet header is the subscription ID.

The payload consists of the values for all subscribed variables in binary format ().

SDS_INPUT_DATA Packet

The client can send an packet on an SDS session to set all input variables; the payload should consist of the values in binary format () for all input variables in the order indicated by .

SCS Interactive Commands

All interactive commands are sent as a CMD package on a SCS session.

getInputVariableNames()

Returns a list with the names of all input variables in the model.

getModelName()

Returns the name of the model.

getOutputVariableNames()

Returns a list with the names of all output variables in the model.

getParameterNames()

Returns a list with the names of all parameters in the model.

getStateDerivativeVariableNames()

Returns a list with the names of all state derivative variables in the model.

getStateVariableNames()

Returns a list with the names of all state variables in the model.

getVariableNames()

Returns a list with the names of all variables in the model.

getAlgebraicVariableNames()

Returns a list with the names of all algebraic variables in the model.

setSubscription({"var1", "var2", "var3", ...})

Sets the subscription for the corresponding SDS session; returns a used to identify the packets received in the SDS session.

setInputValues({"var1", value1, "var2", value2, ...})

Sets input variable values; the new values will be used in the next solver step.

getTime()

Returns the current simulation time.

suspendSimulation()

Suspends the simulation until a or command is issued.

continueSimulation()

Continues the simulation after a command.

startSimulation()

Starts the simulation if the simulation is configured to wait for a command before starting.

stopSimulation()

Stops the simulation when the current solver step has finished.

setParameterValues({"var1", value1, "var2", value2, ...})

Sets parameter values; the new values will be used in the next solver step.

getVariableValues({"var1", "var2", ...})

Returns a list of variable values.

Introduction | Options | Experiment Browser | Plot Windows | 3D Animation | Initializing Experiments | FFT Analysis | Importing and Exporting | Keyboard Shortcuts | Input Variable Data Files | Simulation Settings Files | Simulation Result Files | Communication with Simulation