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

libFAUDES 2.14g --- 2009-12-3 --- c++ source docu by doxygen 1.5.6