Communication with Simulation via TCP
System Modeler simulations use a protocol that can be used to interface a running simulation to read and write data. A network protocol with two sessions is used: Wolfram System Modeler–Simulation Control Session (WSM–SCS) and Wolfram System Modeler–Simulation Data Session (WSM–SDS). The following figure illustrates the setup.
System Modeler 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.
WSM–SCS/WSM–SDS
The System Modeler–Simulation 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 System Modeler–Simulation 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-7 | protocol version | 1 | |
| 8-15 | packet type | 1 - HELLO_SCS 2 - HELLO_SDS 3 - CMD 4 - CMD_REPLY 5 - CMD_ERROR 6 - SDS_OUTPUT_DATA 8 - SDS_INPUT_DATA | |
| 16-31 | packet specific | ||
| 32-63 | payload length |
HELLO_SCS Packet
The client initiates an SCS session by sending a HELLO_SCS packet; the payload should be empty. Upon successful initiation, the server will reply with a CMD_REPLY packet where the payload will be {SESSION_ID_SCS}. If it fails, the server will reply with a CMD_ERROR packet where the payload will be a description of the problem.
HELLO_SDS Packet
The client initiates an SDS session by sending a HELLO_SDS packet; the payload should be the SESSION_ID_SCS given to the corresponding SCS session. If successful, the server will reply with a CMD_REPLY packet where the payload will be {SESSION_ID_SDS}. If it fails, the server will reply with a CMD_ERROR packet where the payload will be a description of the problem.
After the simulation has been started, the server will start to stream SDS_OUTPUT packets to the client after every time step according to the subscription set up 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 CMD_REPLY packet and the payload will contain the result of the command. On failure, the server will reply with a CMD_ERROR 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 CMD_REPLY packet as a reply to a HELLO_SCS, HELLO_SDS, or CMD packet.
CMD_ERROR Packet
The server sends a CMD_ERROR packet as a reply to a HELLO_SCS, HELLO_SDS, or CMD 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 CMD_REPLY and CMD_ERROR packets are formatted as arrays enclosed in {}. The elements in the array are separated with a comma. Valid array elements are:
Example: array with string values: {"var1","var2","var3"}
Example: array with real values: {1.0,2.0,3.0}
Example: array with nested array, strings, and numbers: {{"var1",1.0},{"var2",2.0}}
SDS_OUTPUT_DATA Packet
When an SDS session has been initiated by sending a HELLO_SDS packet, the server will start to send SDS_OUTPUT_DATA 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 (double).
SDS_INPUT_DATA Packet
The client can send an SDS_INPUT_DATA packet on an SDS session to set all input variables; the payload should consist of the values in binary format (double) for all input variables in the order indicated by getInputVariableNames().
SCS Interactive Commands
All interactive commands are sent as a CMD package on an 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 SUBSCRIPTION_ID 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 continueSimulation() or terminateSimulation() command is issued.
continueSimulation()
Continues the simulation after a suspendSimulation() command.
startSimulation()
Starts the simulation if the simulation is configured to wait for a startSimulation() 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.