Wiki source code of V2 Simulation

Version 8.1 by aas2 on 2017/10/23 16:34
Show last authors
1 = Simulation of Models in KIELER =
2
3
4
5 {{toc/}}
6
7 ----
8
9 == Overview ==
10
11 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
13 * Receive inputs for the next tick
14 * Execute a tick
15 * Send generated outputs
16
17 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.
18
19 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.
20
21 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:
22
23 * Compiling a model using the KIELER compiler
24 * Generating the simulation wrapper code for the model using template processing
25 * Compiling the resulting code using, e.g., gcc.
26
27 For more insight of the simulation generation, please take a look at the [[doc:V2 Project Management]].
28
29 ----
30
31 == Using the Simulation ==
32
33 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.
34
35 (% class="relative-table wrapped" style="width: 99.9453%;" %)
36 |=(((
37 Selection
38 )))|=(% colspan="1" %)(% colspan="1" %)
39 (((
40 Example Selection
41 )))|=(((
42 Macro Tick Configuration of Simulation
43 )))
44 |(% colspan="1" %)(% colspan="1" %)
45 (((
46 1 executable
47 )))|(% colspan="1" %)(% colspan="1" %)
48 (((
49 Sim_ModelA.exe
50 )))|(% colspan="1" %)(% colspan="1" %)
51 (((
52 Performs a single tick and updates the pool with the received data from the process
53 )))
54 |(% colspan="1" %)(% colspan="1" %)
55 (((
56 2 executables
57 )))|(% colspan="1" %)(% colspan="1" %)
58 (((
59 Sim_ModelA.exe, Sim_ModelB.exe
60 )))|(% colspan="1" %)(% colspan="1" %)
61 (((
62 Starts two executable data handlers with bidirectional redirection of inputs/outputs between the models. So the performed steps are:
63
64 Execute tick of A, redirect A→B, execute tick of B, redirect B → A
65 )))
66 |(% colspan="1" %)(% colspan="1" %)
67 (((
68 1 kisim file
69 )))|(% colspan="1" %)(% colspan="1" %)
70 (((
71 ComplexSimulation.kisim
72 )))|(% colspan="1" %)(% colspan="1" %)
73 (((
74 Uses the explicit configuration from the file
75 )))
76 |(% colspan="1" %)(% colspan="1" %)
77 (((
78 1 executable, 1 trace file
79 )))|(% colspan="1" %)(% colspan="1" %)
80 (((
81 Sim_ModelA.exe, TraceOfModelA.eso
82 )))|(% colspan="1" %)(% colspan="1" %)
83 (((
84 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.
85 )))
86 |(% colspan="1" %)(% colspan="1" %)
87 (((
88 1 simin file
89 )))|(% colspan="1" %)(% colspan="1" %)
90 (((
91 process_output.simin
92 )))|(% colspan="1" %)(% colspan="1" %)
93 (((
94 The simin file must contain a JSON object for some model. The data pool of the simulation is then updated with its contents.
95 )))
96 |(% colspan="1" %)(% colspan="1" %)
97 (((
98 1 simout file
99 )))|(% colspan="1" %)(% colspan="1" %)
100 (((
101 simulation_output.simout
102 )))|(% colspan="1" %)(% colspan="1" %)
103 (((
104 A model of the simulation is written as JSON object to the simout file.
105 )))
106
107 === Playing the Simulation ===
108
109 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).
110
111 === Stepping Back in the Simulation ===
112
113 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.
114
115 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**.
116
117 === The Data Pool View ===
118
119 The current data pool can be seen in the Data Pool View (Window > Show View > Other > KIELER Simulation > Data Pool View).
120
121 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.
122
123 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.
124
125 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.
126
127 ----
128
129 == Data Handlers ==
130
131 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.
132
133 Which handlers are available are explained in the following.
134
135 === Executable ===
136
137 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.
138
139 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.
140
141 (% class="wrapped" %)
142 |=(((
143 Attribute
144 )))|=(% colspan="1" %)(% colspan="1" %)
145 (((
146 Domain
147 )))|=(% colspan="1" %)(% colspan="1" %)
148 (((
149 Example
150 )))|=(((
151 Description
152 )))
153 |(% colspan="1" %)(% colspan="1" %)
154 (((
155 executable
156 )))|(% colspan="1" %)(% colspan="1" %)
157 (((
158 String, absolute workspace path or project relative path
159 )))|(% colspan="1" %)(% colspan="1" %)
160 (((
161 /MyProject/kieler-gen/sim/bin/Sim_MyModel.exe
162 )))|(% colspan="1" %)(% colspan="1" %)
163 (((
164 The path to the executable
165 )))
166 |(% colspan="1" %)(% colspan="1" %)
167 (((
168 command
169 )))|(% colspan="1" %)(% colspan="1" %)
170 (((
171 String, the shell command that is used to start the process
172 )))|(% colspan="1" %)(% colspan="1" %)
173 (((
174 python "${executable_path}"
175 )))|(% colspan="1" %)(% colspan="1" %)
176 (((
177 The shell command to start the executable
178 )))
179
180 === Redirect ===
181
182 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.
183
184 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.
185
186 (% class="wrapped" %)
187 |=(((
188 Attribute
189 )))|=(((
190 Domain
191 )))|=(((
192 Example
193 )))|=(((
194 Description
195 )))
196 |(((
197 from
198 )))|(((
199 String, name of a model in the simulation
200 )))|(((
201 Sim_ModelA.exe
202 MyModelA
203 )))|(((
204 The name of the model of which the outputs are read
205 )))
206 |(((
207 to
208 )))|(((
209 String, name of a model in the simulation
210 )))|(((
211 Sim_ModelB.exe
212 MyModelB
213 )))|(((
214 The name of the model of which the inputs are set
215 )))
216 |(% colspan="1" %)(% colspan="1" %)
217 (((
218 mapping
219 )))|(% colspan="1" %)(% colspan="1" %)
220 (((
221 Map, The key is an output variable and the value is an input variable
222 )))|(% colspan="1" %)(% colspan="1" %)
223 (((
224 (% class="content-wrapper" %)
225 (((
226 configure redirect A_to_B {
227 from: A
228 to: B
229 mapping {
230 someOutputOfA: someInputOfB
231 other OutputOfA: otherInputOfB
232 }
233 }
234 )))
235 )))|(% colspan="1" %)(% colspan="1" %)
236 (((
237 Defines which output variables should be mapped to which input variables
238 )))
239
240 === Trace ===
241
242 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).
243 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.
244
245 Thus the typical simulation setup to use a trace data handler for a model A is:
246
247 * Set the input of the model to the inputs from the trace (write)
248 * Perform the tick of the model A
249 * Compare the outputs of the trace and the model A (check)
250 * Go to the next tick in the trace (loadNextTick)
251
252 (% class="wrapped" %)
253 |=(((
254 Attribute
255 )))|=(((
256 Domain
257 )))|=(((
258 Example
259 )))|=(((
260 Description
261 )))
262 |(((
263 file
264 )))|(((
265 String, absolute workspace path or project relative path
266 )))|(((
267 MyTrace.eso
268 )))|(((
269 The trace file to be used
270 )))
271 |(((
272 modelName
273 )))|(((
274 String, name of a model in the simulation
275 )))|(((
276 Sim_ModelA.exe
277
278 MyModelA
279 )))|(((
280 The model in the simulation for which the trace is for
281 )))
282 |(% colspan="1" %)(% colspan="1" %)
283 (((
284 traceNumber
285 )))|(% colspan="1" %)(% colspan="1" %)
286 (((
287 Integer
288 )))|(% colspan="1" %)(% colspan="1" %)
289 (((
290 0
291 )))|(% colspan="1" %)(% colspan="1" %)
292 (((
293 In case there are multiple traces in the eso file, determines which trace should be used.
294 Default is 0
295 )))
296 |(% colspan="1" %)(% colspan="1" %)
297 (((
298 tickNumber
299 )))|(% colspan="1" %)(% colspan="1" %)
300 (((
301 Integer
302 )))|(% colspan="1" %)(% colspan="1" %)
303 (((
304 0
305 )))|(% colspan="1" %)(% colspan="1" %)
306 (((
307 The tick of which the input is set. This can be used to skip some ticks of the trace.
308 Default is 0
309 )))
310 |(% colspan="1" %)(% colspan="1" %)
311 (((
312 checkInterface
313 )))|(% colspan="1" %)(% colspan="1" %)
314 (((
315 Boolean
316 )))|(% colspan="1" %)(% colspan="1" %)
317 (((
318 true
319 )))|(% colspan="1" %)(% colspan="1" %)
320 (((
321 Determines if the interface of the trace and model should be compared.
322 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.
323 If this is false and for example the trace contains a variable that does not exist in the model, this issue is ignored.
324 )))
325
326 \\
327
328 === Simulation Input Files ===
329
330 The simulation can communicate with executables via stdin and stdout. To use this, the executable has to be started from within KIELER.
331
332 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.
333
334 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.
335
336 Simulation input files can also be used to feed the simulation with data to be visualized via the simulation visualization.
337
338 (% class="relative-table wrapped" style="width: 81.5545%;" %)
339 |=(((
340 Attribute
341 )))|=(((
342 Domain
343 )))|=(((
344 Example
345 )))|=(((
346 Description
347 )))
348 |(((
349 file
350 )))|(((
351 String, absolute file system path or
352 absolute workspace path or project relative path
353 )))|(((
354 /home/myuser/process_output.simin
355 )))|(((
356 The target file
357 )))
358 |(((
359 modelName
360 )))|(((
361 String, name of a model
362 )))|(((
363 MyModel
364 )))|(((
365 Name of the model in the simulation that the data in the simin file is for.
366 )))
367
368 \\
369
370 === Simulation Outputs Files ===
371
372 This data handler writes the output of the model in the simulation to the specified file.
373
374 (% class="relative-table wrapped" style="width: 81.7734%;" %)
375 |=(((
376 Attribute
377 )))|=(((
378 Domain
379 )))|=(((
380 Example
381 )))|=(((
382 Description
383 )))
384 |(((
385 file
386 )))|(((
387 String, absolute file system path or
388 absolute workspace path or project relative path
389 )))|(((
390 myFolder/myFile.simout
391 )))|(((
392 The target file
393 )))
394 |(((
395 modelName
396 )))|(((
397 String, name of a model
398 )))|(((
399 MyModel
400 )))|(((
401 Name of the model in the simulation that will be written as JSON object to the simout file
402 )))
403
404 === Variable Setter ===
405
406 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.
407
408 (% class="relative-table wrapped" %)
409 |=(((
410 Attribute
411 )))|=(((
412 Domain
413 )))|=(((
414 Example
415 )))|=(((
416 Description
417 )))
418 |(((
419 variables
420 )))|(((
421 Map, The key is the variable name, the value is the value for this variable
422 )))|(((
423 configure setter S {
424 variables {
425 I: true
426 O: 5
427 MyModel.MyVar: -1
428 }
429 }
430 )))|(((
431 Sets the variables in to the given values.
432
433 This way different setters can be defined for different simulation runs or manual testing.
434 )))
435
436 \\
437
438 \\
439
440 ----
441
442 == KiSim ==
443
444 Which data handlers are used and which actions are performed on them for each macro tick can be configured using a DSL, namely **KiSim**.
445
446 A kisim file contains two main parts:
447
448 * Configuration of data handlers
449 * Actions to be performed on the data handlers for each a macro tick
450
451 Besides these, an optional initialization part can be used to perform actions on data handlers once at startup.
452
453 === Examples ===
454
455 The following shows examples of kisim files.
456
457 Configuration to simulate a single executable:
458
459 {{code title="Single Executable"}}
460 configure sim Test {
461 executable: kielger-gen/sim/bin/Sim_Test
462 }
463
464 execution {
465 write sim Test
466 }
467 {{/code}}
468
469 \\
470
471 Configuration for two executables with redirection between both:
472
473 {{code}}
474 configure sim A {
475 executable: kielger-gen/sim/bin/Sim_Test
476 }
477 configure sim B {
478 executable: kielger-gen/sim/bin/Sim_Test2
479 }
480
481 configure redirect A_to_B{
482 from: A
483 to: B
484 }
485
486 configure redirect B_to_A{
487 from: B
488 to: A
489 }
490
491 execution {
492 write sim A
493 write redirect A_to_B
494 write sim B
495 write redirect B_to_A
496 }
497 {{/code}}
498
499 Using a trace for a model:
500
501 {{code}}
502 configure sim A {
503 executable: kielger-gen/sim/bin/Sim_Test
504 }
505
506 configure trace A {
507 file: MyTrace.eso
508 modelName: A
509 }
510
511 execution {
512 write trace A // Set inputs of model to values from trace
513 write sim A // Perform tick of model
514 read trace A // Compare outputs of model with values from trace
515 }
516 {{/code}}
517
518 Feeding inputs of a model from a simin file:
519
520 {{code}}
521 configure sim A {
522 executable: kielger-gen/sim/bin/Sim_Test
523 }
524
525 configure simin SimInput {
526 file: process_output.simin
527 }
528
529 configure redirect SimInput_to_A{
530 from: SimInput
531 to: A
532 }
533
534 execution {
535 write simin SimIn
536 write redirect SimInput_to_A
537 write sim A
538 }
539 {{/code}}
540
541 Sets the variables for manual testing:
542
543 {{code}}
544 configure sim A {
545 executable: kieler-gen/sim/bin/Sim_Test.exe
546 }
547
548 configure setter S {
549 variables {
550 x: 100
551 y: 100
552 }
553 }
554
555 initialization {
556 write setter S
557 }
558
559 execution {
560 write sim A
561 }
562 {{/code}}
563
564 \\
565
566 == Implementation Details ==
567
568 The following are details about the implementation of the simulation and the JSON format that is used to communicate the variables in the models.
569
570 As said above the simulation is seen as black box which takes inputs on stdin, computes a reaction, and sends outputs stdout. Thus an executable simulation is a normal program that communicates in a specific JSON format and can also be used from command line.
571 \\
572
573 === The JSON Format ===
574
575 The JSON format is designed to communicate the state of a simulation. In KIELER such a state is saved as a single data pool. This means the JSON format for the communication with running simulations is also the JSON format for data pools.
576
577 It mainly consists of a list of models and a map of models. The models consist mainly of a map of their variables. The most important field of a variable is their value.
578
579 {{code}}
580 { "MODEL_NAME0" : {
581 "VAR0":{"value": "VAR0_VALUE"}, "VAR1":{"value":"VAR1_VALUE"}, ...
582 }
583 "MODEL_NAME1" : {
584 "VAR0":{"value": "VAR0_VALUE"}, "VAR1":{"value":"VAR1_VALUE"}, ...
585 }
586 ...
587 "actionIndex" : "ACTION_INDEX_AFTER_WHICH_THE_DATA_POOL_WAS_CREATED"
588 }
589 {{/code}}
590
591 Besides these core informations, an additional field "actionIndex" can be set for the data pool. In the simulation the actions of data handlers are executed to create a macro tick. Therefore the action index takes the task of a program counter. It determines the next action to be executed. Thus in the JSON format the field "actionIndex" can be set to store when the data pool was created in the simulation.
592
593 There are also additional fields for variables than their value. However these only need to be communicated once after the initialization of the model and are explained in the table below.
594
595 |=(((
596 Field Name
597 )))|=(((
598 Example Values
599 )))|=(((
600 Description
601 )))
602 |(((
603 type
604 )))|(((
605 int
606
607 bool
608
609 pure
610
611 float
612
613 double
614
615 string
616 )))|(((
617 The type of the variable in the source model.
618
619 Because this information is lost in general in the compilation (for instance a bool is compiled to a char in C code), the simulation can communicate the intended variable type in the source model.
620 )))
621 |(((
622 interface
623 )))|(((
624 0
625
626 1
627
628 2
629
630 3
631
632 4
633
634 5
635
636 6
637 )))|(((
638 Bitmask, that determines how the variable is used in the source model's interface (e.g. input, output, internal, other).
639 A bitmask has been choosen because a mixture of a variables interface types is possible (e.g. input, output, input output)
640
641 |=(((
642 Interface Type
643 )))|=(((
644 Binary Bitmask
645 )))|=(((
646 Decimal Number
647 )))
648 |(((
649 Other
650 )))|(((
651 0000
652 )))|(((
653 0
654 )))
655 |(% colspan="1" %)(% colspan="1" %)
656 (((
657 Internal
658 )))|(% colspan="1" %)(% colspan="1" %)
659 (((
660 0001
661 )))|(% colspan="1" %)(% colspan="1" %)
662 (((
663 1
664 )))
665 |(% colspan="1" %)(% colspan="1" %)
666 (((
667 Output
668 )))|(% colspan="1" %)(% colspan="1" %)
669 (((
670 0010
671 )))|(% colspan="1" %)(% colspan="1" %)
672 (((
673 2
674 )))
675 |(% colspan="1" %)(% colspan="1" %)
676 (((
677 Input
678 )))|(% colspan="1" %)(% colspan="1" %)
679 (((
680 0100
681 )))|(% colspan="1" %)(% colspan="1" %)
682 (((
683 4
684 )))
685 |(% colspan="1" %)(% colspan="1" %)
686 (((
687 Input Output
688 )))|(% colspan="1" %)(% colspan="1" %)
689 (((
690 0110
691 )))|(% colspan="1" %)(% colspan="1" %)
692 (((
693 6
694 )))
695
696 Not that internal is intended for variables that are neither input nor output but still part of the source model, in contrast to variables that are created in the compilation (e.g. register flags).
697 Anyway an input and output is also a internal variable normally.
698 )))
699
700 === Python Example ===
701
702 \\

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage