cfl_graphfncts.h
Go to the documentation of this file.
1 /** @file cfl_graphfncts.h Operations on (directed) graphs. */
2 
3 /* FAU Discrete Event Systems Library (libfaudes)
4 
5  Copyright (C) 2009 Thomas Moor, Klaus Schmidt, Sebastian Perk
6  Exclusive copyright is granted to Klaus Schmidt
7 
8  This library is free software; you can redistribute it and/or
9  modify it under the terms of the GNU Lesser General Public
10  License as published by the Free Software Foundation; either
11  version 2.1 of the License, or (at your option) any later version.
12 
13  This library is distributed in the hope that it will be useful,
14  but WITHOUT ANY WARRANTY; without even the implied warranty of
15  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16  Lesser General Public License for more details.
17 
18  You should have received a copy of the GNU Lesser General Public
19  License along with this library; if not, write to the Free Software
20  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
21 
22 
23 #ifndef FAUDES_GRAPHFNCTS_H
24 
25 #include "cfl_definitions.h"
26 #include "cfl_generator.h"
27 #include <stack>
28 
29 namespace faudes {
30 
31 
32 /**
33  * Filter for strictly connected components (SCC) search/compute routines.
34  *
35  * When ComputeScc()/HasScc()/NextScc() traverse a specified transition sytem in their
36  * search, a SccFilter parameter can mute certain transitions. The respective
37  * filter conditions are set by the constructor and consist of a flag word (mMode)
38  * and additional parameters (depending on the flags). The Flags can be combined
39  * from the following:
40  *
41  * - NoFilter: std textbook beheviour;
42  * - FindFirst: stop the search after one SCC has been found;
43  * - IgnoreTrivial: dont report singleton SCCs without selfloop;
44  * - StatesAvoid: mute specified states from trasition structure;
45  * - StatesRequire: dont report SCCs that fail to contain at least one state from the specified set;
46  * - EventsAvoid: mute any transitions with an event label from the specified set.
47  *
48  * Convenience modes set up the state related filter conditions from the set of marked states:
49  *
50  * - IgnoreLiveLocks: set StatesRequire to the marked states of a specified Generator;
51  * - LiveLocksOnly: set StatesAvoid to the marked states of a specified Generator;
52  * - IgnoreUnaccessible: initialise todo list with accessible states only.
53  *
54  * Technical note: SccFilters interally use references to condition
55  * parameters that are required to exist during the life time of the filter object.
56  *
57  * Technical note: currently, there is no EventsRequire filter because the implementation
58  * interprets the transition relation primarily from a directed graph perspective; while StatesRequire
59  * makes sense for marked states semantics, we are not aware of any applications for
60  * a corresponding version of EventsRequire; please let us know if you require such an extension.
61  *
62  * @ingroup GeneratorFunctions
63  */
64 class SccFilter {
65 
66  // Allow search function access
67  friend void SearchScc(
68  const Idx vState,
69  int& vRcount,
70  const Generator& rGen,
71  const SccFilter& rFilter,
72  StateSet& rTodo,
73  std::stack<Idx>& rStack,
74  StateSet& rStackStates,
75  std::map<const Idx, int>& rDfn,
76  std::map<const Idx, int>& rLowLnk,
77  std::list<StateSet>& rSccList,
78  StateSet& rRoots);
79  friend bool ComputeNextScc(
80  const Generator& rGen,
81  SccFilter& rFilter,
82  StateSet& rScc
83  );
84 
85 public:
86 
87  /** Typedef for filter modes */
88  typedef enum {
89  FmNoFilter=0x00, //// no filters at all (default)
90  FmFindFirst=0x01, //// only report first valid SCC
91  FmIgnoreTrivial=0x02, //// ignore non-cycles, aka singletons without selfloop
92  FmStatesAvoid=0x10, //// filter by avoiding specified states
93  FmStatesRequire=0x20, //// filter by requireing specified states
94  FmEventsAvoid=0x40, //// filter by avoiding specified events
95  FmIgnoreLiveLocks=0x1000, //// ignore cycles with unmarked states only
96  FmLiveLocksOnly =0x2000, //// ignore cycles with one or more marked states
97  FmIgnoreUnaccessible=0x4000 //// only inspect accessible part
98  } FMode;
99 
100  /** Constructor (no filter) */
101  SccFilter(void);
102 
103  /** Constructor (copy constructor) */
104  SccFilter(const SccFilter& rSrc);
105 
106  /** Constructor (from flags w.r.t. Generator) */
107  SccFilter(int mode, const Generator& rGen);
108 
109  /** Constructor (from flags and state set, either avoid or require) */
110  SccFilter(int mode, const StateSet& rStatesAvoidRequire);
111 
112  /** Constructor (from flags and state sets) */
113  SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire);
114 
115  /** Constructor (from flags and event sets) */
116  SccFilter(int mode, const EventSet& rEventsAvoid);
117 
118  /** Constructor (from flags and sets) */
119  SccFilter(int mode, const StateSet& rStatesAvoid, const StateSet& rStatesRequire,
120  const EventSet& rEventsAvoid);
121 
122  /** Destructor */
123  ~SccFilter(void);
124 
125  /** Member access */
126  int Mode(void) const { return mMode;};
127 
128  /** Member access */
129  const StateSet& StatesAvoid(void) const { return *pStatesAvoid;};
130 
131  /** Member access */
132  const StateSet& StatesRequire(void) const { return *pStatesRequire;};
133 
134  /** Edit filter (RTI): no filter */
135  void Clear(void);
136 
137  /** Edit filter (RTI): set avoid states */
138  void StatesAvoid(const StateSet& rStatesAvoid);
139 
140  /** Edit filter (RTI): set required states */
141  void StatesRequire(const StateSet& rStatesRequire);
142 
143  /** Edit filter (RTI): set avoid events */
144  void EventsAvoid(const EventSet& rEventsAvoid);
145 
146  /** Edit filter (RTI): ignore trivial */
147  void IgnoreTrivial(bool flag);
148 
149  /** Edit filter (RTI): find first */
150  void FindFirst(bool flag);
151 
152 
153 protected:
154 
155  /** Edit filter (RTI): avoid states */
156  void MergeStatesAvoid(const StateSet& rStatesAvoid);
157 
158  /** Flag, combining bit masks from Mode */
159  int mMode;
160  /** States to avoid (if flag StatesAvoid is set) */
162  /** States to require (if flag StatesRequire is set) */
164  /** Events to avoid (if flag EventssAvoid is set) */
166 
167  /** Local sets (optional) */
171 
172  /** Static emptysets */
173  const static StateSet msEmptyStates;
174  const static EventSet msEmptyEvents;
175 };
176 
177 
178 /**
179  *
180  * Search for strongly connected components (SCC).
181  *
182  * This function partitions the stateset of a generator into equivalent
183  * classes such that states x1 and x2 are equivalent iff there is a path from x1
184  * to x2 AND a path from x2 to x1.
185  *
186  * This function implements the algorithm based on a recursive depth first search
187  * presented in:
188  *
189  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
190  *
191  * While the original algorithm works on a directed graph, this
192  * implementation adds some features that refer to transition systems and
193  * allow to filter SCCs on the run. The filter condition is specified by the
194  * SccFilter parameter rFilter.
195  *
196  * Note: this version is derived from earlier implementations used in
197  * various plug-ins; in due course, this version will replace earlier versions.
198  *
199  * Note: Due to the recursive implementation, this function requires a stack
200  * size proportional to the largest SCC. We have experienced typical default
201  * configurations to be good for a depth of about 80000 (Mac OSX 10.6, Debian 7.4).
202  * For SCCs exceeding the default stack size, you may adjust the operating system
203  * parameters accordingly. On Unix/Linux/MacOsX this is done by the shell command
204  * "ulimit -s hard". A future revision of SearchSCC() may be re-designed to
205  * circumvent this inconvenient issue.
206  *
207  * Note: for a convenience API see also ComputeScc()
208  *
209  * @param vState
210  * State, from which the current recursion is started.
211  * @param vRcount
212  * Denotes the current depth of the recursion.
213  * @param rGen
214  * Transition system to investigate
215  * @param rFilter
216  * Filter out specified transitions
217  * @param rTodo
218  * Set of states that up to now were not found by the
219  * depth first search.
220  * @param rStack
221  * Stack of states to represent current path.
222  * @param rStackStates
223  * Set of states that are in rStack
224  * @param rDfn
225  * Map assigning to each state idx its Depth-First Number.
226  * @param rLowLnk
227  * Map assigning to each state its LOWLINK Number.
228  * @param rSccList
229  * Set SCCs (accumulative result).
230  * @param rRoots
231  * Set of states that each are root of some SCC (accumulative result).
232  *
233  *
234  */
235 void SearchScc(
236  const Idx vState,
237  int& vRcount,
238  const Generator& rGen,
239  const SccFilter& rFilter,
240  StateSet& rTodo,
241  std::stack<Idx>& rStack,
242  StateSet& rStackStates,
243  std::map<const Idx, int>& rDfn,
244  std::map<const Idx, int>& rLowLnk,
245  std::list<StateSet>& rSccList,
246  StateSet& rRoots);
247 
248 
249 /**
250  * Compute strongly connected components (SCC)
251  *
252  * This function is a API wrapper that calls the recursive implementation
253  * SearchScc().
254  *
255  *
256  * @param rGen
257  * Generator under investigation
258  * @param rFilter
259  * Filter specified transitions
260  * @param rSccList
261  * List of SCCs (result)
262  * @param rRoots
263  * Set of states that each are root of some SCC (result).
264  *
265  * @return
266  * True if SCCs have been found, false if not.
267  *
268  * @ingroup GeneratorFunctions
269  *
270  */
271 bool ComputeScc(
272  const Generator& rGen,
273  const SccFilter& rFilter,
274  std::list<StateSet>& rSccList,
275  StateSet& rRoots);
276 
277 
278 /**
279  * Compute strongly connected components (SCC)
280  *
281  * This function is a API wrapper that calls the recursive implementation
282  * SearchScc().
283  *
284  * @param rGen
285  * Generator under investigation
286  * @param rSccList
287  * List of SCCs (result)
288  * @param rRoots
289  * Set of states that each are root of some SCC (result).
290  *
291  * @return
292  * True if SCCs have been found, false if not.
293  * Since there are no filters, true is returned iff the
294  * the state set is non-empty.
295  *
296  * @ingroup GeneratorFunctions
297  *
298  */
299 bool ComputeScc(
300  const Generator& rGen,
301  std::list<StateSet>& rSccList,
302  StateSet& rRoots);
303 
304 
305 
306 /**
307  * Compute strongly connected component (SCC)
308  *
309  * This function is a API wrapper that calls the recursive implementation
310  * SearchScc(). It internally edits the filter to require the specified
311  * initial state and to stop on the first SCC found. In particular, any
312  * other state requirement will be ignored.
313  *
314  * @param rGen
315  * Generator under investigation
316  * @param rFilter
317  * Filter specified transitions
318  * @param q0
319  * Initial state for SCC.
320  * @param rScc
321  * SCC (result)
322  *
323  * @return
324  * True if an SCC has been found, false if not.
325  *
326  * @ingroup GeneratorFunctions
327  *
328  */
329 bool ComputeScc(
330  const Generator& rGen,
331  const SccFilter& rFilter,
332  Idx q0,
333  StateSet& rScc
334 );
335 
336 
337 
338 /**
339  * Compute one strongly connected components (SCC)
340  *
341  * This functions searchs for the first SCC of the generator rGen
342  * while applying the filter rFilter; see SCCFilter for details.
343  *
344  * Technically, this function is a API wrapper that calls the recursive implementation
345  * SearchScc() as presented in
346  *
347  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
348  *
349  * @param rGen
350  * Generator under investigation
351  * @param rFilter
352  * Filter out specified transitions
353  * @param rScc
354  * First SCC that has been found, empty if no such.
355  *
356  * @return
357  * True if SCCs have been found, false if not.
358  *
359  * @ingroup GeneratorFunctions
360  *
361  */
362 
363 bool ComputeScc(
364  const Generator& rGen,
365  const SccFilter& rFilter,
366  StateSet& rScc
367 );
368 
369 /**
370  * Test for strongly connected components (SCC)
371  *
372  * This functions searchs for the first SCC of the generator rGen
373  * while applying the filter rFilter; see SCCFilter for details.
374  *
375  * Technically, this function is an API wrapper that calls the recursive implementation
376  * SearchScc() as presented in
377  *
378  * -- Aho, Hopcroft, Ullman: The Design and Analysis of Computer Algorithms --
379  *
380  * @param rGen
381  * Generator under investigation
382  * @param rFilter
383  * Filter out specified transitions
384  *
385  * @return
386  * True if SCCs have been found, false if not.
387  *
388  * @ingroup GeneratorFunctions
389  *
390  */
391 bool HasScc(
392  const Generator& rGen,
393  const SccFilter& rFilter
394 );
395 
396 
397 /**
398  * Compute next SCC
399  *
400  * This function provides an API for the iterative computation
401  * of SCCs. It invokes SearchScc() to find the next SCC and then
402  * adds the SCC to the StatesAvoid Filter. This approach is
403  * not computationally efficient but it allows for simple Lua wrappers.
404  *
405  * @param rGen
406  * Generator under investigation
407  * @param rFilter
408  * Filter out specified transitions
409  * @param rScc
410  * First SCC that has been found, empty if no such.
411  *
412  * @return
413  * True if an SCC has been found, false if not.
414  *
415  * @ingroup GeneratorFunctions
416  *
417  */
418 bool ComputeNextScc(
419  const Generator& rGen,
420  SccFilter& rFilter,
421  StateSet& rScc
422 );
423 
424 } // namespace
425 #endif

libFAUDES 2.24g --- 2014.09.15 --- c++ api documentaion by doxygen