Wiki source code of V2 Simulation

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

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage