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() 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: ignore SCCs that consist of one state without selfloop;
00044  * - StatesAvoid: ignore SCCs that contain one or more states from specified set;
00045  * - StatesRequire: ignore SCCs that fail to contain at least one state froma 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 are static objects in that they can not be edited after 
00055  * construction; interally, they use references to condition parameters that are required to
00056  * exisit during the life time of the filter object. 
00057  *
00058  * Technical note: currently, there is no EventsRequire filter because the implementation 
00059  * interprets the transition relation primarily from a directed graph perspective; while StatesRequire
00060  * makes sense for marked states semantics, we are not aware of any applications for
00061  * a corresponding version of EventsRequire; please let us know if you require such an extension. 
00062  *
00063  * @ingroup GeneratorFunctions
00064  */
00065 class SccFilter {
00066 
00067   // Allow search function access
00068   friend void SearchScc(
00069     const Idx vState,           
00070     int& vRcount,               
00071     const Generator& rGen,      
00072     const SccFilter& rFilter,
00073     StateSet&  rTodo,           
00074     std::stack<Idx>& rStack,    
00075     StateSet& rStackStates,     
00076     std::map<const Idx, int>& rDfn,
00077     std::map<const Idx, int>& rLowLnk, 
00078     std::list<StateSet>& rSccList,  
00079     StateSet& rRoots);       
00080 
00081 public:
00082 
00083   /** Typedef for filter modes */
00084   typedef enum { 
00085     NoFilter=0x00,             //// no filters at all (default)
00086     FindFirst=0x01,            //// only report first valid SCC
00087     IgnoreTrivial=0x02,        //// ignore non-cycles, aka singletons without selfloop
00088     StatesAvoid=0x10,          //// filter by avoiding specified states
00089     StatesRequire=0x20,        //// filter by requireing specified states
00090     EventsAvoid=0x40,          //// filter by avoiding specified events
00091     IgnoreLiveLocks=0x1000,    //// ignore cycles with unmarked states only
00092     LiveLocksOnly =0x2000,     //// ignore cycles one or more marked states
00093     IgnoreUnaccessible=0x4000  //// only inspect accessible part
00094   } FMode;
00095 
00096   /** Constructor (no filter) */
00097   SccFilter(void);
00098 
00099   /** Constructor (from flags w.r.t. Generator) */
00100   SccFilter(int mode, const Generator& rGen);
00101 
00102   /** Constructor (from flags and state set, either avoid or require) */
00103   SccFilter(int mode, const StateSet& rStatesAvoidRequire);
00104 
00105   /** Constructor (from flags and state sets) */
00106   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire);
00107 
00108   /** Constructor (from flags and event sets) */
00109   SccFilter(int mode, const EventSet& rEventsAvoid);
00110 
00111   /** Constructor (from flags and sets) */
00112   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire, 
00113      const EventSet& rEventsAvoid);
00114 
00115   /** Destructor */
00116   ~SccFilter(void);
00117 
00118   /** Member access */
00119   int Mode(void) const { return mMode;};
00120 
00121 protected:
00122 
00123   /** Flag, combining bit masks from Mode */
00124   int mMode; 
00125   /** States to avoid (if flag StatesAvoid is set) */
00126   const StateSet* pStatesAvoid;
00127   /** States to require (if flag StatesRequire is set) */
00128   const StateSet* pStatesRequire;
00129   /** Events to avoid (if flag EventssAvoid is set) */
00130   const EventSet* pEventsAvoid;
00131 
00132   /** Local sets (optional) */
00133   StateSet* mpStatesAvoid;
00134   StateSet* mpStatesRequire;
00135   EventSet* mpEventsAvoid;
00136 
00137   /** Static emptysets */
00138   const static StateSet msEmptyStates;
00139   const static EventSet msEmptyEvents;
00140 };
00141 
00142 
00143 /**
00144  *
00145  * Search for strongly connected components (SCC). 
00146  * 
00147  * This function partitions the stateset of a generator into equivalent 
00148  * classes such that states x1 and x2 are equivalent iff there is a path from x1
00149  * to x2 AND a path from x2 to x1. 
00150  *
00151  * This function implements the algorithm based on a depth first search
00152  * presented in:
00153  *
00154  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00155  *
00156  * While the original algorithm works on a directed graph, this
00157  * implementation adds some features that refer to transition systems and
00158  * allow to filter SCCs on the run. The filter condition is specified by the
00159  * SccFilter parameter rFilter.
00160  *
00161  * Note: this version is derived from earlier implementations used in 
00162  * various plug-ins; in due course, this version will replace earlier versions; 
00163  * filter conditions are not thouroughly tested.
00164  *
00165  * @param vState
00166  *   State, from which the current recursion is started.
00167  * @param vRcount
00168  *   Denotes the current depth of the recursion.
00169  * @param rGen
00170  *   Transition system to investigate
00171  * @param rFilter
00172  *   Filter out specified transitions
00173  * @param rTodo
00174  *   Set of states that up to now were not found by the
00175  *   depth first search.
00176  * @param rStack
00177  *   Stack of states to represent current path.
00178  * @param rStackStates
00179  *   Set of states that are in rStack
00180  * @param rDfn
00181  *   Map assigning to each state idx its Depth-First Number.
00182  * @param rLowLnk
00183  *   Map assigning to each state its LOWLINK Number.
00184  * @param rSccList
00185  *   Set SCCs (accumulative result).
00186  * @param rRoots
00187  *   Set of states that each are root of some SCC (accumulative result).
00188  *
00189  * 
00190  */
00191 void SearchScc(
00192   const Idx vState,           
00193   int& vRcount,               
00194   const Generator& rGen,      
00195   const SccFilter& rFilter,
00196   StateSet&  rTodo,           
00197   std::stack<Idx>& rStack,    
00198   StateSet& rStackStates,     
00199   std::map<const Idx, int>& rDfn,
00200   std::map<const Idx, int>& rLowLnk, 
00201   std::list<StateSet>& rSccList,  
00202   StateSet& rRoots);       
00203 
00204 
00205 /**
00206  * Compute strongly connected components (SCC) 
00207  *
00208  * This partitions the stateset 
00209  * of a generator into equivalenc classes such that states x1 and x2 are equivalent 
00210  * iff there is a path from x1 to x2 AND a path from x2 to x1. You may specify 
00211  * the filter condition rFilter to ignore certain transitions and/or SCCs; see also SccFilter. 
00212  *
00213  * Technically, this function is a API wrapper that calls the recursive implementation
00214  * SearchScc() as presented in 
00215  *
00216  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00217  *
00218  * 
00219  * @param rGen
00220  *   Generator under investigation
00221  * @param rFilter
00222  *   Filter out specified transitions
00223  * @param rSccList
00224  *   List of SCCs (result)
00225  * @param rRoots
00226  *   Set of states that each are root of some SCC (result).
00227  *
00228  * @return
00229  *   True if SCCs have been found, false if not.
00230  *
00231  * @ingroup GeneratorFunctions
00232  * 
00233  */
00234 bool ComputeScc(
00235   const Generator& rGen,
00236   const SccFilter& rFilter,
00237   std::list<StateSet>& rSccList,
00238   StateSet& rRoots);
00239 
00240 /**
00241  * Compute strongly connected components (SCC) 
00242  *
00243  * This partitions the stateset 
00244  * of a generator into equivalenc classes such that states x1 and x2 are equivalent 
00245  * iff there is a path from x1 to x2 AND a path from x2 to x1. 
00246  *
00247  * Technically, this function is a API wrapper that calls the recursive implementation
00248  * SearchScc() as presented in
00249  * 
00250  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00251  *
00252  *
00253  * @param rGen
00254  *   Generator under investigation
00255  * @param rSccList
00256  *   List of SCCs (result)
00257  * @param rRoots
00258  *   Set of states that each are root of some SCC (result).
00259  *
00260  * @return
00261  *   True if SCCs have been found, false if not.
00262  *   Since there are no filters, true is returned iff the
00263  *   the state set is non-empty.
00264  *
00265  * @ingroup GeneratorFunctions
00266  * 
00267  */
00268 bool ComputeScc(
00269   const Generator& rGen,
00270   std::list<StateSet>& rSccList,
00271   StateSet& rRoots);
00272   
00273 
00274   
00275 /**
00276  * Test for strongly connected components (SCC) 
00277  *
00278  * This functions searchs for the first SCC of the generator rGen 
00279  * while applying the filter rFilter; see SCCFilter for details.
00280  *
00281  * Technically, this function is a API wrapper that calls the recursive implementation
00282  * SearchScc() as presented in 
00283  *
00284  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00285  * 
00286  * @param rGen
00287  *   Generator under investigation
00288  * @param rFilter
00289  *   Filter out specified transitions
00290  * @param rScc
00291  *   First SCC that has been found, empty if no such.
00292  *
00293  * @return
00294  *   True if SCCs have been found, false if not.
00295  *
00296  * @ingroup GeneratorFunctions
00297  * 
00298  */
00299 bool HasScc(
00300   const Generator& rGen,
00301   const SccFilter& rFilter,
00302   StateSet& rScc
00303 );
00304 
00305 /**
00306  * Test for strongly connected components (SCC) 
00307  *
00308  * This functions searchs for the first SCC of the generator rGen 
00309  * while applying the filter rFilter; see SCCFilter for details.
00310  *
00311  * Technically, this function is a API wrapper that calls the recursive implementation
00312  * SearchScc() as presented in 
00313  * 
00314  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00315  *
00316  * @param rGen
00317  *   Generator under investigation
00318  * @param rFilter
00319  *   Filter out specified transitions
00320  *
00321  * @return
00322  *   True if SCCs have been found, false if not.
00323  *
00324  * @ingroup GeneratorFunctions
00325  * 
00326  */
00327 bool HasScc(
00328   const Generator& rGen,
00329   const SccFilter& rFilter
00330 );
00331 
00332 } // namespace
00333 #endif

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