Wiki source code of Simulation (KiSim)

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

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage