Changes for page Simulation (KiSim)

Last modified by Richard Kreissig on 2023/09/14 11:07

From version < 2.1 >

edited by aas2
on 2017/08/03 13:23

To version < 6.1 >

edited by aas2
on 2017/10/23 14:07

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (1 modified, 0 added, 0 removed)
Objects (1 modified, 0 added, 0 removed)
- Confluence.Code.ConfluencePageClass[0]

Details

Page properties

Content

@@ -4,6 +4,8 @@
  {{toc/}}
++----
++
  == 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
@@ -12,15 +12,25 @@
  * 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.
++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. In KIELER the communication for receiving and sending the state of the model is done using JSON. When starting the executable file of a simulation in KIELER, the JSON communication is 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 ==
++Executables for simulation are created using the incremental project builder that is part of the project management. The typical steps to create an executable for simulation are:
--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.
++* Compiling a model using the KIELER compiler
++* Generating the simulation wrapper code for the model using template processing
++* Compiling the resulting code using, e.g., gcc.
--(% class="relative-table" style="width: 99.9453%;" %)
++For more insight of the simulation generation, please take a look at the [[doc:V2 Project Management]].
++
++----
++
++== Using the 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 used to start a simulation and what simulation configuration is created for it.
++
++(% class="relative-table wrapped" style="width: 99.9453%;" %)
  |=(((
  Selection
  )))|=(% colspan="1" %)(% colspan="1" %)
@@ -31,7 +31,7 @@
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--executable
++1 executable
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
  Sim_ModelA.exe
@@ -53,7 +53,7 @@
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--kisim file
++1 kisim file
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
  ComplexSimulation.kisim
@@ -73,7 +73,7 @@
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--simin file
++1 simin file
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
  process_output.simin
@@ -83,23 +83,50 @@
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--simout file
++1 simout file
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
  simulation_output.simout
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--The current pool of the simulation is written as JSON object to the simout file.
++A model of the simulation is written as JSON object to the simout file.
  )))
++=== Playing the Simulation ===
++
++One can step through the simulation tick after tick. Furthermore it is possible to let the simulation step automatically. This is the //play mode//, in which a macro tick is performed after a given time, which can be defined in the data pool view (e.g. to perform a tick every 200ms).
++
++=== Stepping Back in the Simulation ===
++
++When clicking the //Step Back// button, the values of a former tick are set in the data pool view as user values, which will be assigned to the model before the next tick is executed. Thus it is possible to revert the simulation to a previous state if all variables that define this state are recorded in the data pool.
++
++When stepping back and forth in the simulation history, the position in the history is shown next to the current tick count in the Data Pool View. For example, when the simulation is after tick 5 and one steps two ticks back in the simulation history, this will be indicated as the tick **#5 (-2)**. If a tick is performed now using the old state, the values of tick 5 - 2 = 3 are applied and the new outputs are computed so that the simulation is now after tick **#4**.
++
++=== The Data Pool View ===
++
++The current data pool can be seen in the Data Pool View (Window > Show View > Other > KIELER Simulation > Data Pool View).
++
++In the view, the variable values can be modified by the user via clicking the column //User Value//. If a user value is specified for a variable, the corresponding row is highlighted and marked with an asterisk ( * ) . The value is applied to the variable and send to the model before the next tick is performed.
++
++When using traces in the simulation, a trace mismatch of a variable will be highlighted in the data pool view. A tooltip on the //Current Value// column shows details about the mismatch. The trace mismatch is kept between ticks. To clear a mismatch, use the menu of the view and select //Clear Trace Mismatches// from the view's menu.
++
++When the data pool view is selected, stepping through the simulation can be done using the RIGHT arrow on the keyboard, which is often more useful than clicking the corresponding button in the toolbar. Furthermore the SPACE key will play/pause the simulation and with CTRL+LEFT (respectively CTRL+RIGHT) one can step back (step forward) in the simulation history.
++
++----
++
  == 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.
++A simulation consists of a list of //data handlers//. These perform actions on the data pool. When the actions of all data handlers for a simulation have been executed, then this is a single full macro tick. In contrast performing only a single action on one data handler is called a //sub tick// and typically not necessary when using the simulation. However stepping through the data handler actions one by one can be useful to see the effect of each action on the 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.
++There is a data handler for the simulation of executables. This data handler will send the inputs of the corresponding model in the simulation as JSON object to stdin of the process. Afterwards the tick is computed by the process. Finally the data pool in the current simulation is updated with the JSON object received from stdout of the running process.
++Normal executables and executable jar files can be used simply by providing the path to the file. For other file types, e.g., a python script, the shell command to start the process has to be specified explicitly.
++
++(% class="wrapped" %)
  |=(((
  Attribute
  )))|=(% colspan="1" %)(% colspan="1" %)
@@ -124,11 +124,27 @@
  (((
  The path to the executable
  )))
++|(% colspan="1" %)(% colspan="1" %)
++(((
++command
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++String, the shell command that is used to start the process
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++python "${executable_path}"
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++The shell command to start 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.
++Per default inputs and outputs are matched by name. However it is also possible to provide an explicit mapping of which output should be mapped to which input variable.
++
++(% class="wrapped" %)
  |=(((
  Attribute
  )))|=(((
@@ -158,17 +158,43 @@
  )))|(((
  The name of the model of which the inputs are set
  )))
++|(% colspan="1" %)(% colspan="1" %)
++(((
++mapping
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++Map, The key is an output variable and the value is an input variable
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++(% class="content-wrapper" %)
++(((
++configure redirect A_to_B {
++  from: A
++  to: B
++  mapping {
++    someOutputOfA: someInputOfB
++    other OutputOfA: otherInputOfB
++  }
++}
++)))
++)))|(% colspan="1" %)(% colspan="1" %)
++(((
++Defines which output variables should be mapped to which input variables
++)))
  === 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.
++A trace data handler can read a trace file. The inputs of a model can be set to corresponding inputs from the trace and outputs of a model can be compared with corresponding outputs in the trace. Therefore the trace data handler has the methods **write** (inputs), **check** (outputs), **loadNextTick** (to go to the next tick in the trace).
++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:
++Thus the typical simulation setup to use a trace data handler for a model A is:
--* Read inputs for model from trace
++* Set the input of the model to the inputs from the trace (write)
  * Perform the tick of the model A
--* Compare the outputs of the trace and the model A
++* Compare the outputs of the trace and the model A (check)
++* Go to the next tick in the trace (loadNextTick)
++(% class="wrapped" %)
  |=(((
  Attribute
  )))|=(((
@@ -181,7 +181,7 @@
  |(((
  file
  )))|(((
--String, project relative path
++String, absolute workspace path or project relative path
  )))|(((
  MyTrace.eso
  )))|(((
@@ -200,22 +200,21 @@
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--checkOutputs
++traceNumber
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--Boolean
++Integer
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--true
--false
++0
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--If false, the outputs of the trace and simulation are not compared and the next tick is loaded after inputs have been set.
--Use this option when only the //write// method of the data handler is used, but not its //read// method.
++In case there are multiple traces in the eso file, determines which trace should be used.
++Default is 0
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--traceNumber
++tickNumber
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
  Integer
@@ -224,22 +224,23 @@
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--In case there are multiple traces in the eso file, determines which trace should be used.
++The tick of which the input is set. This can be used to skip some ticks of the trace.
  Default is 0
  )))
  |(% colspan="1" %)(% colspan="1" %)
  (((
--tickNumber
++checkInterface
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--Integer
++Boolean
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--0
++true
  )))|(% colspan="1" %)(% colspan="1" %)
  (((
--The tick of which the input is set. This can be used to skip some ticks of the trace.
--Default is 0
++Determines if the interface of the trace and model should be compared.
++If this is true and for example there is an additional input or output in the model that is not recored in the trace, a TraceMismatchEvent is fired.
++If this is false and for example the trace contains a variable that does not exist in the model, this issue is ignored.
  )))
  \\
@@ -254,7 +254,7 @@
  Simulation input files can also be used to feed the simulation with data to be visualized via the simulation visualization.
--(% class="relative-table" style="width: 81.5545%;" %)
++(% class="relative-table wrapped" style="width: 81.5545%;" %)
  |=(((
  Attribute
  )))|=(((
@@ -265,13 +265,14 @@
  Description
  )))
  |(((
--fileLocation
++file
  )))|(((
--String, absolute file system path
++String, absolute file system path or
++absolute workspace path or project relative path
  )))|(((
  /home/myuser/process_output.simin
  )))|(((
--The file location of the file containing the JSON object
++The target file
  )))
  |(((
  modelName
@@ -289,7 +289,7 @@
  This data handler writes the output of the model in the simulation to the specified file.
--(% class="relative-table" style="width: 81.7734%;" %)
++(% class="relative-table wrapped" style="width: 81.7734%;" %)
  |=(((
  Attribute
  )))|=(((
@@ -300,13 +300,14 @@
  Description
  )))
  |(((
--fileLocation
++file
  )))|(((
--String, absolute file system path
++String, absolute file system path or
++absolute workspace path or project relative path
  )))|(((
--/home/myuser/process_output.simout
++myFolder/myFile.simout
  )))|(((
--The file location of the target file
++The target file
  )))
  |(((
  modelName
@@ -318,9 +318,21 @@
  Name of the model in the simulation that will be written as JSON object to the simout file
  )))
++=== Variable Setter ===
++
++This data handler is only used for easier debugging and setting up simulations for different test runs. It sets the variables in the data pool to constant values, typically once for the simulation in the initialization part of a kisim file.
++
++\\
++
++\\
++
++\\
++
++----
++
  == KiSim ==
--Which data handlers are used and which actions are performed on them can be configured using a DSL, namely **KiSim**.
++Which data handlers are used and which actions are performed on them for each macro tick can be configured using a DSL, namely **KiSim**.
  A kisim file contains two main parts:

Confluence.Code.ConfluencePageClass[0]

Id

@@ -1,1 +1,1 @@
--31162495
++33260019

URL

@@ -1,1 +1,1 @@
--https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/31162495/V2 Simulation
++https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/33260019/V2 Simulation

Changes for page Simulation (KiSim)

Summary

Details

Navigation

Quick Links