hio_module.hGo to the documentation of this file.00001 /** @file hio_module.h Class describing the I/O based hierarchy */ 00002 00003 /* Hierarchical IO Systems Plug-In for FAU Discrete Event Systems Library (libfaudes) 00004 00005 Copyright (C) 2006 Sebastian Perk 00006 Copyright (C) 2006 Thomas Moor 00007 Copyright (C) 2006 Klaus Schmidt 00008 00009 */ 00010 00011 #ifndef FAUDES_HIO_MODULE_H 00012 #define FAUDES_HIO_MODULE_H 00013 00014 #include "hio_helper.h" 00015 #include "hio_functions.h" 00016 #include <list> 00017 #include <cmath> 00018 00019 namespace faudes { 00020 00021 /** 00022 * Recurring structure in hierarchies designed according to the I/O based DES framework. 00023 * The HioModule class is a composite pattern providing access to the components of a 00024 * I/O-controller synthesis problem for a composite I/O-plant: 00025 * 00026 * - Operator-constraint: describes liveness properties of I/O-plant, together with 00027 * environment-constraint 00028 * - Plant: abstraction and at the same time specification of the external 00029 * closed-loop behaviour of the HioModule. 00030 * - Controller enforcing the desired behaviour 00031 * - children-vector of (pointers to) subordinate HioModules 00032 * - Environment 00033 * - Environment-constraint: describes liveness properties of I/O-plant, together with 00034 * operator-constraint 00035 * 00036 * The plants of the subordinate HioModules and the environment form the 00037 * uncontrolled behaviour of the HioModule. 00038 * 00039 * @ingroup hiosysplugin 00040 */ 00041 00042 class HioModule { 00043 00044 public: 00045 00046 /** 00047 * constructor 00048 */ 00049 HioModule(void); 00050 00051 00052 /** 00053 * copy constructor 00054 */ 00055 HioModule(const HioModule& rOtherHioModule); 00056 00057 /** 00058 * virtual destructor 00059 */ 00060 virtual ~HioModule(void) {}; 00061 00062 /** 00063 * Clear all members of the HioModule 00064 */ 00065 void Clear(); 00066 00067 00068 /** 00069 * Set name of HioModule 00070 * 00071 * @param rName 00072 * Name to set 00073 */ 00074 void Name(const std::string& rName); 00075 00076 /** 00077 * Return name of HioModule 00078 * 00079 * @return 00080 * Name of HioModule 00081 */ 00082 std::string Name() const; 00083 00084 /** 00085 * Set index of HioModule. 00086 * 00087 * @param Index 00088 * Index to set 00089 */ 00090 void Index(const Idx Index); 00091 00092 /** 00093 * Return index of HioModule. 00094 * 00095 * @return 00096 * Index of HioModule 00097 */ 00098 Idx Index() const; 00099 00100 /** 00101 * Set Operator-Constraint of HioModule 00102 * 00103 * @param rOpConstr 00104 * Operator-Constraint to set 00105 */ 00106 void OpConstr(const HioConstraint& rOpConstr); 00107 00108 /** 00109 * Return Operator-Constraint of HioModule 00110 * 00111 * @return 00112 * Operator-Constraint of HioModule 00113 */ 00114 HioConstraint OpConstr() const; 00115 00116 /** 00117 * Set HioPlant of HioModule 00118 * 00119 * @param rHioPlant 00120 * HioPlant to set 00121 */ 00122 void Plant(const HioPlant& rHioPlant); 00123 00124 /** 00125 * Return HioPlant of HioModule 00126 * 00127 * @return 00128 * HioPlant of HioModule 00129 */ 00130 HioPlant Plant() const; 00131 00132 /** 00133 * Set HioController of HioModule 00134 * 00135 * @param rHioController 00136 * HioController to set 00137 */ 00138 void Controller(const HioController& rHioController); 00139 00140 /** 00141 * Return HioController of HioModule 00142 * 00143 * @return 00144 * HioController of HioModule 00145 */ 00146 HioController Controller() const; 00147 00148 /** 00149 * Return Children of HioModule 00150 * 00151 * @return 00152 * Children of the HioModule 00153 */ 00154 std::vector<HioModule*> Children() const; 00155 00156 /** 00157 * Set Children of HioModule 00158 * 00159 * @param rChildren 00160 * vector of children to set 00161 */ 00162 void Children(const std::vector<HioModule*>& rChildren); 00163 00164 /** 00165 * Set HioEnvironment of HioModule 00166 * 00167 * @param rHioEnvironment 00168 * HioEnvironment to set 00169 */ 00170 void Environment(const HioEnvironment& rHioEnvironment); 00171 00172 /** 00173 * Return HioEnvironment of HioModule 00174 * 00175 * @return 00176 * HioEnvironment of HioModule 00177 */ 00178 HioEnvironment Environment() const; 00179 00180 /** 00181 * Set Environment-Constraint of HioModule 00182 * 00183 * @param rEnvConstr 00184 * Environment-Constraint to set 00185 */ 00186 void EnvConstr(const HioConstraint& rEnvConstr); 00187 00188 /** 00189 * Return Environment-Constraint of HioModule 00190 * 00191 * @return 00192 * Environment-Constraint of HioModule 00193 */ 00194 HioConstraint EnvConstr() const; 00195 00196 /** 00197 * Insert HioModule to list of children 00198 * 00199 * @param rChild 00200 * Child HioModule to insert to list of children 00201 */ 00202 void InsChild(HioModule* rChild); 00203 00204 ////////////////////////////////////////////////////////////////////////// 00205 // from here to 'private': M.Musunoi - design specific functions 00206 00207 //### M.Musunoi ### 00208 /** 00209 * This is a function to set the x and y position of the HioModule. 00210 * 00211 * @param Xpos 00212 * Position at the X-Axis of an x0y-System 00213 * @param Ypos 00214 * Position at the Y-Axis of an x0y-System 00215 */ 00216 void Position(const int Xpos, const int Ypos); 00217 //### M.Musunoi ### 00218 00219 //### M.Musunoi ### 00220 /** 00221 * This is a function to set the type of the HioModule; by type we mean an array 00222 * of length 5 where each position has a specific semnification: 00223 * 00224 * *************** Interpretation of mType[] ******* 00225 * ************* Capacity: mType[0] ********* 00226 * ************* Take from left: mType[1] ********* 00227 * ************* Take from right: mType[2] ********* 00228 * ************* Deliver to left: mType[3] ********* 00229 * ************* Deliver to left: mType[4] ********* 00230 * ************************************************* 00231 * 00232 * @param type 00233 * type of the HioModule 00234 */ 00235 void TypeHioModule(int type[5]); 00236 //### M.Musunoi ### 00237 00238 00239 /** 00240 * This function reads the model from the given library and 00241 * sets the following private variables of the HioModule. 00242 * The library must contain the following files: 00243 * 00244 * plantCBx.gen - IO-Plant model of the simulated work unit (to set mIOPlant); 00245 * constrP_CBx.gen - Operator constraints of the IO Plant model (if the 00246 * model doesn't require any operator constraints at 00247 * least an empty generator must be available) (mLcConstr) 00248 * constrE_CBx.gen - Environment constraints of the IO Plant model (at 00249 * least an empty generator must be available) (mLeConstr) 00250 * 00251 * for GUI purpose: 00252 * symbolic picture of the work unit in *.png format 00253 * 00254 * The file names must be given as described above, and the events respect the 00255 * following format: 00256 * "CBx_..." (e.g.: CBx_rdy, CBx_full, CBx_stby,...) 00257 * 00258 * @param path 00259 * string path indicating to the folder of the library to load; 00260 * (required format: ../CBx/) 00261 * 00262 * todo: for GUI load image 00263 */ 00264 void ReadHioPlant(const std::string path); 00265 00266 00267 /** 00268 * This function reads the model describing the interaction of IO-Plants with 00269 * the environment and sets the private variable mIOEnvironment. As a next 00270 * logical step this generator must be adapted to the IO-Plants that interact 00271 * with each other. 00272 * 00273 * @param path 00274 * string path indicating to the folder of the library to load; 00275 */ 00276 void ReadHioEnv(const std::string path); 00277 00278 00279 /** 00280 * This function converts a generator by renaming all events from 00281 * "CBx_..." to "CBi_..."; 00282 * 00283 * all properties of the input generator are inherited by the output generator; 00284 * as a standard all events used in this plugin have the following name format: 00285 * "CBx_..." 00286 * 00287 * @param rOldGen 00288 * generator to convert 00289 * @param i 00290 * new parameter to replace x 00291 * @param rResGen 00292 * Reference to the resulting converted generator (result) 00293 */ 00294 void AdjusTimedGenerator( 00295 const Generator& rOldGen, 00296 const int i, 00297 Generator& rResGen); 00298 00299 00300 /** 00301 * AdjustHioPlant(): convenience function (derived from AdjusTimedGenerator())to 00302 * allow also the conversion of HioPlants 00303 * 00304 * @param rOldHioPlant 00305 * HioPlant to convert 00306 * @param i 00307 * new parameter to replace x 00308 * @param rResult 00309 * Reference to the resulting converted HioPlant (result) 00310 */ 00311 void AdjustHioPlant( 00312 const HioPlant& rOldHioPlant, 00313 const int i, 00314 HioPlant& rResult); 00315 00316 00317 /** 00318 * This function converts an alphabet by renaming all events from 00319 * "CBx_..." to "CBi_..."; 00320 * as a standard all events used in this plugin have the following name format: 00321 * "CBx_..."; 00322 * Warning: This function does not preserves the attributes of the events! 00323 * 00324 * @param rOldAlph 00325 * Alphabet to convert 00326 * @param i 00327 * new parameter to replace x 00328 * 00329 * @param rResAlph 00330 * Reference to the resulting converted alphabet (result) 00331 */ 00332 void AdjustAlphabet( 00333 const EventSet& rOldAlph, 00334 const int i, 00335 EventSet& rResAlph); 00336 00337 00338 /** 00339 * AdjustEnvironment(): In order to describe the interaction between two IO-Plants 00340 * we use the IO-Environment. This function adjusts the master copy 00341 * (IOEnvironmentX) to the two IO-Plants. The position of the plants to each 00342 * other must be set. 00343 * 00344 * @param rHioEnvX 00345 * the master copy generator of the environment model 00346 * @param rHioModule1 00347 * first HioModule 00348 * @param rHioModule2 00349 * second HioModule 00350 * @param rResEnv 00351 * Reference to the resulting environment. 00352 */ 00353 void AdjustHioEnvironment( 00354 const HioEnvironment& rHioEnvX, 00355 const HioModule* rHioModule1, 00356 const HioModule* rHioModule2, 00357 HioEnvironment& rResEnv); 00358 00359 00360 /** 00361 * AdjustHioController: convenience function derived from AdjustHioEnvironment() in 00362 * order to adjust an IOController to any two IO-Plants which must enforce a 00363 * well-defined specification 00364 * 00365 * @param rHioController 00366 * the input controller to convert 00367 * @param HioModule1 00368 * pointer to first HioModule 00369 * @param HioModule2 00370 * pointer to second HioModule 00371 * @param rResCont 00372 * Reference to resulting controller 00373 */ 00374 void AdjustHioController( 00375 const HioController& rHioController, 00376 const HioModule* HioModule1, 00377 const HioModule* HioModule2, 00378 HioController& rResCont); 00379 00380 00381 /** 00382 * this function renames all relevant member of the HioModule. These are: 00383 * mHioPlant, mLcConstr, mLeConstr, mHioEnvironment, mHioController, mName 00384 * 00385 * @param i 00386 * the new Id of the HioModule 00387 */ 00388 void RenameHioModule(const int i); 00389 00390 00391 /** 00392 * chooseSpec: this function searches through an appropriate folder (based on 00393 * the maximal capacity resulting from the ChildList) for available 00394 * specifications and allows the user to choose one of the found specifications; 00395 * After the user has chosen a specification, this function sets the IO-Plant, 00396 * the constraints and the alphabets of the actual HioModule. 00397 * The path must have the following format: "../Spec/" 00398 * 00399 * Warning: The computation of the IO-Controller is not triggered by this function, 00400 * it must be started separately! 00401 * 00402 * @param path 00403 * Path to the folder containing the specifications 00404 * @return 00405 * list of strings with available specifications 00406 */ 00407 std::vector<std::string> ChooseSpec( 00408 const std::string path); 00409 00410 /** 00411 * Compute: this function prepares the data required for HioSynth() function. 00412 * If all data is available, HioSynth() is called and the resulting generator 00413 * is the IOController for the given specification. 00414 */ 00415 void Compute(); 00416 00417 00418 /** 00419 * FindController(): this function searches in the folder of a chosen 00420 * specification for an already computed IO-controller which enforces this 00421 * specification. 00422 * Furthermore must the IO-controller only be adjusted to the IO-Modules that 00423 * we need to control. (to adjust call adjustController()) 00424 * @return 00425 * true if a IO-Controller is available 00426 */ 00427 bool FindController(); 00428 00429 00430 /** 00431 * Save: this function saves the computed controller in the same folder with 00432 * the specification that this controller enforces 00433 */ 00434 void SaveController(); 00435 00436 00437 /** 00438 * MyPath(): based on the type of the HioModule, this is a convenience 00439 * function to establish the local path where to Write/Read from. (This function 00440 * is used up to now only by FindController() and SaveController()) 00441 * 00442 * @return 00443 * string: path to the actual IO-Module 00444 */ 00445 std::string MyPath(); 00446 00447 /********************************************** 00448 ********************************************** 00449 * 00450 * functions to call properties of the HioModule 00451 ********************************************** 00452 ***********************************************/ 00453 00454 /** 00455 * function to call the x-Position of the HioModule 00456 * 00457 * @return 00458 * x-Position of the HioModule 00459 */ 00460 int Xpos() const; 00461 00462 /** 00463 * function to call the y-Position of the HioModule 00464 * 00465 * @return 00466 * y-Position of the HioModule 00467 */ 00468 int Ypos() const; 00469 00470 /** 00471 * function to call the Type of the HioModule 00472 * 00473 * @return 00474 * array of length 5 describing the type of the HioModule 00475 */ 00476 int* TypeHioModule() const; 00477 00478 /** 00479 * function to encode to Type of the HioModule (function has only an 00480 * informational character). 00481 * 00482 * *************** Interpretation of mType[] ******* 00483 * ************* Capacity: mType[0] ********* 00484 * ************* Take from left: mType[1] ********* 00485 * ************* Take from right: mType[2] ********* 00486 * ************* Deliver to left: mType[3] ********* 00487 * ************* Deliver to left: mType[4] ********* 00488 * ************************************************* 00489 * 00490 * @param type 00491 * the type to be encoded 00492 */ 00493 void EncodeType(const std::string type); 00494 00495 private: 00496 00497 //Name 00498 std::string mName; 00499 00500 //Identity 00501 Idx mIndex; 00502 00503 // Operator-Constraint 00504 HioConstraint mOpConstr; 00505 00506 // I/O-Plant 00507 HioPlant mPlant; 00508 00509 // IO-Controller 00510 HioController mController; 00511 00512 // Children 00513 std::vector<HioModule*> mChildren; 00514 00515 // IO-Environment 00516 HioEnvironment mEnvironment; 00517 00518 // Environment-Constraint 00519 HioConstraint mEnvConstr; 00520 00521 ///////////////////////////////////////////////////////////////////// 00522 // from here to end of file: design specific functions by M.Musunoi 00523 // will be outsourced to something like hiodesign.h 00524 00525 // operational mode of the HioModule 00526 int mType[5]; 00527 00528 // define the position in a x0y coordinate system; mXpos = 0 and mYpos =0 is 00529 // reserved for the general IOModule CBx 00530 int mXpos; 00531 int mYpos; 00532 00533 }; // end of HioModule class definition 00534 00535 /******************************************************************************* 00536 ***************************END OF IOMODULE CLASS DEFINITION******************** 00537 ******************************************************************************/ 00538 00539 /** 00540 * GroupHioModules: This function groups two or more HioModules to a new HioModule. The new 00541 * HioModule represents the uncontrolled behaviour of the composed HioModules. 00542 * 00543 * @param rChildren 00544 * vector of HioModules to group 00545 * @param rParentModule 00546 * resulting HioModule 00547 */ 00548 void GroupHioModules( 00549 const std::vector<HioModule*>& rChildren, 00550 HioModule& rParentModule); 00551 00552 /** 00553 * This function creates new specification given by the type ("xxxxx") 00554 * Note: The core of this function is a template specification model (SpecCB12.gen). 00555 * Based on this model are the specifications created, by simply adding corresponding 00556 * states and transitions. Hence, for different models, this function can not be 00557 * used directly, but can serve as an example. 00558 * 00559 * @param mType 00560 * By the type we specify the desired behaviour we want to model 00561 * @param rHioSpec 00562 * HioPlant reference to the resulting specification (result) 00563 * @param constrP 00564 * Generator to the resulting operator constraint for the specification 00565 * @param constrE 00566 * Generator to the resulting environment constraint for the specification 00567 */ 00568 void CreateSpec(int mType[5], HioPlant& rHioSpec, Generator& constrP, Generator& constrE); 00569 00570 /** This function creates constraints which describe the condition of completeness 00571 * and Yp-liveness of a Specification. The implementation follows the same algorithm 00572 * as the CreateSpec() function, and has the same limitation: it is only for use 00573 * with a specific model 00574 * 00575 * @param mType 00576 * By the type we specify type of the specification to build constraint for 00577 * @param constrP 00578 * Generator to the resulting operator constraint for the specification 00579 * @param constrE 00580 * Generator to the resulting environment constraint for the specification 00581 */ 00582 void CreateConstraint(int mType[5], Generator& constrP, Generator& constrE); 00583 00584 00585 } // end namespace faudes 00586 00587 #endif libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen |