hio_module.h

Go 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