Wiki source code of V2 Simulation

Version 5.1 by aas2 on 2017/08/03 14:38
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. 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.
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 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 started as 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 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 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 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 simout file
99 )))|(% colspan="1" %)(% colspan="1" %)
100 (((
101 simulation_output.simout
102 )))|(% colspan="1" %)(% colspan="1" %)
103 (((
104 The current pool of the simulation is written as JSON object to the simout file.
105 )))
106
107 === Playing the Simulation ===
108
109 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).
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.
114
115 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.
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//.
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.
126
127 ----
128
129 == Data Handlers ==
130
131 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.
132
133 Which handlers are available are explained in the following.
134
135 === Executable ===
136
137 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.
138
139 (% class="wrapped" %)
140 |=(((
141 Attribute
142 )))|=(% colspan="1" %)(% colspan="1" %)
143 (((
144 Domain
145 )))|=(% colspan="1" %)(% colspan="1" %)
146 (((
147 Example
148 )))|=(((
149 Description
150 )))
151 |(% colspan="1" %)(% colspan="1" %)
152 (((
153 executable
154 )))|(% colspan="1" %)(% colspan="1" %)
155 (((
156 String, absolute workspace path or project relative path
157 )))|(% colspan="1" %)(% colspan="1" %)
158 (((
159 /MyProject/kieler-gen/sim/bin/Sim_MyModel.exe
160 )))|(% colspan="1" %)(% colspan="1" %)
161 (((
162 The path to the executable
163 )))
164
165 === Redirect ===
166
167 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.
168
169 (% class="wrapped" %)
170 |=(((
171 Attribute
172 )))|=(((
173 Domain
174 )))|=(((
175 Example
176 )))|=(((
177 Description
178 )))
179 |(((
180 from
181 )))|(((
182 String, name of a model in the simulation
183 )))|(((
184 Sim_ModelA.exe
185 MyModelA
186 )))|(((
187 The name of the model of which the outputs are read
188 )))
189 |(((
190 to
191 )))|(((
192 String, name of a model in the simulation
193 )))|(((
194 Sim_ModelB.exe
195 MyModelB
196 )))|(((
197 The name of the model of which the inputs are set
198 )))
199
200 === Trace ===
201
202 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.
203
204 The typical setup to use a trace data handler for a model A is:
205
206 * Read inputs for model from trace
207 * Perform the tick of the model A
208 * Compare the outputs of the trace and the model A
209
210 (% class="wrapped" %)
211 |=(((
212 Attribute
213 )))|=(((
214 Domain
215 )))|=(((
216 Example
217 )))|=(((
218 Description
219 )))
220 |(((
221 file
222 )))|(((
223 String, project relative path
224 )))|(((
225 MyTrace.eso
226 )))|(((
227 The trace file to be used
228 )))
229 |(((
230 modelName
231 )))|(((
232 String, name of a model in the simulation
233 )))|(((
234 Sim_ModelA.exe
235
236 MyModelA
237 )))|(((
238 The model in the simulation for which the trace is for
239 )))
240 |(% colspan="1" %)(% colspan="1" %)
241 (((
242 checkOutputs
243 )))|(% colspan="1" %)(% colspan="1" %)
244 (((
245 Boolean
246 )))|(% colspan="1" %)(% colspan="1" %)
247 (((
248 true
249 false
250 )))|(% colspan="1" %)(% colspan="1" %)
251 (((
252 If false, the outputs of the trace and simulation are not compared and the next tick is loaded after inputs have been set.
253 Use this option when only the //write// method of the data handler is used, but not its //read// method.
254 )))
255 |(% colspan="1" %)(% colspan="1" %)
256 (((
257 traceNumber
258 )))|(% colspan="1" %)(% colspan="1" %)
259 (((
260 Integer
261 )))|(% colspan="1" %)(% colspan="1" %)
262 (((
263 0
264 )))|(% colspan="1" %)(% colspan="1" %)
265 (((
266 In case there are multiple traces in the eso file, determines which trace should be used.
267 Default is 0
268 )))
269 |(% colspan="1" %)(% colspan="1" %)
270 (((
271 tickNumber
272 )))|(% colspan="1" %)(% colspan="1" %)
273 (((
274 Integer
275 )))|(% colspan="1" %)(% colspan="1" %)
276 (((
277 0
278 )))|(% colspan="1" %)(% colspan="1" %)
279 (((
280 The tick of which the input is set. This can be used to skip some ticks of the trace.
281 Default is 0
282 )))
283
284 \\
285
286 === Simulation Input Files ===
287
288 The simulation can communicate with executables via stdin and stdout. To use this, the executable has to be started from within KIELER.
289
290 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.
291
292 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.
293
294 Simulation input files can also be used to feed the simulation with data to be visualized via the simulation visualization.
295
296 (% class="relative-table wrapped" style="width: 81.5545%;" %)
297 |=(((
298 Attribute
299 )))|=(((
300 Domain
301 )))|=(((
302 Example
303 )))|=(((
304 Description
305 )))
306 |(((
307 fileLocation
308 )))|(((
309 String, absolute file system path
310 )))|(((
311 /home/myuser/process_output.simin
312 )))|(((
313 The file location of the file containing the JSON object
314 )))
315 |(((
316 modelName
317 )))|(((
318 String, name of a model
319 )))|(((
320 MyModel
321 )))|(((
322 Name of the model in the simulation that the data in the simin file is for.
323 )))
324
325 \\
326
327 === Simulation Outputs Files ===
328
329 This data handler writes the output of the model in the simulation to the specified file.
330
331 (% class="relative-table wrapped" style="width: 81.7734%;" %)
332 |=(((
333 Attribute
334 )))|=(((
335 Domain
336 )))|=(((
337 Example
338 )))|=(((
339 Description
340 )))
341 |(((
342 fileLocation
343 )))|(((
344 String, absolute file system path
345 )))|(((
346 /home/myuser/process_output.simout
347 )))|(((
348 The file location of the target file
349 )))
350 |(((
351 modelName
352 )))|(((
353 String, name of a model
354 )))|(((
355 MyModel
356 )))|(((
357 Name of the model in the simulation that will be written as JSON object to the simout file
358 )))
359
360 ----
361
362 == KiSim ==
363
364 Which data handlers are used and which actions are performed on them for each macro tick can be configured using a DSL, namely **KiSim**.
365
366 A kisim file contains two main parts:
367
368 * Configuration of data handlers
369 * Actions to be performed on the data handlers for each a macro tick
370
371 Besides these, an optional initialization part can be used to perform actions on data handlers once at startup.
372
373 === Examples ===
374
375 The following shows examples of kisim files.
376
377 Configuration to simulate a single executable:
378
379 {{code title="Single Executable"}}
380 configure sim Test {
381 executable: kielger-gen/sim/bin/Sim_Test
382 }
383
384 execution {
385 write sim Test
386 }
387 {{/code}}
388
389 \\
390
391 Configuration for two executables with redirection between both:
392
393 {{code}}
394 configure sim A {
395 executable: kielger-gen/sim/bin/Sim_Test
396 }
397 configure sim B {
398 executable: kielger-gen/sim/bin/Sim_Test2
399 }
400
401 configure redirect A_to_B{
402 from: A
403 to: B
404 }
405
406 configure redirect B_to_A{
407 from: B
408 to: A
409 }
410
411 execution {
412 write sim A
413 write redirect A_to_B
414 write sim B
415 write redirect B_to_A
416 }
417 {{/code}}
418
419 Using a trace for a model:
420
421 {{code}}
422 configure sim A {
423 executable: kielger-gen/sim/bin/Sim_Test
424 }
425
426 configure trace A {
427 file: MyTrace.eso
428 modelName: A
429 }
430
431 execution {
432 write trace A // Set inputs of model to values from trace
433 write sim A // Perform tick of model
434 read trace A // Compare outputs of model with values from trace
435 }
436 {{/code}}
437
438 Feeding inputs of a model from a simin file:
439
440 {{code}}
441 configure sim A {
442 executable: kielger-gen/sim/bin/Sim_Test
443 }
444
445 configure simin SimInput {
446 file: process_output.simin
447 }
448
449 configure redirect SimInput_to_A{
450 from: SimInput
451 to: A
452 }
453
454 execution {
455 write simin SimIn
456 write redirect SimInput_to_A
457 write sim A
458 }
459 {{/code}}
460
461 \\
462
463 \\

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage