Wiki source code of Simulation (KiSim)

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

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage