hio_module.h
Go to the documentation of this file.
1 /** @file hio_module.h Class describing the I/O based hierarchy */
2 
3 /* Hierarchical IO Systems Plug-In for FAU Discrete Event Systems Library (libfaudes)
4 
5  Copyright (C) 2006 Sebastian Perk
6  Copyright (C) 2006 Thomas Moor
7  Copyright (C) 2006 Klaus Schmidt
8 
9 */
10 
11 #ifndef FAUDES_HIO_MODULE_H
12 #define FAUDES_HIO_MODULE_H
13 
14 #include "hio_helper.h"
15 #include "hio_functions.h"
16 #include <list>
17 #include <cmath>
18 
19 namespace faudes {
20 
21 /**
22 * Recurring structure in hierarchies designed according to the I/O based DES framework.
23 * The HioModule class is a composite pattern providing access to the components of a
24 * I/O-controller synthesis problem for a composite I/O-plant:
25 *
26 * - Operator-constraint: describes liveness properties of I/O-plant, together with
27 * environment-constraint
28 * - Plant: abstraction and at the same time specification of the external
29 * closed-loop behaviour of the HioModule.
30 * - Controller enforcing the desired behaviour
31 * - children-vector of (pointers to) subordinate HioModules
32 * - Environment
33 * - Environment-constraint: describes liveness properties of I/O-plant, together with
34 * operator-constraint
35 *
36 * The plants of the subordinate HioModules and the environment form the
37 * uncontrolled behaviour of the HioModule.
38 *
39 * @ingroup hiosysplugin
40 */
41 
42 class HioModule {
43 
44  public:
45 
46  /**
47  * constructor
48  */
49  HioModule(void);
50 
51 
52  /**
53  * copy constructor
54  */
55  HioModule(const HioModule& rOtherHioModule);
56 
57  /**
58  * virtual destructor
59  */
60  virtual ~HioModule(void) {};
61 
62  /**
63  * Clear all members of the HioModule
64  */
65  void Clear();
66 
67 
68  /**
69  * Set name of HioModule
70  *
71  * @param rName
72  * Name to set
73  */
74  void Name(const std::string& rName);
75 
76  /**
77  * Return name of HioModule
78  *
79  * @return
80  * Name of HioModule
81  */
82  std::string Name() const;
83 
84  /**
85  * Set index of HioModule.
86  *
87  * @param Index
88  * Index to set
89  */
90  void Index(const Idx Index);
91 
92  /**
93  * Return index of HioModule.
94  *
95  * @return
96  * Index of HioModule
97  */
98  Idx Index() const;
99 
100  /**
101  * Set Operator-Constraint of HioModule
102  *
103  * @param rOpConstr
104  * Operator-Constraint to set
105  */
106  void OpConstr(const HioConstraint& rOpConstr);
107 
108  /**
109  * Return Operator-Constraint of HioModule
110  *
111  * @return
112  * Operator-Constraint of HioModule
113  */
114  HioConstraint OpConstr() const;
115 
116  /**
117  * Set HioPlant of HioModule
118  *
119  * @param rHioPlant
120  * HioPlant to set
121  */
122  void Plant(const HioPlant& rHioPlant);
123 
124  /**
125  * Return HioPlant of HioModule
126  *
127  * @return
128  * HioPlant of HioModule
129  */
130  HioPlant Plant() const;
131 
132  /**
133  * Set HioController of HioModule
134  *
135  * @param rHioController
136  * HioController to set
137  */
138  void Controller(const HioController& rHioController);
139 
140  /**
141  * Return HioController of HioModule
142  *
143  * @return
144  * HioController of HioModule
145  */
146  HioController Controller() const;
147 
148  /**
149  * Return Children of HioModule
150  *
151  * @return
152  * Children of the HioModule
153  */
154  std::vector<HioModule*> Children() const;
155 
156  /**
157  * Set Children of HioModule
158  *
159  * @param rChildren
160  * vector of children to set
161  */
162  void Children(const std::vector<HioModule*>& rChildren);
163 
164  /**
165  * Set HioEnvironment of HioModule
166  *
167  * @param rHioEnvironment
168  * HioEnvironment to set
169  */
170  void Environment(const HioEnvironment& rHioEnvironment);
171 
172  /**
173  * Return HioEnvironment of HioModule
174  *
175  * @return
176  * HioEnvironment of HioModule
177  */
178  HioEnvironment Environment() const;
179 
180  /**
181  * Set Environment-Constraint of HioModule
182  *
183  * @param rEnvConstr
184  * Environment-Constraint to set
185  */
186  void EnvConstr(const HioConstraint& rEnvConstr);
187 
188  /**
189  * Return Environment-Constraint of HioModule
190  *
191  * @return
192  * Environment-Constraint of HioModule
193  */
194  HioConstraint EnvConstr() const;
195 
196  /**
197  * Insert HioModule to list of children
198  *
199  * @param rChild
200  * Child HioModule to insert to list of children
201  */
202  void InsChild(HioModule* rChild);
203 
204 //////////////////////////////////////////////////////////////////////////
205 // from here to 'private': M.Musunoi - design specific functions
206 
207 //### M.Musunoi ###
208  /**
209  * This is a function to set the x and y position of the HioModule.
210  *
211  * @param Xpos
212  * Position at the X-Axis of an x0y-System
213  * @param Ypos
214  * Position at the Y-Axis of an x0y-System
215  */
216  void Position(const int Xpos, const int Ypos);
217 //### M.Musunoi ###
218 
219 //### M.Musunoi ###
220  /**
221  * This is a function to set the type of the HioModule; by type we mean an array
222  * of length 5 where each position has a specific semnification:
223  *
224  * *************** Interpretation of mType[] *******
225  * ************* Capacity: mType[0] *********
226  * ************* Take from left: mType[1] *********
227  * ************* Take from right: mType[2] *********
228  * ************* Deliver to left: mType[3] *********
229  * ************* Deliver to left: mType[4] *********
230  * *************************************************
231  *
232  * @param type
233  * type of the HioModule
234  */
235  void TypeHioModule(int type[5]);
236 //### M.Musunoi ###
237 
238 
239  /**
240  * This function reads the model from the given library and
241  * sets the following private variables of the HioModule.
242  * The library must contain the following files:
243  *
244  * plantCBx.gen - IO-Plant model of the simulated work unit (to set mIOPlant);
245  * constrP_CBx.gen - Operator constraints of the IO Plant model (if the
246  * model doesn't require any operator constraints at
247  * least an empty generator must be available) (mLcConstr)
248  * constrE_CBx.gen - Environment constraints of the IO Plant model (at
249  * least an empty generator must be available) (mLeConstr)
250  *
251  * for GUI purpose:
252  * symbolic picture of the work unit in *.png format
253  *
254  * The file names must be given as described above, and the events respect the
255  * following format:
256  * "CBx_..." (e.g.: CBx_rdy, CBx_full, CBx_stby,...)
257  *
258  * @param path
259  * string path indicating to the folder of the library to load;
260  * (required format: ../CBx/)
261  *
262  * todo: for GUI load image
263  */
264  void ReadHioPlant(const std::string path);
265 
266 
267  /**
268  * This function reads the model describing the interaction of IO-Plants with
269  * the environment and sets the private variable mIOEnvironment. As a next
270  * logical step this generator must be adapted to the IO-Plants that interact
271  * with each other.
272  *
273  * @param path
274  * string path indicating to the folder of the library to load;
275  */
276  void ReadHioEnv(const std::string path);
277 
278 
279 /**
280  * This function converts a generator by renaming all events from
281  * "CBx_..." to "CBi_...";
282  *
283  * all properties of the input generator are inherited by the output generator;
284  * as a standard all events used in this plugin have the following name format:
285  * "CBx_..."
286  *
287  * @param rOldGen
288  * generator to convert
289  * @param i
290  * new parameter to replace x
291  * @param rResGen
292  * Reference to the resulting converted generator (result)
293  */
295  const Generator& rOldGen,
296  const int i,
297  Generator& rResGen);
298 
299 
300 /**
301  * AdjustHioPlant(): convenience function (derived from AdjusTimedGenerator())to
302  * allow also the conversion of HioPlants
303  *
304  * @param rOldHioPlant
305  * HioPlant to convert
306  * @param i
307  * new parameter to replace x
308  * @param rResult
309  * Reference to the resulting converted HioPlant (result)
310  */
311 void AdjustHioPlant(
312  const HioPlant& rOldHioPlant,
313  const int i,
314  HioPlant& rResult);
315 
316 
317 /**
318  * This function converts an alphabet by renaming all events from
319  * "CBx_..." to "CBi_...";
320  * as a standard all events used in this plugin have the following name format:
321  * "CBx_...";
322  * Warning: This function does not preserves the attributes of the events!
323  *
324  * @param rOldAlph
325  * Alphabet to convert
326  * @param i
327  * new parameter to replace x
328  *
329  * @param rResAlph
330  * Reference to the resulting converted alphabet (result)
331  */
332 void AdjustAlphabet(
333  const EventSet& rOldAlph,
334  const int i,
335  EventSet& rResAlph);
336 
337 
338 /**
339  * AdjustEnvironment(): In order to describe the interaction between two IO-Plants
340  * we use the IO-Environment. This function adjusts the master copy
341  * (IOEnvironmentX) to the two IO-Plants. The position of the plants to each
342  * other must be set.
343  *
344  * @param rHioEnvX
345  * the master copy generator of the environment model
346  * @param rHioModule1
347  * first HioModule
348  * @param rHioModule2
349  * second HioModule
350  * @param rResEnv
351  * Reference to the resulting environment.
352  */
354  const HioEnvironment& rHioEnvX,
355  const HioModule* rHioModule1,
356  const HioModule* rHioModule2,
357  HioEnvironment& rResEnv);
358 
359 
360 /**
361  * AdjustHioController: convenience function derived from AdjustHioEnvironment() in
362  * order to adjust an IOController to any two IO-Plants which must enforce a
363  * well-defined specification
364  *
365  * @param rHioController
366  * the input controller to convert
367  * @param HioModule1
368  * pointer to first HioModule
369  * @param HioModule2
370  * pointer to second HioModule
371  * @param rResCont
372  * Reference to resulting controller
373  */
375  const HioController& rHioController,
376  const HioModule* HioModule1,
377  const HioModule* HioModule2,
378  HioController& rResCont);
379 
380 
381 /**
382  * this function renames all relevant member of the HioModule. These are:
383  * mHioPlant, mLcConstr, mLeConstr, mHioEnvironment, mHioController, mName
384  *
385  * @param i
386  * the new Id of the HioModule
387  */
388 void RenameHioModule(const int i);
389 
390 
391  /**
392  * chooseSpec: this function searches through an appropriate folder (based on
393  * the maximal capacity resulting from the ChildList) for available
394  * specifications and allows the user to choose one of the found specifications;
395  * After the user has chosen a specification, this function sets the IO-Plant,
396  * the constraints and the alphabets of the actual HioModule.
397  * The path must have the following format: "../Spec/"
398  *
399  * Warning: The computation of the IO-Controller is not triggered by this function,
400  * it must be started separately!
401  *
402  * @param path
403  * Path to the folder containing the specifications
404  * @return
405  * list of strings with available specifications
406  */
407 std::vector<std::string> ChooseSpec(
408  const std::string path);
409 
410  /**
411  * Compute: this function prepares the data required for HioSynth() function.
412  * If all data is available, HioSynth() is called and the resulting generator
413  * is the IOController for the given specification.
414  */
415  void Compute();
416 
417 
418  /**
419  * FindController(): this function searches in the folder of a chosen
420  * specification for an already computed IO-controller which enforces this
421  * specification.
422  * Furthermore must the IO-controller only be adjusted to the IO-Modules that
423  * we need to control. (to adjust call adjustController())
424  * @return
425  * true if a IO-Controller is available
426  */
427  bool FindController();
428 
429 
430  /**
431  * Save: this function saves the computed controller in the same folder with
432  * the specification that this controller enforces
433  */
434  void SaveController();
435 
436 
437  /**
438  * MyPath(): based on the type of the HioModule, this is a convenience
439  * function to establish the local path where to Write/Read from. (This function
440  * is used up to now only by FindController() and SaveController())
441  *
442  * @return
443  * string: path to the actual IO-Module
444  */
445  std::string MyPath();
446 
447  /**********************************************
448  **********************************************
449  *
450  * functions to call properties of the HioModule
451  **********************************************
452  ***********************************************/
453 
454  /**
455  * function to call the x-Position of the HioModule
456  *
457  * @return
458  * x-Position of the HioModule
459  */
460  int Xpos() const;
461 
462  /**
463  * function to call the y-Position of the HioModule
464  *
465  * @return
466  * y-Position of the HioModule
467  */
468  int Ypos() const;
469 
470  /**
471  * function to call the Type of the HioModule
472  *
473  * @return
474  * array of length 5 describing the type of the HioModule
475  */
476  int* TypeHioModule() const;
477 
478  /**
479  * function to encode to Type of the HioModule (function has only an
480  * informational character).
481  *
482  * *************** Interpretation of mType[] *******
483  * ************* Capacity: mType[0] *********
484  * ************* Take from left: mType[1] *********
485  * ************* Take from right: mType[2] *********
486  * ************* Deliver to left: mType[3] *********
487  * ************* Deliver to left: mType[4] *********
488  * *************************************************
489  *
490  * @param type
491  * the type to be encoded
492  */
493  void EncodeType(const std::string type);
494 
495  private:
496 
497  //Name
498  std::string mName;
499 
500  //Identity
502 
503  // Operator-Constraint
505 
506  // I/O-Plant
508 
509  // IO-Controller
511 
512  // Children
513  std::vector<HioModule*> mChildren;
514 
515  // IO-Environment
517 
518  // Environment-Constraint
520 
521  /////////////////////////////////////////////////////////////////////
522  // from here to end of file: design specific functions by M.Musunoi
523  // will be outsourced to something like hiodesign.h
524 
525  // operational mode of the HioModule
526  int mType[5];
527 
528  // define the position in a x0y coordinate system; mXpos = 0 and mYpos =0 is
529  // reserved for the general IOModule CBx
530  int mXpos;
531  int mYpos;
532 
533  }; // end of HioModule class definition
534 
535 /*******************************************************************************
536  ***************************END OF IOMODULE CLASS DEFINITION********************
537  ******************************************************************************/
538 
539 /**
540  * GroupHioModules: This function groups two or more HioModules to a new HioModule. The new
541  * HioModule represents the uncontrolled behaviour of the composed HioModules.
542  *
543  * @param rChildren
544  * vector of HioModules to group
545  * @param rParentModule
546  * resulting HioModule
547  */
548 void GroupHioModules(
549  const std::vector<HioModule*>& rChildren,
550  HioModule& rParentModule);
551 
552 /**
553  * This function creates new specification given by the type ("xxxxx")
554  * Note: The core of this function is a template specification model (SpecCB12.gen).
555  * Based on this model are the specifications created, by simply adding corresponding
556  * states and transitions. Hence, for different models, this function can not be
557  * used directly, but can serve as an example.
558  *
559  * @param mType
560  * By the type we specify the desired behaviour we want to model
561  * @param rHioSpec
562  * HioPlant reference to the resulting specification (result)
563  * @param constrP
564  * Generator to the resulting operator constraint for the specification
565  * @param constrE
566  * Generator to the resulting environment constraint for the specification
567  */
568 void CreateSpec(int mType[5], HioPlant& rHioSpec, Generator& constrP, Generator& constrE);
569 
570 /** This function creates constraints which describe the condition of completeness
571  * and Yp-liveness of a Specification. The implementation follows the same algorithm
572  * as the CreateSpec() function, and has the same limitation: it is only for use
573  * with a specific model
574  *
575  * @param mType
576  * By the type we specify type of the specification to build constraint for
577  * @param constrP
578  * Generator to the resulting operator constraint for the specification
579  * @param constrE
580  * Generator to the resulting environment constraint for the specification
581  */
582 void CreateConstraint(int mType[5], Generator& constrP, Generator& constrE);
583 
584 
585 } // end namespace faudes
586 
587 #endif

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen