libFAUDES

Sections

Index

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 protected:
00262 
00263   /** Indicate precense of stochastic behaviour */
00264   bool mStochastic;
00265 
00266   /** Indicate precense of priority property */
00267   bool mPriority;
00268 
00269   /** Priority definition data  */
00270   SimPriorityEventAttribute mPriorityAttribute;
00271 
00272   /** Stochastic definition data  */
00273   SimStochasticEventAttribute mStochasticAttribute;
00274 
00275   /**
00276    * Assignment method. 
00277    *
00278    * @param rSrcAttr
00279    *    Source to assign from
00280    */
00281   void DoAssign(const SimEventAttribute& rSrcAttr);
00282 
00283   /**
00284    * Test equality
00285    *
00286    * @param rOther
00287    *    Attribute to compare with
00288    * @return
00289    *    True/False
00290    */
00291   bool DoEqual(const SimEventAttribute& rOther) const;
00292 
00293   /**
00294    * Reads the attribute from TokenReader, see AttributeVoid for public wrappers.
00295    * 
00296    * If the current token indicates a simulation event section, the method reads all
00297    * consecutive simulation attributes. Else it does nothing. Exceptions may only be thrown
00298    * on invalid data within the section. The label argument is ignored, we use hardcoded
00299    * keywords for the four attributes. The context argument is ignored.
00300    *
00301    * @param rTr
00302    *   TokenReader to read from
00303    * @param rLabel
00304    *   Section to read
00305    * @param pContext
00306    *   Read context to provide contextual information
00307    *
00308    * @exception Exception
00309    *   - IO error (id 1)
00310    */
00311    virtual void DoRead(TokenReader& rTr,const std::string& rLabel="", const Type* pContext=0);
00312  
00313   /**
00314    * Writes the attribute to TokenWriter, see AttributeVoid for public wrappers.
00315    *
00316    * Writes all present simulation event attributes to include the defining data. 
00317    * The label argument is ignored, we use hardcoded keywords. The context argument is ignored.  
00318    *
00319    * @param rTw
00320    *   TokenWriter to write to
00321    * @param rLabel
00322    *   Section to write
00323    * @param pContext
00324    *   Read context to provide contextual information
00325    *
00326    * @exception Exception
00327    *   - IO error (id 2)
00328    */
00329    virtual void DoWrite(TokenWriter& rTw,const std::string& rLabel="", const Type* pContext=0) const;
00330 
00331 
00332 
00333 
00334 }; // class SimEventAttribute
00335 
00336 
00337 /**
00338  * Typedef for events with simulation attributes.
00339  */
00340 
00341 typedef TaNameSet<SimEventAttribute> sEventSet;
00342 
00343 /** @} doxygen group */
00344 
00345 } // namespace
00346 
00347 #endif

libFAUDES 2.18b --- 2010-12-17 --- c++ source docu by doxygen 1.6.3