sp_simconditionset.h

Go to the documentation of this file.
00001 /** @file sp_simconditionset.h  Set of named simulation conditions */
00002 
00003 /*
00004    Copyright (C) 2008  Thomas Moor
00005    Exclusive copyright is granted to Klaus Schmidt
00006 */
00007 
00008 
00009 #include "corefaudes.h"
00010 #include "sp_densityfnct.h"
00011 
00012 
00013 #ifndef FAUDES_SP_SIMCONDITIONSET_H
00014 #define FAUDES_SP_SIMCONDITIONSET_H
00015 
00016 namespace faudes {
00017 
00018 /** 
00019 
00020 @defgroup SimConditionAttributes Simulation Condition Attributes 
00021 
00022 @ingroup SimulatorPlugin 
00023 
00024 Attributes to define simulation conditions used for statistic analysis
00025 of simulation runs.
00026 
00027 @copydoc faudes::AttributeSimCondition
00028 
00029 @{ 
00030 
00031 */
00032 
00033 /**  
00034  * Defining data of event based simulation condition
00035  *
00036  * An event based condition has a set of start events and a set of
00037  * stop events. It becomes satisfied when a start event occurs and it 
00038  * becomes unsatisfied when a stop event occurs. Thus, when start or stop
00039  * events fail to alternate, the first event of the respective type is relevant.
00040  *
00041  */
00042 class SimEventCondition {
00043  public:
00044   EventSet mStart;
00045   EventSet mStop;
00046   bool operator==(const SimEventCondition rOther) const { 
00047     return mStart==rOther.mStart && mStop==rOther.mStop;}; 
00048 };
00049 
00050 /**  
00051  * Defining data of state based simulation condition
00052  *
00053  * A state based condition has a set of states per generator an is satisfied
00054  * while the components of the current discrete state vector are within the
00055  * respective set. A flag indicates whether each or some component 
00056  * must comply with the state set to satisfy the condition.
00057  * 
00058  * Note: Since state indices are local to generators, a SimStateCondition 
00059  * is only meaningful in the context of a particular ParallelExecutor. 
00060  *
00061  */
00062 
00063 // state based condition
00064 class  SimStateCondition {
00065 public:
00066   bool mAllFlag;
00067   std::vector<StateSet> mStateSets;
00068   bool operator==(const SimStateCondition rOther) const { 
00069     return mAllFlag==rOther.mAllFlag && mStateSets==rOther.mStateSets;}; 
00070 };
00071 
00072 
00073 /**
00074  * Attribute for a simulation condition
00075  *
00076  * In order to extract statistical data from a simulation by a LoggingExecutor
00077  * or some derived class, so called simulation conditions
00078  * are defined. At any instance of time, a condition is satisfied or
00079  * dissatisfied. Statistical data can then be requested regarding 
00080  * the period and duration of each condition. Currently, two
00081  * types of conditions are available:
00082  *
00083  * - SimStateCondition addresses conditions of the current state
00084  * - SimEventCondition addresses the external event sequence.
00085  *
00086  * A Condition may be flagged as a break condition to halt simulation
00087  * when satisfied. A condition may be enabled for tracking or not.
00088  *
00089  * The class AttributeSimCondition summarizes all data to represent
00090  * faudes simulation conditions. It also holds some state of the condition
00091  * wrt execution and provides an interface for sampling. The latter 
00092  * may be seperated to a different class in a future revision. The class
00093  * AttributeSimCondition does, however, not implement any test whether
00094  * or not a condition is satisfied. This is done by the LoggingExecutor.
00095  *
00096  * As a faudes attribute, conditions can be referenced by 
00097  * names via the std faudes container TaNameSet. For token io, a
00098  * ParallelExecutor should be provided as context to access symbolic
00099  * state names. The file format of a set of
00100  * events equipped with condition attributes is illustrated by the below example
00101  * to monitor some performance aspects of one simple machine:
00102  * 
00103  * @code
00104  *
00105  * <Conditions>
00106  *
00107  * % monitor when the machine is idle
00108  * "IdleCond"      
00109  * <StateCondition>
00110  * <StateSet> "idle" </StateSet>
00111  * </StateCondition>
00112  *
00113  * % halt simulation  when the machine is down
00114  * % however, the condition is disabled
00115  * "DownCond"      
00116  * +Break+     
00117  * +Disabled+     
00118  * <StateCondition>
00119  * <StateSet> "down" </StateSet>
00120  * </StateCondition>
00121  *
00122  * % monitor how long the prozessing one work piece takes
00123  * "OperationCond"     
00124  * <EventCondition>
00125  * <StartEvents>  "alpha" </StartEvents>
00126  * <StopEvents>   "beta"  </StopEvents>
00127  * </EventCondition>
00128  *
00129  * </Conditions>
00130  *
00131  * @endcode
00132  */
00133 
00134 class AttributeSimCondition : public AttributeFlags {
00135 
00136 FAUDES_TYPE_DECLARATION(Void,AttributeSimCondition,AttributeFlags)
00137 
00138   public:
00139 
00140   /** Convenience typedef */
00141   typedef std::vector<StateSet>::iterator Iterator;
00142   typedef std::vector<StateSet>::const_iterator CIterator;
00143 
00144   /** 
00145    * Default constructor. Constructs a AttributeSimCondition of 
00146    * with no type ie neither state condition nor event condition.
00147    */
00148   AttributeSimCondition(void);
00149 
00150   /** 
00151    * Copy constructor.
00152    * with no type ie neither state condition nor event condition.
00153    */
00154   AttributeSimCondition(const AttributeSimCondition& rOther);
00155 
00156   /** 
00157    * Test for default value 
00158    * 
00159    * @return
00160    *   True, if this attribute has its default value
00161    */
00162   virtual bool IsDefault(void) const {
00163     return !mEventCondition && !mStateCondition && (mFlags==mDefSCFlags); };
00164 
00165 
00166   /** 
00167    * Test for state condition.
00168    *
00169    * @return
00170    *   True, if this attribute defines a state condition
00171    */
00172   bool IsStateCondition(void) const {return mStateCondition; };
00173 
00174   /** 
00175    * Test for event condition.
00176    *
00177    * @return
00178    *   True, if this attribute defines an event condition
00179    */
00180   bool IsEventCondition(void) const {return mEventCondition; };
00181 
00182   /** 
00183    * Test for break condition.
00184    *
00185    * @return
00186    *   True, if this condition halts simulation.
00187    */
00188   bool Breakpoint(void) const {return ((mFlags & mBreakpointFlag) != 0); };
00189 
00190   /** 
00191    * Test whether condition is enabled.
00192    *
00193    * @return
00194    *   True, if this condition is monitored during simulation.
00195    */
00196   bool Enabled(void) const { return ((mFlags & mEnabledFlag) != 0); };
00197 
00198   /** 
00199    * Set state condition attribute. Define this attribute to
00200    * represent the specified state condition.
00201    *
00202    * @param rStateConditionAttribute
00203    *     Define state condition
00204    */
00205   void StateCondition(const SimStateCondition&  rStateConditionAttribute) 
00206     {mStateConditionAttribute=rStateConditionAttribute; mStateCondition=true; mEventCondition=false;
00207     for(Idx i=0; i<mStateConditionAttribute.mStateSets.size(); i++) 
00208       mStateConditionAttribute.mStateSets.at(i).Name("StateSet");
00209   };
00210 
00211   /** 
00212    * Set event condition attribute. Define this attribute to
00213    * represent the specified event condition.
00214    *
00215    * @param rEventConditionAttribute
00216    *     Define event condition
00217    */
00218   void EventCondition(const SimEventCondition&  rEventConditionAttribute) 
00219     {mEventConditionAttribute=rEventConditionAttribute; mEventCondition=true; mStateCondition=false;};
00220 
00221   /** 
00222    * Set break flag.
00223    * 
00224    * @param on
00225    *   True, to indicate that this condition halts simulation.
00226    */
00227   void Breakpoint(bool on) { if(on) mFlags |= mBreakpointFlag; else mFlags &= ~mBreakpointFlag; };
00228 
00229   /** 
00230    * Set enabled flag.
00231    * 
00232    * @param on
00233    *   True, to indicate that this condition is to be monitored during simulation.
00234    */
00235   void Enabled(bool on) { if(on) mFlags |= mEnabledFlag; else mFlags &= ~mEnabledFlag; };
00236 
00237   /**  
00238    * Get event condition. Note that the attribute can only return
00239    * meaningful data if it actually is an event condition.  
00240    *
00241    *  @return
00242    *    Defining data of this attribute's event condition.
00243    *
00244    */
00245   const SimEventCondition& EventCondition(void) const {return mEventConditionAttribute; };
00246 
00247   /**  
00248    * Get state condition. Note that the attribute can only return
00249    * meaningful data if it actually is an state condition.  
00250    *
00251    *  @return
00252    *    Defining data of this attribute's state condition.
00253    *
00254    */
00255   const SimStateCondition& StateCondition(void) const {return mStateConditionAttribute; };
00256 
00257   /**
00258    *  Reset conditions execution state. The execution state of a condition
00259    *  consists of all data accumulated during simulation eg statistical data
00260    *  and whether or not the condition is currently satisfied. The execution state
00261    *  resides in the attribute for pragmatic reasons only.
00262    */
00263   void Reset(void) 
00264   { mSatisfied=false; mActivationTime=-1; mSamplesPeriod.Clear(); mSamplesDuration.Clear(); };
00265 
00266   /** 
00267    * Test whether the condition is currently satisfied. This is part
00268    * of the condition execution state. 
00269    *
00270    * @return
00271    *   True, if the conditions is considered satisfied
00272    */
00273   bool Satisfied(void) const { return mSatisfied; };
00274 
00275   /** 
00276    * Set the condition to be satisfied. This is part
00277    * of the condition execution state. Since it is the executor
00278    * that determines whether a condition is satisfied, and since
00279    * the condition state resides in the attribute, the executor
00280    * is meant to notify state changes.
00281    *
00282    * @param on
00283    *   True, if the conditions is considered satisfied
00284    * @param now
00285    *   Time at which the state change occures
00286    */
00287   void Satisfied(bool on, tpTime::Type now);
00288    
00289   /** 
00290    * Sampled period, at which this condition becomes satisfied. 
00291    */
00292   SampledDensityFunction mSamplesPeriod;
00293 
00294   /** 
00295    * Sampled durations, for which this condition remains satisfied. 
00296    */
00297   SampledDensityFunction mSamplesDuration;
00298 
00299   // flag masks for the three properties
00300   const static fType mEnabledFlag      =0x01;
00301   const static fType mBreakpointFlag   =0x02;
00302 
00303 protected:
00304  
00305   /** Indicate precense of a event condition */
00306   bool mEventCondition;
00307 
00308   /** Indicate precense of a state condition */
00309   bool mStateCondition;
00310 
00311   /** Event based condition data */
00312   SimEventCondition mEventConditionAttribute;
00313 
00314   /** State based condition data */
00315   SimStateCondition mStateConditionAttribute;
00316 
00317   /** Condotion state: recorded as satisfied */
00318   bool mSatisfied;
00319 
00320   /** Condition state: when last satisfied became true */
00321   tpTime::Type mActivationTime;
00322    
00323 
00324  protected:
00325 
00326   /**
00327    * Assignment method. 
00328    *
00329    * @param rSrcAttr
00330    *    Source to assign from
00331    */
00332   void DoAssign(const AttributeSimCondition& rSrcAttr);
00333 
00334   /**
00335    * Equality method. 
00336    *
00337    * @param rAttr
00338    *    Source to compare with
00339    */
00340   bool DoEqual(const AttributeSimCondition& rAttr) const;
00341 
00342   /**
00343    * Reads the attribute from TokenReader, see AttributeVoid for public wrappers.
00344    * 
00345    * If the current token indicates a condition section, the method reads the  
00346    * condition data from that section. Else it does nothing. Exceptions may only be thrown
00347    * on invalid data within the condition section. The label argiment is ignored, we 
00348    * use hardcoded labled "EventCondition" and "StateCondition" to figure the type of 
00349    * condition. When a ParallelExecutor is provided as context, it is used to interpret
00350    * symbolc state names of a state condition.
00351    *
00352    * @param rTr
00353    *   TokenReader to read from
00354    * @param rLabel
00355    *   Section to read
00356    * @param pContext
00357    *   Read context to provide contextual information
00358    *
00359    * @exception Exception
00360    *   - IO error (id 1)
00361    */
00362   virtual void DoRead(TokenReader& rTr, const std::string& rLabel="", const Type* pContext=0);
00363  
00364   /**
00365    * Writes the attribute to TokenWriter, see AttributeVoid for public wrappers.
00366    *
00367    * Writes a condition section to include data on state- or event-condition. The label argument
00368    * is ignored, we use hardcoded keywords "EventCondition" and StateCondition". When a 
00369    * ParallelExecutor is provided as context, it state conditions are written with 
00370    * symbolic state names.
00371    *
00372    * @param rTw
00373    *   TokenWriter to write to
00374    * @param rLabel
00375    *   Section to write
00376    * @param pContext
00377    *   Read context to provide contextual information
00378    *
00379    * @exception Exception
00380    *   - IO error (id 2)
00381    */
00382   virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00383 
00384 private:
00385 
00386   /** Overall default value */
00387   const static fType mDefSCFlags  =0x01;
00388 
00389   /** All flags used by CFlags */
00390   const static fType mAllSCFlags  =0x03;
00391 
00392 
00393 
00394 }; // class AttributeSimCondition
00395 
00396 
00397 /**
00398  * Set of simulation named conditions. 
00399  *
00400  * Note: we currently share a symboltabel with the global
00401  * event set. This will definitely change in a future revision.
00402  */
00403 
00404 class SimConditionSet : public TaNameSet<AttributeSimCondition> {
00405 
00406 FAUDES_TYPE_DECLARATION(Void,SimConditionSet,TaNameSet<AttributeSimCondition>)
00407 
00408  public:
00409 
00410   /** Default constructor */
00411   SimConditionSet(void);
00412 
00413   /** Copy constructor */
00414   SimConditionSet(const SimConditionSet& rOtherSet);
00415 
00416   /**  Virtual destructor */
00417   virtual ~SimConditionSet(void) {};
00418 
00419   /** Test condition for enabled */
00420   bool Enabled(Idx cond) const { return Attribute(cond).Enabled(); };
00421 
00422   /** Set condition enabled */
00423   void Enabled(Idx cond, bool on) { Attributep(cond)->Enabled(on); };
00424 
00425   /** Get set of enabled conditions */
00426   SimConditionSet EnabledConditions(void);
00427 
00428   /** Reset all condition states */
00429   void Reset(void);
00430 
00431 protected:
00432 
00433  /**
00434   * Assign from other condition set. 
00435   *
00436   * @param rSourceSet
00437   *   Destination to copy from
00438   * @return
00439   *   ref to this set
00440   */
00441  virtual void DoAssign(const SimConditionSet& rSourceSet) {
00442    TaNameSet<AttributeSimCondition>::DoAssign(rSourceSet); };
00443 
00444 
00445  
00446 
00447 };
00448 
00449 
00450 
00451 /** @} doxygen group */
00452 
00453 } // namespace
00454 
00455 #endif

libFAUDES 2.23h --- 2014.04.03 --- c++ api documentaion by doxygen