About
User Reference
C++ API
luafaudes
Developer
Links
libFAUDES online
libFAUDES

Sections

Index

cfl_graphfncts.h

Go to the documentation of this file.
00001 /** @file cfl_graphfncts.h Operations on (directed) graphs. */
00002 
00003 /* FAU Discrete Event Systems Library (libfaudes)
00004 
00005    Copyright (C) 2009  Thomas Moor, Klaus Schmidt, Sebastian Perk
00006    Exclusive copyright is granted to Klaus Schmidt
00007 
00008    This library is free software; you can redistribute it and/or
00009    modify it under the terms of the GNU Lesser General Public
00010    License as published by the Free Software Foundation; either
00011    version 2.1 of the License, or (at your option) any later version.
00012 
00013    This library is distributed in the hope that it will be useful,
00014    but WITHOUT ANY WARRANTY; without even the implied warranty of
00015    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016    Lesser General Public License for more details.
00017 
00018    You should have received a copy of the GNU Lesser General Public
00019    License along with this library; if not, write to the Free Software
00020    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA */
00021 
00022 
00023 #ifndef FAUDES_GRAPHFNCTS_H
00024 
00025 #include "cfl_definitions.h"
00026 #include "cfl_generator.h"
00027 #include <stack>
00028 
00029 namespace faudes {
00030 
00031 
00032 /**
00033  * Filter for strictly connected components (SCC) search/compute routines.
00034  *
00035  * When ComputeScc()/HasScc()/NextScc()  traverse a specified transition sytem in their
00036  * search, a SccFilter parameter can mute certain transitions. The respective
00037  * filter conditions are set by the constructor and consist of a flag word (mMode)
00038  * and additional parameters (depending on the flags). The Flags can be combined
00039  * from the following: 
00040  *
00041  * - NoFilter: std textbook beheviour;
00042  * - FindFirst: stop the search after one SCC has been found;
00043  * - IgnoreTrivial: dont report singleton SCCs without selfloop;
00044  * - StatesAvoid: mute specified states from trasition structure;
00045  * - StatesRequire: dont report SCCs that fail to contain at least one state from the specified set;
00046  * - EventsAvoid: mute any transitions with an event label from the specified set.
00047  *
00048  * Convenience modes set up the state related filter conditions from the set of marked states:
00049  *
00050  * - IgnoreLiveLocks: set StatesRequire to the marked states of a specified Generator;
00051  * - LiveLocksOnly: set StatesAvoid to the marked states of a specified Generator;
00052  * - IgnoreUnaccessible: initialise todo list with accessible states only.
00053  *
00054  * Technical note: SccFilters interally use references to condition 
00055  * parameters that are required to exist during the life time of the filter object. 
00056  *
00057  * Technical note: currently, there is no EventsRequire filter because the implementation 
00058  * interprets the transition relation primarily from a directed graph perspective; while StatesRequire
00059  * makes sense for marked states semantics, we are not aware of any applications for
00060  * a corresponding version of EventsRequire; please let us know if you require such an extension. 
00061  *
00062  * @ingroup GeneratorFunctions
00063  */
00064 class SccFilter {
00065 
00066   // Allow search function access
00067   friend void SearchScc(
00068     const Idx vState,           
00069     int& vRcount,               
00070     const Generator& rGen,      
00071     const SccFilter& rFilter,
00072     StateSet&  rTodo,           
00073     std::stack<Idx>& rStack,    
00074     StateSet& rStackStates,     
00075     std::map<const Idx, int>& rDfn,
00076     std::map<const Idx, int>& rLowLnk, 
00077     std::list<StateSet>& rSccList,  
00078     StateSet& rRoots);       
00079   friend bool ComputeNextScc(
00080     const Generator& rGen,
00081     SccFilter& rFilter,
00082     StateSet& rScc
00083   );
00084 
00085 public:
00086 
00087   /** Typedef for filter modes */
00088   typedef enum { 
00089     FmNoFilter=0x00,             //// no filters at all (default)
00090     FmFindFirst=0x01,            //// only report first valid SCC
00091     FmIgnoreTrivial=0x02,        //// ignore non-cycles, aka singletons without selfloop
00092     FmStatesAvoid=0x10,          //// filter by avoiding specified states
00093     FmStatesRequire=0x20,        //// filter by requireing specified states
00094     FmEventsAvoid=0x40,          //// filter by avoiding specified events
00095     FmIgnoreLiveLocks=0x1000,    //// ignore cycles with unmarked states only
00096     FmLiveLocksOnly =0x2000,     //// ignore cycles with one or more marked states
00097     FmIgnoreUnaccessible=0x4000  //// only inspect accessible part
00098   } FMode;
00099 
00100   /** Constructor (no filter) */
00101   SccFilter(void);
00102 
00103   /** Constructor (copy constructor) */
00104   SccFilter(const SccFilter& rSrc);
00105 
00106   /** Constructor (from flags w.r.t. Generator) */
00107   SccFilter(int mode, const Generator& rGen);
00108 
00109   /** Constructor (from flags and state set, either avoid or require) */
00110   SccFilter(int mode, const StateSet& rStatesAvoidRequire);
00111 
00112   /** Constructor (from flags and state sets) */
00113   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire);
00114 
00115   /** Constructor (from flags and event sets) */
00116   SccFilter(int mode, const EventSet& rEventsAvoid);
00117 
00118   /** Constructor (from flags and sets) */
00119   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire, 
00120      const EventSet& rEventsAvoid);
00121 
00122   /** Destructor */
00123   ~SccFilter(void);
00124 
00125   /** Member access */
00126   int Mode(void) const { return mMode;};
00127 
00128   /** Member access */
00129   const StateSet& StatesAvoid(void) const { return *pStatesAvoid;};
00130 
00131   /** Member access */
00132   const StateSet& StatesRequire(void) const { return *pStatesRequire;};
00133 
00134   /** Edit filter (RTI): no filter */
00135   void Clear(void);
00136 
00137   /** Edit filter (RTI): set avoid states */
00138   void StatesAvoid(const StateSet& rStatesAvoid);
00139 
00140   /** Edit filter (RTI): set required states */
00141   void StatesRequire(const StateSet& rStatesRequire);
00142 
00143   /** Edit filter (RTI): set avoid events */
00144   void EventsAvoid(const EventSet& rEventsAvoid);
00145 
00146   /** Edit filter (RTI): ignore trivial */
00147   void IgnoreTrivial(bool flag);  
00148 
00149   /** Edit filter (RTI): find first */
00150   void FindFirst(bool flag);  
00151 
00152 
00153 protected:
00154 
00155   /** Edit filter (RTI): avoid states */
00156   void MergeStatesAvoid(const StateSet& rStatesAvoid);
00157 
00158   /** Flag, combining bit masks from Mode */
00159   int mMode; 
00160   /** States to avoid (if flag StatesAvoid is set) */
00161   const StateSet* pStatesAvoid;
00162   /** States to require (if flag StatesRequire is set) */
00163   const StateSet* pStatesRequire;
00164   /** Events to avoid (if flag EventssAvoid is set) */
00165   const EventSet* pEventsAvoid;
00166 
00167   /** Local sets (optional) */
00168   StateSet* mpStatesAvoid;
00169   StateSet* mpStatesRequire;
00170   EventSet* mpEventsAvoid;
00171 
00172   /** Static emptysets */
00173   const static StateSet msEmptyStates;
00174   const static EventSet msEmptyEvents;
00175 };
00176 
00177 
00178 /**
00179  *
00180  * Search for strongly connected components (SCC). 
00181  * 
00182  * This function partitions the stateset of a generator into equivalent 
00183  * classes such that states x1 and x2 are equivalent iff there is a path from x1
00184  * to x2 AND a path from x2 to x1. 
00185  *
00186  * This function implements the algorithm based on a depth first search
00187  * presented in:
00188  *
00189  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00190  *
00191  * While the original algorithm works on a directed graph, this
00192  * implementation adds some features that refer to transition systems and
00193  * allow to filter SCCs on the run. The filter condition is specified by the
00194  * SccFilter parameter rFilter.
00195  *
00196  * Note: this version is derived from earlier implementations used in 
00197  * various plug-ins; in due course, this version will replace earlier versions; 
00198  * filter conditions are not thouroughly tested.
00199  *
00200  * Note: for a convenience API see also ComputeScc()
00201  *
00202  * @param vState
00203  *   State, from which the current recursion is started.
00204  * @param vRcount
00205  *   Denotes the current depth of the recursion.
00206  * @param rGen
00207  *   Transition system to investigate
00208  * @param rFilter
00209  *   Filter out specified transitions
00210  * @param rTodo
00211  *   Set of states that up to now were not found by the
00212  *   depth first search.
00213  * @param rStack
00214  *   Stack of states to represent current path.
00215  * @param rStackStates
00216  *   Set of states that are in rStack
00217  * @param rDfn
00218  *   Map assigning to each state idx its Depth-First Number.
00219  * @param rLowLnk
00220  *   Map assigning to each state its LOWLINK Number.
00221  * @param rSccList
00222  *   Set SCCs (accumulative result).
00223  * @param rRoots
00224  *   Set of states that each are root of some SCC (accumulative result).
00225  *
00226  * 
00227  */
00228 void SearchScc(
00229   const Idx vState,           
00230   int& vRcount,               
00231   const Generator& rGen,      
00232   const SccFilter& rFilter,
00233   StateSet&  rTodo,           
00234   std::stack<Idx>& rStack,    
00235   StateSet& rStackStates,     
00236   std::map<const Idx, int>& rDfn,
00237   std::map<const Idx, int>& rLowLnk, 
00238   std::list<StateSet>& rSccList,  
00239   StateSet& rRoots);       
00240 
00241 
00242 /**
00243  * Compute strongly connected components (SCC) 
00244  *
00245  * This function is a API wrapper that calls the recursive implementation
00246  * SearchScc().
00247  *
00248  * 
00249  * @param rGen
00250  *   Generator under investigation
00251  * @param rFilter
00252  *   Filter specified transitions
00253  * @param rSccList
00254  *   List of SCCs (result)
00255  * @param rRoots
00256  *   Set of states that each are root of some SCC (result).
00257  *
00258  * @return
00259  *   True if SCCs have been found, false if not.
00260  *
00261  * @ingroup GeneratorFunctions
00262  * 
00263  */
00264 bool ComputeScc(
00265   const Generator& rGen,
00266   const SccFilter& rFilter,
00267   std::list<StateSet>& rSccList,
00268   StateSet& rRoots);
00269 
00270 
00271 /**
00272  * Compute strongly connected components (SCC) 
00273  *
00274  * This function is a API wrapper that calls the recursive implementation
00275  * SearchScc().
00276  *
00277  * @param rGen
00278  *   Generator under investigation
00279  * @param rSccList
00280  *   List of SCCs (result)
00281  * @param rRoots
00282  *   Set of states that each are root of some SCC (result).
00283  *
00284  * @return
00285  *   True if SCCs have been found, false if not.
00286  *   Since there are no filters, true is returned iff the
00287  *   the state set is non-empty.
00288  *
00289  * @ingroup GeneratorFunctions
00290  * 
00291  */
00292 bool ComputeScc(
00293   const Generator& rGen,
00294   std::list<StateSet>& rSccList,
00295   StateSet& rRoots);
00296   
00297 
00298   
00299 /**
00300  * Compute strongly connected component (SCC) 
00301  *
00302  * This function is a API wrapper that calls the recursive implementation
00303  * SearchScc(). It internally edits the filter to require the specified
00304  * initial state and to stop on the first SCC found. In particular, any
00305  * other state requirement will be ignored.
00306  *
00307  * @param rGen
00308  *   Generator under investigation
00309  * @param rFilter
00310  *   Filter specified transitions
00311  * @param q0
00312  *   Initial state for SCC.
00313  * @param rScc
00314  *   SCC (result)
00315  *
00316  * @return
00317  *   True if an SCC has been found, false if not.
00318  *
00319  * @ingroup GeneratorFunctions
00320  * 
00321  */
00322 bool ComputeScc(
00323   const Generator& rGen,
00324   const SccFilter& rFilter,
00325   Idx q0, 
00326   StateSet& rScc
00327 );
00328 
00329 
00330 
00331 /**
00332  * Compute one strongly connected components (SCC) 
00333  *
00334  * This functions searchs for the first SCC of the generator rGen 
00335  * while applying the filter rFilter; see SCCFilter for details.
00336  *
00337  * Technically, this function is a API wrapper that calls the recursive implementation
00338  * SearchScc() as presented in 
00339  *
00340  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00341  * 
00342  * @param rGen
00343  *   Generator under investigation
00344  * @param rFilter
00345  *   Filter out specified transitions
00346  * @param rScc
00347  *   First SCC that has been found, empty if no such.
00348  *
00349  * @return
00350  *   True if SCCs have been found, false if not.
00351  *
00352  * @ingroup GeneratorFunctions
00353  * 
00354  */
00355 
00356 bool ComputeScc(
00357   const Generator& rGen,
00358   const SccFilter& rFilter,
00359   StateSet& rScc
00360 );
00361 
00362 /**
00363  * Test for strongly connected components (SCC) 
00364  *
00365  * This functions searchs for the first SCC of the generator rGen 
00366  * while applying the filter rFilter; see SCCFilter for details.
00367  *
00368  * Technically, this function is an API wrapper that calls the recursive implementation
00369  * SearchScc() as presented in 
00370  * 
00371  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00372  *
00373  * @param rGen
00374  *   Generator under investigation
00375  * @param rFilter
00376  *   Filter out specified transitions
00377  *
00378  * @return
00379  *   True if SCCs have been found, false if not.
00380  *
00381  * @ingroup GeneratorFunctions
00382  * 
00383  */
00384 bool HasScc(
00385   const Generator& rGen,
00386   const SccFilter& rFilter
00387 );
00388 
00389 
00390 /**
00391  * Compute next SCC
00392  *
00393  * This function provides an API for the iterative computation
00394  * of SCCs. It invokes SearchScc() to find the next SCC and then
00395  * adds the SCC to the StatesAvoid Filter. This approach is 
00396  * not computationally efficient but it allows for simple Lua wrappers.
00397  *    
00398  * @param rGen
00399  *   Generator under investigation
00400  * @param rFilter
00401  *   Filter out specified transitions
00402  * @param rScc
00403  *   First SCC that has been found, empty if no such.
00404  *
00405  * @return
00406  *   True if an SCC has been found, false if not.
00407  *
00408  * @ingroup GeneratorFunctions
00409  * 
00410  */
00411 bool ComputeNextScc(
00412   const Generator& rGen,
00413   SccFilter& rFilter,
00414   StateSet& rScc
00415 );
00416 
00417 } // namespace
00418 #endif

libFAUDES 2.22k --- 2013.04.02 --- c++ source docu by doxygen