sp_simeventset.h

Go to the documentation of this file.
00001 /** @file sp_simeventset.h  Eventsets with execution data for simulation */
00002 
00003 /*
00004    Copyright (C) 2008  Thomas Moor
00005    Exclusive copyright is granted to Klaus Schmidt
00006 */
00007 
00008 
00009 #ifndef FAUDES_SP_SIMEVENTSET_H
00010 #define FAUDES_SP_SIMEVENTSET_H
00011 
00012 #include "corefaudes.h"
00013 #include "tp_include.h"
00014 
00015 namespace faudes {
00016 
00017 
00018 /** 
00019 
00020 @defgroup SimEventAttributes Simulation Event Attributes 
00021 
00022 @ingroup SimulatorPlugin 
00023 
00024 Attributes to define stochastic and priority properties.
00025 
00026 @copydoc faudes::SimEventAttribute
00027 
00028 @{ 
00029 
00030 
00031 */
00032 
00033 
00034 /**  
00035  * Defining data to prioritise events.
00036  *
00037  * There are both prefer and avoid priorities. See ProposingExecutor for details.
00038  * - Positive priority: preferred execution of event, larger number wins
00039  * - Negative priority: avoid execution of event, smaller number wins
00040  *
00041  */
00042 class SimPriorityEventAttribute {
00043   public:
00044   long int mPriority;
00045   bool operator==(const SimPriorityEventAttribute& rOther) const {
00046     return mPriority==rOther.mPriority;}
00047 };
00048 
00049 /**  
00050  * Defining data of stochastic behaviour.
00051  *
00052  * The occurence of events with stochastic behaviour is scheduled by sampling a random variable.
00053  * While the attribute class only holds the defining data,  actual semantics 
00054  * are implemented in the ProposingExecutor.
00055  *
00056  * The type indicates the mechanism for sampling the random variable and for scheduling the event.
00057  * - Extern: the random variable models an external stochastic process.
00058  * - Trigger:  the random variable is used to narrow down the effective guard interval to a
00059  *           point. 
00060  * - Delay:  the random variable models a delay relative to the time while the event is
00061  *           enabled. 
00062  *
00063  * The propability density function may be one of
00064  * - Exponential
00065  * - Uniform
00066  * - Gauss
00067  * - Vector (arbitrary discrete density, not implemented)
00068  *
00069  */
00070 class  SimStochasticEventAttribute {
00071   public:
00072 
00073   /** When to re-evaluate the random variable */
00074   typedef enum {Extern, Trigger, Delay} Type;  
00075   Type mType;             
00076 
00077   /** Convert type to string */
00078   std::string static TStr(Type type) { 
00079    if(type == Extern) return "extern"; 
00080    if(type == Trigger) return "trigger"; 
00081    if(type == Delay) return "delay"; 
00082     return "unknown"; 
00083   };
00084 
00085   /** Pdf to use when evaluating the random variable */
00086   typedef enum {Exponential,  Uniform, Gauss, Vector} Pdf;  
00087   Pdf mPdf;              
00088 
00089   /** Pdf parameters */
00090   std::vector<double> mParameter; 
00091 
00092   /** Equality operator */
00093   bool operator==(const SimStochasticEventAttribute& rOther) const {
00094     return (mType==rOther.mType) && (mPdf==rOther.mPdf) && (mParameter==rOther.mParameter);}
00095 
00096 };
00097 
00098 
00099 
00100 
00101 /**
00102  * Attribute for an event in the context of simulation.
00103  *
00104  * When simulating one or more generators, at each instance of time 
00105  * there will be one or more transitions enabled. In order resolve this non-determinism
00106  * in a defined way, each event may be equipped with either one of the following 
00107  * properties. 
00108  *
00109  * - a SimPriorityEventAttribute to prioritise events
00110  * - a SimStochasticEventAttribute to determine timing by random variables
00111  * 
00112  *
00113  * Note that the SimEventAttribute just holds the data to define the properties, 
00114  * a semantic implementation is in faudes::ProposingExecutor. The current implementation
00115  * also stores simulation state data (ie evaluations of random variables), but
00116  * this is likely to change in a future revision.
00117  *
00118  * As a faudes attribute, SimEventAttribute provides token io and is prepared 
00119  * for the use in the context of a faudes container. The file format of a set of
00120  * events equipped with simulation attributes is illustrated by the below example
00121  * for the simulation of a simple machine:
00122  * 
00123  * @code
00124  *
00125  * <SimEvents>
00126  *
00127  * % machine start: prioritised event with priority 100
00128  * "alpha"    
00129  * <Priority> 100  </Priority>  
00130  *
00131  * % machine finsh: gauss distributed event with mue=10 and sigma=5, relative to guard
00132  * "beta"   
00133  * <Stochastic> +Trigger+  +Gauss+  <Parameter> 10  5  </Parameter> </Stochastic>
00134  *
00135  * % break down: gauss distributed event with mue=20 and sigma=5, relative to enabled time
00136  * "mue"   
00137  * <Stochastic> +Delay+  +Gauss+  <Parameter> 20  5  </Parameter> </Stochastic>
00138  *
00139  * % machine repair: prioritised event with priority 100
00140  * "lambda"    
00141  * <Priority> 100  </Priority>  
00142  *
00143  * </SimEvents>
00144  *
00145  * @endcode
00146  *
00147  */
00148 
00149 class SimEventAttribute : public AttributeCFlags {
00150 
00151 FAUDES_TYPE_DECLARATION(Void,SimEventAttribute,AttributeCFlags)
00152 
00153   public:
00154 
00155   /** 
00156    * Default constructor. Construct a SimEventAttribute with 
00157    * priority 0. 
00158    */
00159   SimEventAttribute(void) : AttributeCFlags() { 
00160     mStochastic=false; mPriority=true; mPriorityAttribute.mPriority=0;};
00161 
00162   /** 
00163    * Copy constructor.
00164    */
00165   SimEventAttribute(const SimEventAttribute& rSrc) : AttributeCFlags() { 
00166     DoAssign(rSrc); }
00167 
00168   /** 
00169    * Test for default value 
00170    * 
00171    * @return
00172    *   True, if this attribute has its default value
00173    */
00174    virtual bool IsDefault(void) const {return (!mStochastic) &&
00175      (mPriority && mPriorityAttribute.mPriority==0) && AttributeCFlags::IsDefault(); };
00176 
00177   /** 
00178    * Test for stochastic property.
00179    *
00180    * @return
00181    *   True, if this attribute defines stochastic behaviour
00182    */
00183    bool IsStochastic(void) const {return mStochastic; };
00184 
00185   /** 
00186    * Test for priority property.
00187    *
00188    * @return
00189    *   True, if this attribute defines priority  behaviour
00190    */
00191   bool IsPriority(void) const {return mPriority; };
00192 
00193   /** 
00194    * Set stochastic behaviour. Define this attribute to
00195    * indicate the specified stochastic bahaviour.
00196    *
00197    * @param rStochasticAttribute
00198    *     Define stochastic behaviour
00199    */
00200   void Stochastic(const SimStochasticEventAttribute&  rStochasticAttribute) {
00201     mStochasticAttribute= rStochasticAttribute; mStochastic=true; mPriority=false;};
00202 
00203 
00204   /** 
00205    * Set priority behaviour. Define this attribute to
00206    * indicate execution with the specified priority.
00207    *
00208    * @param rPriorityAttribute
00209    *     Define stochastic behaviour
00210    */
00211   void Priority(const SimPriorityEventAttribute& rPriorityAttribute) {
00212       mPriorityAttribute = rPriorityAttribute; mPriority=true; mStochastic=false; }
00213 
00214 
00215   /**  
00216    * Get priority attribute. Note that the return value
00217    * is only meaningful if the attribute actually is a priority attribute.
00218    *
00219    *  @return
00220    *    Defining data of this attribute's priority behaviour
00221    *
00222    */
00223   const SimPriorityEventAttribute& Priority(void) const {return mPriorityAttribute; };
00224 
00225   /**  
00226    * Get stochastic attribute. Note that the return value
00227    * is only meaningful if the attribute defines stochastic behaviour.
00228    *
00229    *  @return
00230    *    Defining data of this attribute's stochastic behaviour
00231    *
00232    */
00233   const SimStochasticEventAttribute&  Stochastic(void) const {return mStochasticAttribute; };
00234 
00235   /** 
00236    * Next scheduled occurence of this event relative to current time. This is part of the
00237    * execution state. It indicates the instance of time for which the respective event is scheduled
00238    * to occur. Schedules, however, may expire or otherwise become invalid.
00239    */
00240   tpTime::Type mScheduledFor;
00241 
00242   /** 
00243    * Time at which the recent schedule expires. This is part of the
00244    * execution state. Once a schedule expires, the event is re-scheduled.
00245    */
00246   tpTime::Type mExpiresAt;
00247 
00248   /** 
00249    * Amount of time to defer the event. This is part of the
00250    * execution state. It is used for events of delay type and is a count down type
00251    * alarm to trigger the event.
00252    */
00253   tpTime::Type mDelayFor;
00254 
00255   /** 
00256    * Time domain on which the recent schedule was computed. This is part of the
00257    * execution state. It is used to invalidate schedules for events of trigger type.
00258    */
00259   TimeInterval mReferenceInterval;
00260 
00261   /**
00262    * Debug string, incl state
00263    *
00264    */
00265   std::string Str(void) const; 
00266 
00267 protected:
00268 
00269   /** Indicate precense of stochastic behaviour */
00270   bool mStochastic;
00271 
00272   /** Indicate precense of priority property */
00273   bool mPriority;
00274 
00275   /** Priority definition data  */
00276   SimPriorityEventAttribute mPriorityAttribute;
00277 
00278   /** Stochastic definition data  */
00279   SimStochasticEventAttribute mStochasticAttribute;
00280 
00281   /**
00282    * Assignment method. 
00283    *
00284    * @param rSrcAttr
00285    *    Source to assign from
00286    */
00287   void DoAssign(const SimEventAttribute& rSrcAttr);
00288 
00289   /**
00290    * Test equality
00291    *
00292    * @param rOther
00293    *    Attribute to compare with
00294    * @return
00295    *    True/False
00296    */
00297   bool DoEqual(const SimEventAttribute& rOther) const;
00298 
00299   /**
00300    * Reads the attribute from TokenReader, see AttributeVoid for public wrappers.
00301    * 
00302    * If the current token indicates a simulation event section, the method reads all
00303    * consecutive simulation attributes. Else it does nothing. Exceptions may only be thrown
00304    * on invalid data within the section. The label argument is ignored, we use hardcoded
00305    * keywords for the four attributes. The context argument is ignored.
00306    *
00307    * @param rTr
00308    *   TokenReader to read from
00309    * @param rLabel
00310    *   Section to read
00311    * @param pContext
00312    *   Read context to provide contextual information
00313    *
00314    * @exception Exception
00315    *   - IO error (id 1)
00316    */
00317    virtual void DoRead(TokenReader& rTr,const std::string& rLabel="", const Type* pContext=0);
00318  
00319   /**
00320    * Writes the attribute to TokenWriter, see AttributeVoid for public wrappers.
00321    *
00322    * Writes all present simulation event attributes to include the defining data. 
00323    * The label argument is ignored, we use hardcoded keywords. The context argument is ignored.  
00324    *
00325    * @param rTw
00326    *   TokenWriter to write to
00327    * @param rLabel
00328    *   Section to write
00329    * @param pContext
00330    *   Read context to provide contextual information
00331    *
00332    * @exception Exception
00333    *   - IO error (id 2)
00334    */
00335    virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00336 
00337 
00338 
00339 
00340 }; // class SimEventAttribute
00341 
00342 
00343 /**
00344  * Typedef for events with simulation attributes.
00345  */
00346 
00347 typedef TaNameSet<SimEventAttribute> sEventSet;
00348 
00349 /** @} doxygen group */
00350 
00351 } // namespace
00352 
00353 #endif

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