libFAUDES

Sections

Index

graphfncts.h

Go to the documentation of this file.
00001 /** @file 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 "definitions.h"
00026 #include "vgenerator.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 sets) */
00103   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire);
00104 
00105   /** Constructor (from flags and event sets) */
00106   SccFilter(int mode, const EventSet& rEventsAvoid);
00107 
00108   /** Constructor (from flags and sets) */
00109   SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire, 
00110      const EventSet& rEventsAvoid);
00111 
00112   /** Destructor */
00113   ~SccFilter(void);
00114 
00115   /** Member access */
00116   int Mode(void) const { return mMode;};
00117 
00118 protected:
00119 
00120   /** Flag, combining bit masks from Mode */
00121   int mMode; 
00122   /** States to avoid (if flag StatesAvoid is set) */
00123   const StateSet* pStatesAvoid;
00124   /** States to require (if flag StatesRequire is set) */
00125   const StateSet* pStatesRequire;
00126   /** Events to avoid (if flag EventssAvoid is set) */
00127   const EventSet* pEventsAvoid;
00128 
00129   /** Local sets (optional) */
00130   StateSet* mpStatesAvoid;
00131   StateSet* mpStatesRequire;
00132   EventSet* mpEventsAvoid;
00133 
00134   /** Static emptysets */
00135   const static StateSet msEmptyStates;
00136   const static EventSet msEmptyEvents;
00137 };
00138 
00139 
00140 /**
00141  *
00142  * Search for strongly connected components (SCC). 
00143  * 
00144  * This function partitions the stateset of a generator into equivalent 
00145  * classes such that states x1 and x2 are equivalent iff there is a path from x1
00146  * to x2 AND a path from x2 to x1. 
00147  *
00148  * This function implements the algorithm based on a depth first search
00149  * presented in:
00150  *
00151  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00152  *
00153  * While the original algorithm works on a directed graph, this
00154  * implementation adds some features that refer to transition systems and
00155  * allow to filter SCCs on the run. The filter condition is specified by the
00156  * SccFilter parameter rFilter.
00157  *
00158  * Note: this version is derived from earlier implementations used in 
00159  * various plug-ins; in due course, this version will replace earlier versions; 
00160  * filter conditions are not thouroughly tested.
00161  *
00162  * @param vState
00163  *   State, from which the current recursion is started.
00164  * @param vRcount
00165  *   Denotes the current depth of the recursion.
00166  * @param rGen
00167  *   Transition system to investigate
00168  * @param rFilter
00169  *   Filter out specified transitions
00170  * @param rTodo
00171  *   Set of states that up to now were not found by the
00172  *   depth first search.
00173  * @param rStack
00174  *   Stack of states to represent current path.
00175  * @param rStackStates
00176  *   Set of states that are in rStack
00177  * @param rDfn
00178  *   Map assigning to each state idx its Depth-First Number.
00179  * @param rLowLnk
00180  *   Map assigning to each state its LOWLINK Number.
00181  * @param rSccList
00182  *   Set SCCs (accumulative result).
00183  * @param rRoots
00184  *   Set of states that each are root of some SCC (accumulative result).
00185  *
00186  * 
00187  */
00188 void SearchScc(
00189   const Idx vState,           
00190   int& vRcount,               
00191   const Generator& rGen,      
00192   const SccFilter& rFilter,
00193   StateSet&  rTodo,           
00194   std::stack<Idx>& rStack,    
00195   StateSet& rStackStates,     
00196   std::map<const Idx, int>& rDfn,
00197   std::map<const Idx, int>& rLowLnk, 
00198   std::list<StateSet>& rSccList,  
00199   StateSet& rRoots);       
00200 
00201 
00202 /**
00203  * Compute strongly connected components (SCC) 
00204  *
00205  * This partitions the stateset 
00206  * of a generator into equivalenc classes such that states x1 and x2 are equivalent 
00207  * iff there is a path from x1 to x2 AND a path from x2 to x1. You may specify 
00208  * the filter condition rFilter to ignore certain transitions and/or SCCs; see also SccFilter. 
00209  *
00210  * Technically, this function is a API wrapper that calls the recursive implementation
00211  * SearchScc() as presented in 
00212  *
00213  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00214  *
00215  * 
00216  * @param rGen
00217  *   Generator under investigation
00218  * @param rFilter
00219  *   Filter out specified transitions
00220  * @param rSccList
00221  *   List of SCCs (result)
00222  * @param rRoots
00223  *   Set of states that each are root of some SCC (result).
00224  *
00225  * @return
00226  *   True if SCCs have been found, false if not.
00227  *
00228  * @ingroup GeneratorFunctions
00229  * 
00230  */
00231 bool ComputeScc(
00232   const Generator& rGen,
00233   const SccFilter& rFilter,
00234   std::list<StateSet>& rSccList,
00235   StateSet& rRoots);
00236 
00237 /**
00238  * Compute strongly connected components (SCC) 
00239  *
00240  * This partitions the stateset 
00241  * of a generator into equivalenc classes such that states x1 and x2 are equivalent 
00242  * iff there is a path from x1 to x2 AND a path from x2 to x1. 
00243  *
00244  * Technically, this function is a API wrapper that calls the recursive implementation
00245  * SearchScc() as presented in
00246  * 
00247  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00248  *
00249  *
00250  * @param rGen
00251  *   Generator under investigation
00252  * @param rSccList
00253  *   List of SCCs (result)
00254  * @param rRoots
00255  *   Set of states that each are root of some SCC (result).
00256  *
00257  * @return
00258  *   True if SCCs have been found, false if not.
00259  *   Since there are no filters, true is returned iff the
00260  *   the state set is non-empty.
00261  *
00262  * @ingroup GeneratorFunctions
00263  * 
00264  */
00265 bool ComputeScc(
00266   const Generator& rGen,
00267   std::list<StateSet>& rSccList,
00268   StateSet& rRoots);
00269   
00270 
00271   
00272 /**
00273  * Test for strongly connected components (SCC) 
00274  *
00275  * This functions searchs for the first SCC of the generator rGen 
00276  * while applying the filter rFilter; see SCCFilter for details.
00277  *
00278  * Technically, this function is a API wrapper that calls the recursive implementation
00279  * SearchScc() as presented in 
00280  *
00281  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00282  * 
00283  * @param rGen
00284  *   Generator under investigation
00285  * @param rFilter
00286  *   Filter out specified transitions
00287  * @param rScc
00288  *   First SCC that has been found, empty if no such.
00289  *
00290  * @return
00291  *   True if SCCs have been found, false if not.
00292  *
00293  * @ingroup GeneratorFunctions
00294  * 
00295  */
00296 bool HasScc(
00297   const Generator& rGen,
00298   const SccFilter& rFilter,
00299   StateSet& rScc
00300 );
00301 
00302 /**
00303  * Test for strongly connected components (SCC) 
00304  *
00305  * This functions searchs for the first SCC of the generator rGen 
00306  * while applying the filter rFilter; see SCCFilter for details.
00307  *
00308  * Technically, this function is a API wrapper that calls the recursive implementation
00309  * SearchScc() as presented in 
00310  * 
00311  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
00312  *
00313  * @param rGen
00314  *   Generator under investigation
00315  * @param rFilter
00316  *   Filter out specified transitions
00317  *
00318  * @return
00319  *   True if SCCs have been found, false if not.
00320  *
00321  * @ingroup GeneratorFunctions
00322  * 
00323  */
00324 bool HasScc(
00325   const Generator& rGen,
00326   const SccFilter& rFilter
00327 );
00328 
00329 } // namespace
00330 #endif

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