Wiki source code of V2 Simulation

Version 3.1 by aas2 on 2017/08/03 13:42
Show last authors
1 = Simulation of Models in KIELER =
2
3
4
5 {{toc/}}
6
7 == Overview ==
8
9 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
10
11 * Receive inputs for the next tick
12 * Execute a tick
13 * Send generated outputs
14
15 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.
16
17 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.
18
19 == Using the Simulation ==
20
21 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.
22
23 (% class="relative-table wrapped" style="width: 99.9453%;" %)
24 |=(((
25 Selection
26 )))|=(% colspan="1" %)(% colspan="1" %)
27 (((
28 Example Selection
29 )))|=(((
30 Macro Tick Configuration of Simulation
31 )))
32 |(% colspan="1" %)(% colspan="1" %)
33 (((
34 executable
35 )))|(% colspan="1" %)(% colspan="1" %)
36 (((
37 Sim_ModelA.exe
38 )))|(% colspan="1" %)(% colspan="1" %)
39 (((
40 Performs a single tick and updates the pool with the received data from the process
41 )))
42 |(% colspan="1" %)(% colspan="1" %)
43 (((
44 2 executables
45 )))|(% colspan="1" %)(% colspan="1" %)
46 (((
47 Sim_ModelA.exe, Sim_ModelB.exe
48 )))|(% colspan="1" %)(% colspan="1" %)
49 (((
50 Starts two executable data handlers with bidirectional redirection of inputs/outputs between the models. So the performed steps are:
51
52 Execute tick of A, redirect A→B, execute tick of B, redirect B → A
53 )))
54 |(% colspan="1" %)(% colspan="1" %)
55 (((
56 kisim file
57 )))|(% colspan="1" %)(% colspan="1" %)
58 (((
59 ComplexSimulation.kisim
60 )))|(% colspan="1" %)(% colspan="1" %)
61 (((
62 Uses the explicit configuration from the file
63 )))
64 |(% colspan="1" %)(% colspan="1" %)
65 (((
66 1 executable, 1 trace file
67 )))|(% colspan="1" %)(% colspan="1" %)
68 (((
69 Sim_ModelA.exe, TraceOfModelA.eso
70 )))|(% colspan="1" %)(% colspan="1" %)
71 (((
72 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.
73 )))
74 |(% colspan="1" %)(% colspan="1" %)
75 (((
76 simin file
77 )))|(% colspan="1" %)(% colspan="1" %)
78 (((
79 process_output.simin
80 )))|(% colspan="1" %)(% colspan="1" %)
81 (((
82 The simin file must contain a JSON object for some model. The data pool of the simulation is then updated with its contents.
83 )))
84 |(% colspan="1" %)(% colspan="1" %)
85 (((
86 simout file
87 )))|(% colspan="1" %)(% colspan="1" %)
88 (((
89 simulation_output.simout
90 )))|(% colspan="1" %)(% colspan="1" %)
91 (((
92 The current pool of the simulation is written as JSON object to the simout file.
93 )))
94
95 === Playing the Simulation ===
96
97 Besided manually stepping through the simulation tick after tick, it is possible to let the simulation play automatically. In play mode, 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).
98
99 === Stepping Back in the Simulation ===
100
101 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.
102
103 This it is possible to revert a model to a previous state if all variables that define the current state of this model are recorded in the data pool.
104
105 === The Data Pool View ===
106
107 The current data pool can be seen in the Data Pool View (Window > Show View > Other > KIELER Simulation > Data Pool View).
108
109 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.
110
111 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//.
112
113 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.
114
115 == Data Handlers ==
116
117 A simulation consists of a list of //data handlers//, that can read or write the current data pool. A macro tick in the simulation then consists of the execution of the read or write actions on these data handlers. Performing a single action on a data handler is called a //sub tick// and typically not necessary but can be useful to see the effect of single data handlers on the data pool.
118
119 Which handlers are available are explained in the following.
120
121 === Executable ===
122
123 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.
124
125 (% class="wrapped" %)
126 |=(((
127 Attribute
128 )))|=(% colspan="1" %)(% colspan="1" %)
129 (((
130 Domain
131 )))|=(% colspan="1" %)(% colspan="1" %)
132 (((
133 Example
134 )))|=(((
135 Description
136 )))
137 |(% colspan="1" %)(% colspan="1" %)
138 (((
139 executable
140 )))|(% colspan="1" %)(% colspan="1" %)
141 (((
142 String, absolute workspace path or project relative path
143 )))|(% colspan="1" %)(% colspan="1" %)
144 (((
145 /MyProject/kieler-gen/sim/bin/Sim_MyModel.exe
146 )))|(% colspan="1" %)(% colspan="1" %)
147 (((
148 The path to the executable
149 )))
150
151 === Redirect ===
152
153 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.
154
155 (% class="wrapped" %)
156 |=(((
157 Attribute
158 )))|=(((
159 Domain
160 )))|=(((
161 Example
162 )))|=(((
163 Description
164 )))
165 |(((
166 from
167 )))|(((
168 String, name of a model in the simulation
169 )))|(((
170 Sim_ModelA.exe
171 MyModelA
172 )))|(((
173 The name of the model of which the outputs are read
174 )))
175 |(((
176 to
177 )))|(((
178 String, name of a model in the simulation
179 )))|(((
180 Sim_ModelB.exe
181 MyModelB
182 )))|(((
183 The name of the model of which the inputs are set
184 )))
185
186 === Trace ===
187
188 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.
189
190 The typical setup to use a trace data handler for a model A is:
191
192 * Read inputs for model from trace
193 * Perform the tick of the model A
194 * Compare the outputs of the trace and the model A
195
196 (% class="wrapped" %)
197 |=(((
198 Attribute
199 )))|=(((
200 Domain
201 )))|=(((
202 Example
203 )))|=(((
204 Description
205 )))
206 |(((
207 file
208 )))|(((
209 String, project relative path
210 )))|(((
211 MyTrace.eso
212 )))|(((
213 The trace file to be used
214 )))
215 |(((
216 modelName
217 )))|(((
218 String, name of a model in the simulation
219 )))|(((
220 Sim_ModelA.exe
221
222 MyModelA
223 )))|(((
224 The model in the simulation for which the trace is for
225 )))
226 |(% colspan="1" %)(% colspan="1" %)
227 (((
228 checkOutputs
229 )))|(% colspan="1" %)(% colspan="1" %)
230 (((
231 Boolean
232 )))|(% colspan="1" %)(% colspan="1" %)
233 (((
234 true
235 false
236 )))|(% colspan="1" %)(% colspan="1" %)
237 (((
238 If false, the outputs of the trace and simulation are not compared and the next tick is loaded after inputs have been set.
239 Use this option when only the //write// method of the data handler is used, but not its //read// method.
240 )))
241 |(% colspan="1" %)(% colspan="1" %)
242 (((
243 traceNumber
244 )))|(% colspan="1" %)(% colspan="1" %)
245 (((
246 Integer
247 )))|(% colspan="1" %)(% colspan="1" %)
248 (((
249 0
250 )))|(% colspan="1" %)(% colspan="1" %)
251 (((
252 In case there are multiple traces in the eso file, determines which trace should be used.
253 Default is 0
254 )))
255 |(% colspan="1" %)(% colspan="1" %)
256 (((
257 tickNumber
258 )))|(% colspan="1" %)(% colspan="1" %)
259 (((
260 Integer
261 )))|(% colspan="1" %)(% colspan="1" %)
262 (((
263 0
264 )))|(% colspan="1" %)(% colspan="1" %)
265 (((
266 The tick of which the input is set. This can be used to skip some ticks of the trace.
267 Default is 0
268 )))
269
270 \\
271
272 === Simulation Input Files ===
273
274 The simulation can communicate with executables via stdin and stdout. To use this, the executable has to be started from within KIELER.
275
276 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.
277
278 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.
279
280 Simulation input files can also be used to feed the simulation with data to be visualized via the simulation visualization.
281
282 (% class="relative-table wrapped" style="width: 81.5545%;" %)
283 |=(((
284 Attribute
285 )))|=(((
286 Domain
287 )))|=(((
288 Example
289 )))|=(((
290 Description
291 )))
292 |(((
293 fileLocation
294 )))|(((
295 String, absolute file system path
296 )))|(((
297 /home/myuser/process_output.simin
298 )))|(((
299 The file location of the file containing the JSON object
300 )))
301 |(((
302 modelName
303 )))|(((
304 String, name of a model
305 )))|(((
306 MyModel
307 )))|(((
308 Name of the model in the simulation that the data in the simin file is for.
309 )))
310
311 \\
312
313 === Simulation Outputs Files ===
314
315 This data handler writes the output of the model in the simulation to the specified file.
316
317 (% class="relative-table wrapped" style="width: 81.7734%;" %)
318 |=(((
319 Attribute
320 )))|=(((
321 Domain
322 )))|=(((
323 Example
324 )))|=(((
325 Description
326 )))
327 |(((
328 fileLocation
329 )))|(((
330 String, absolute file system path
331 )))|(((
332 /home/myuser/process_output.simout
333 )))|(((
334 The file location of the target file
335 )))
336 |(((
337 modelName
338 )))|(((
339 String, name of a model
340 )))|(((
341 MyModel
342 )))|(((
343 Name of the model in the simulation that will be written as JSON object to the simout file
344 )))
345
346 == KiSim ==
347
348 Which data handlers are used and which actions are performed on them for each macro tick can be configured using a DSL, namely **KiSim**.
349
350 A kisim file contains two main parts:
351
352 * Configuration of data handlers
353 * Actions to be performed on the data handlers for each a macro tick
354
355 Besides these, an optional initialization part can be used to perform actions on data handlers once at startup.
356
357 === Examples ===
358
359 The following shows examples of kisim files.
360
361 Configuration to simulate a single executable:
362
363 {{code title="Single Executable"}}
364 configure sim Test {
365 executable: kielger-gen/sim/bin/Sim_Test
366 }
367
368 execution {
369 write sim Test
370 }
371 {{/code}}
372
373 \\
374
375 Configuration for two executables with redirection between both:
376
377 {{code}}
378 configure sim A {
379 executable: kielger-gen/sim/bin/Sim_Test
380 }
381 configure sim B {
382 executable: kielger-gen/sim/bin/Sim_Test2
383 }
384
385 configure redirect A_to_B{
386 from: A
387 to: B
388 }
389
390 configure redirect B_to_A{
391 from: B
392 to: A
393 }
394
395 execution {
396 write sim A
397 write redirect A_to_B
398 write sim B
399 write redirect B_to_A
400 }
401 {{/code}}
402
403 Using a trace for a model:
404
405 {{code}}
406 configure sim A {
407 executable: kielger-gen/sim/bin/Sim_Test
408 }
409
410 configure trace A {
411 file: MyTrace.eso
412 modelName: A
413 }
414
415 execution {
416 write trace A // Set inputs of model to values from trace
417 write sim A // Perform tick of model
418 read trace A // Compare outputs of model with values from trace
419 }
420 {{/code}}
421
422 Feeding inputs of a model from a simin file:
423
424 {{code}}
425 configure sim A {
426 executable: kielger-gen/sim/bin/Sim_Test
427 }
428
429 configure simin SimInput {
430 file: process_output.simin
431 }
432
433 configure redirect SimInput_to_A{
434 from: SimInput
435 to: A
436 }
437
438 execution {
439 write simin SimIn
440 write redirect SimInput_to_A
441 write sim A
442 }
443 {{/code}}
444
445 \\
446
447 \\

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage