V2 Simulation
Simulation of Models in KIELER
Overview
After a model has been created, it is reasonable to test if the model does what is expected. This can be achieved by simulating the model. The simulation must
- Receive inputs for the next tick
- Execute a tick
- Send generated outputs
Thus the simulation can be seen as a black box, which receives a state for the model, somehow computes a reaction, and communicates its new state to the outside. The communication for receiving and sending the state of the model is done using JSON. For example, in KIELER a simulation can be started by starting an executable file. The JSON communication is then done on stdin and stdout of the running process.
Within KIELER a single state of a simulation is represented as a Data Pool. A data pool can have multiple models. Each model can have multiple variables. Thus a representation of a complete run of a simulation can be implemented as list of data pools.
Starting a Simulation
Besides the explicit configuration of a simulation using a kisim file, it is possible to start simulations directly on models, executables or trace files. This will start a pre-defined configuration depending on the selected files. The following table shows which files can be started as simulation and what simulation configuration is created for it.
Selection | Example Selection | Macro Tick Configuration of Simulation |
|---|---|---|
executable | Sim_ModelA.exe | Performs a single tick and updates the pool with the received data from the process |
2 executables | Sim_ModelA.exe, Sim_ModelB.exe | Starts two executable data handlers with bidirectional redirection of inputs/outputs between the models. So the performed steps are: Execute tick of A, redirect A→B, execute tick of B, redirect B → A |
kisim file | ComplexSimulation.kisim | Uses the explicit configuration from the file |
1 executable, 1 trace file | Sim_ModelA.exe, TraceOfModelA.eso | The trace will first set inputs for the model that are read from the trace file. Then the tick is performed. Afterwards the generated outputs are compared to the outputs of the trace file and events are fired in case of a mismatch. |
simin file | process_output.simin | The simin file must contain a JSON object for some model. The data pool of the simulation is then updated with its contents. |
simout file | simulation_output.simout | The current pool of the simulation is written as JSON object to the simout file. |
Data Handlers
A simulation consists of a list of data handlers, that can read or write the current data pool. Which handlers are available are explained in the following.
Executable
For instance, there exists a data handler for the simulation of an executable. The write operation of this data handler will send the inputs of the model as JSON object on stdin of the process. Afterwards the tick is triggered, and finally the data pool is updated with the JSON object received from stdout of the running process.
Attribute | Domain | Example | Description |
|---|---|---|---|
executable | String, absolute workspace path or project relative path | /MyProject/kieler-gen/sim/bin/Sim_MyModel.exe | The path to the executable |
Redirect
Multiple models may interact with each other as some can have inputs that are generated as outputs of other models. To implement this behaviour in the simulation, the redirect data handler has been created. It sets the inputs of a model to the outputs of some other model in the data pool. Thus the outputs of a some model A can be used as inputs of some model B.
Attribute | Domain | Example | Description |
|---|---|---|---|
from | String, name of a model in the simulation | Sim_ModelA.exe | The name of the model of which the outputs are read |
to | String, name of a model in the simulation | Sim_ModelB.exe | The name of the model of which the inputs are set |
Trace
A trace data handler can read a trace file, set the inputs of a model with the inputs from the trace file as well as comparing the outputs of a model to the outputs of the trace file. If the outputs of the trace do not match the outputs of the current simulation, an event is fired and the data pool view will display a trace mismatch.
The typical setup to use a trace data handler for a model A is:
- Read inputs for model from trace
- Perform the tick of the model A
- Compare the outputs of the trace and the model A
Attribute | Domain | Example | Description |
|---|---|---|---|
file | String, project relative path | MyTrace.eso | The trace file to be used |
modelName | String, name of a model in the simulation | Sim_ModelA.exe MyModelA | The model in the simulation for which the trace is for |
checkOutputs | Boolean | true | If false, the outputs of the trace and simulation are not compared and the next tick is loaded after inputs have been set. |
traceNumber | Integer | 0 | In case there are multiple traces in the eso file, determines which trace should be used. |
tickNumber | Integer | 0 | The tick of which the input is set. This can be used to skip some ticks of the trace. |
Simulation Input Files
The simulation can communicate with executables via stdin and stdout. To use this, the executable has to be started from within KIELER.
To get information about a model that is running outside of KIELER, simulation input files can be used. A simin file contains a single JSON object with the state of a model that can be used to feed the simulation with data. Thus any program that can write a JSON object to a file can interact with the simulation.
In combination with redirects, a simin file can be used to set the inputs of a model with data that is produced from another application.
Simulation input files can also be used to feed the simulation with data to be visualized via the simulation visualization.
Attribute | Domain | Example | Description |
|---|---|---|---|
fileLocation | String, absolute file system path | /home/myuser/process_output.simin | The file location of the file containing the JSON object |
modelName | String, name of a model | MyModel | Name of the model in the simulation that the data in the simin file is for. |
Simulation Outputs Files
This data handler writes the output of the model in the simulation to the specified file.
Attribute | Domain | Example | Description |
|---|---|---|---|
fileLocation | String, absolute file system path | /home/myuser/process_output.simout | The file location of the target file |
modelName | String, name of a model | MyModel | Name of the model in the simulation that will be written as JSON object to the simout file |
KiSim
Which data handlers are used and which actions are performed on them can be configured using a DSL, namely KiSim.
A kisim file contains two main parts:
- Configuration of data handlers
- Actions to be performed on the data handlers for each a macro tick
Besides these, an optional initialization part can be used to perform actions on data handlers once at startup.
Examples
The following shows examples of kisim files.
Configuration to simulate a single executable:
executable: kielger-gen/sim/bin/Sim_Test
}
execution {
write sim Test
}
Configuration for two executables with redirection between both:
executable: kielger-gen/sim/bin/Sim_Test
}
configure sim B {
executable: kielger-gen/sim/bin/Sim_Test2
}
configure redirect A_to_B{
from: A
to: B
}
configure redirect B_to_A{
from: B
to: A
}
execution {
write sim A
write redirect A_to_B
write sim B
write redirect B_to_A
}
Using a trace for a model:
executable: kielger-gen/sim/bin/Sim_Test
}
configure trace A {
file: MyTrace.eso
modelName: A
}
execution {
write trace A // Set inputs of model to values from trace
write sim A // Perform tick of model
read trace A // Compare outputs of model with values from trace
}
Feeding inputs of a model from a simin file:
executable: kielger-gen/sim/bin/Sim_Test
}
configure simin SimInput {
file: process_output.simin
}
configure redirect SimInput_to_A{
from: SimInput
to: A
}
execution {
write simin SimIn
write redirect SimInput_to_A
write sim A
}