HeuristicChain Class Reference

Class that manages a list of heuristics. More...

#include <HeuristicChain.h>

Collaboration diagram for HeuristicChain:

Public Member Functions
virtual void	showArguments (std::ostream &os)
	Display valid command line arguments for heuristics in the chain.
virtual bool	parseArguments (int &argc, char **argv)
	Permits heuristics in the chain to process command line arguments.
virtual int	initialize ()
	Initializes all the heuristics in the chain.
virtual int	setReferenceEST (const int estIdx)
	Set the reference EST against which heuristics are to be run.
virtual bool	addHeuristic (Heuristic *heuristic)
	Add the given heuristic to the heuristic chain.
bool	shouldAnalyze (const int otherEST)
	Determine whether the analyzer should perform core (computationally intensive) analysis, according to this heuristic chain.
void	printStats (std::ostream &os, const int rank) const
	Method to display statistics regarding operation of all the heuristics in this chain.
void	setHint (const std::string &hintKey, const int hintValue)
	Set a hint to be used by other algorithms.
bool	getHint (const std::string &hintKey, int &hintValue) const
	Obtain the value associated with a given hint.
Heuristic *	getHeuristic (const std::string &name) const
	Method to obtain pointer to a given heuristic object.
virtual	~HeuristicChain ()
	The destructor.
Static Public Member Functions
static HeuristicChain *	setupChain (const char *heuristicStr, const int refESTidx, const std::string &outputFile)
	Create the heuristics in the chain.
static HeuristicChain *	getHeuristicChain ()
	Get a pointer to the instance of the heuristic chain.
Protected Attributes
StringIntMap	hints
	A hash map to store hints from heuristics.
Private Member Functions
	HeuristicChain ()
	The constructor.
Private Attributes
std::vector< Heuristic * >	chain
	The vector containing a list of heuristics in the chain.
Static Private Attributes
static HeuristicChain *	ptrInstance = NULL
	The pointer to the singleton instance of this class.

Detailed Description

Class that manages a list of heuristics.

This class represents a list of heuristics that are used to try and minimize the number of times EST analysis is performed on a given pair of ESTs. Note that EST analysis (using d2 or clu) is a time consuming task and it must be performed sparingly to reduce runtimes (particularly when large sets of ESTs need to be clustered). The heuristics try to elimintate performing EST analysis on pairs that are most likely unrelated (and will not be in the same cluster).

Each heuristic in the chain implements a specific heuristic and returns a true or false value. If the result is false, then detailed EST analysis is not performed. However, if the result is true, then the next heuristic in the chain is used to further ensure that the comparison is really needed. It is the responsiblity of the caller to ensure that the chain of hueristics is correctly set so that the cheaper (possibly less aggressive) heuristic is run first followed by more computationally-expensive (and more aggressively filtering) heuristics are run.

Definition at line 62 of file HeuristicChain.h.

Constructor & Destructor Documentation

HeuristicChain::~HeuristicChain ( ) [virtual]

The destructor.

The destructor frees up all the heuristics added to this heuristic chain.

Definition at line 111 of file HeuristicChain.cpp.

References chain.

HeuristicChain::HeuristicChain ( ) [private]

The constructor.

This is made private because the heuristic chain is a singleton, and should only be instantiated from the getHeuristicChain() static method.

Definition at line 118 of file HeuristicChain.cpp.

Member Function Documentation

bool HeuristicChain::addHeuristic ( Heuristic * heuristic ) [virtual]

Add the given heuristic to the heuristic chain.

This method permits the heuristic chain to takes ownership of a given heuristic object by added it to its internal chain.

Note:: The heuristic chain takes ownership of the object therefore that the heuristic pointer passed to this method must not be deleted by the caller.

Parameters:

[in] heuristic The instance of class Heuristic that should be added to the heuristic chain.

Returns:: This method returns true if the heuristic was successfully added. On errors this method returns false.

Definition at line 66 of file HeuristicChain.cpp.

References ASSERT, and chain.

Referenced by setupChain().

Heuristic * HeuristicChain::getHeuristic ( const std::string & name ) const

Method to obtain pointer to a given heuristic object.

This method can be used to obtain a pointer to a specific heuristic class present in this chain. If the heruistic does not exist then this method returns NULL.

Note:: The caller must not delete the returned pointer.

Parameters:

[in] name The name associated with a given heuristic.

Returns:: If the heursitic was found then this method returns a valid (non-NULL) pointer to the heuristic object. If the heuristic was not found, then this method returns NULL.

Definition at line 100 of file HeuristicChain.cpp.

References chain.

static HeuristicChain* HeuristicChain::getHeuristicChain ( ) [inline, static]

Get a pointer to the instance of the heuristic chain.

Since this class is a singleton, the constructor is private and the only way to obtain an instance of the class is through this method. The heuristic chain is available only after the setupChain method (that is invoked from main right after command line arguments are validated) has successfully completed its operation. Until such time this method simply returns NULL.

Returns:: The process-wide unique pointer to the heuristic chain.

Definition at line 102 of file HeuristicChain.h.

References ptrInstance.

Referenced by PMSTClusterMaker::makeClusters(), MSTClusterMaker::populateCache(), UVSampleHeuristic::runHeuristic(), and NewUVHeuristic::runHeuristic().

bool HeuristicChain::getHint	(	const std::string &	hintKey,
		int &	hintValue
	)			const `[inline]`

Obtain the value associated with a given hint.

This method must be used to obtain the hint value associated with a given hint key. If the hint value is available, then it is stored in the hintValue parameter.

Parameters:

`[in]`	hintKey	The string identifier associated with the hint whose value is to be retrieved.
`[out]`	hintValue	The parameter into which the hint value (if available) must be stored.

Returns:: This method returns true if the requested hint was found and hintValue was updated. Otherwise this method returns false.

Definition at line 275 of file HeuristicChain.h.

References hints.

Referenced by TwoPassD2::getMetric(), MSTClusterMaker::populateCache(), and D2::runD2().

int HeuristicChain::initialize ( ) [virtual]

Initializes all the heuristics in the chain.

This method iterates over all the heuristics that have been added ot this chain and calls initialize() on each one of them. If any one of the heuristics are unable to initialize correctly, then this method immediately returns an non-zero error code.

Returns:: This method returns zero on success. On errors this method returns a non-zero value.

Definition at line 74 of file HeuristicChain.cpp.

References chain, and NO_ERROR.

Referenced by FWAnalyzer::initialize().

bool HeuristicChain::parseArguments	(	int &	argc,
		char **	argv
	)			`[virtual]`

Permits heuristics in the chain to process command line arguments.

This method iterates over the heuristics that have been added to this chain and invokes parseArguments() method on each one of them. This permits each heuristic in the chain to receive and process command line parameters targeted for the heuristics.

Parameters:

`[in,out]`	argc	The number of command line arguments currently present in argv (the parameter list).
`[in,out]`	argv	The list of command line arguments to be consumed by various heuristics, if they find parameters intended for their use.

Returns:: This method returns true if all the heuristics in the chain successfully processed command line arguments. If an incorrect command line argument is received by any one of the heuristics then this method returns false to flag an error.

Definition at line 55 of file HeuristicChain.cpp.

References chain.

Referenced by main().

void HeuristicChain::printStats	(	std::ostream &	os,
		const int	rank
	)			const

Method to display statistics regarding operation of all the heuristics in this chain.

This method can be used to obtain a dump of the statistics gathered regarding the operation of all the heuristics in this chain. The typical statistic generated by heuristics includes:

The number of times the heuristic was called. More specifically this value indicates the number of times the shouldAnalyze() method was invoked.
The number of successful matches reported by this heuristic. This number indirectly indicates the number of times other heuristics or the actual heavy weight algorithm was invoked.

Parameters:

`[out]`	os	The output stream to which the statistics regarding the heuristics is to be dumped.
`[in]`	rank	The rank of the process for which the statistics is being displayed.

Definition at line 123 of file HeuristicChain.cpp.

References chain.

Referenced by main().

void HeuristicChain::setHint	(	const std::string &	hintKey,
		const int	hintValue
	)			`[inline]`

Set a hint to be used by other algorithms.

This method can be used by various heuristics to set hints for use by other algorithms after their operation. The hints are typically set by heuristics at the end of their runHeuristics method. The hints are then used by other heuristics or by the heavy weight EST analysis algorithms (such as D2).

Parameters:

`[in]`	hintKey	The string identifier associated with the hint. Using string identifiers makes the use of hints a bit more programmer friendly and makes the code more readable.
`[in]`	hintValue	The actual value to be associated with the hintKey.

Definition at line 255 of file HeuristicChain.h.

References hints.

Referenced by UVSampleHeuristic::runHeuristic(), and NewUVHeuristic::runHeuristic().

int HeuristicChain::setReferenceEST ( const int estIdx ) [virtual]

Set the reference EST against which heuristics are to be run.

This method is invokes the corresponding method on all the heuristics that have been added to this chain. Setting the reference EST permits heuristics to build initial tables and other data structures for analyzing another EST (called via the shouldAnalyze) against the reference EST to determine if the heavy weight EST analyzer (d2 or CLU) must be run.

Parameters:

[in] estIdx The index of the reference EST.

Definition at line 88 of file HeuristicChain.cpp.

References chain, and NO_ERROR.

Referenced by TwoPassD2::setReferenceEST(), D2Zim::setReferenceEST(), and D2::setReferenceEST().

HeuristicChain * HeuristicChain::setupChain	(	const char *	heuristicStr,
		const int	refESTidx,
		const std::string &	outputFile
	)			`[static]`

Create the heuristics in the chain.

This method must be used to establish the chain of heuristics. This method is typically invoked from the main method. This method parses the names of the heuristic specified in the parameter heuristicStr and instantiates suitable heuristics via the HeuristicFactory.

Parameters:

`[in]`	heuristicStr	A string containing the list of heuristics to be created in this chain. This string is typically specified by the user as a command line parameter. If this parameter is `NULL`, then this method performs no specific action.
`[in]`	refESTidx	The index of the EST that is to be used to serve as the starting EST for clustering. In a Minimum-Spanning-Tree (MST) clustering scheme, this EST will be the root of the MST.
`[in]`	outputFile	The file to which the results of clustering are to be written.

Definition at line 133 of file HeuristicChain.cpp.

References addHeuristic(), ASSERT, HeuristicFactory::create(), and ptrInstance.

Referenced by main().

bool HeuristicChain::shouldAnalyze ( const int otherEST ) [inline]

Determine whether the analyzer should perform core (computationally intensive) analysis, according to this heuristic chain.

This method can be used to compare a given EST with the reference EST (set via the call to the setReferenceEST()) method.

Parameters:

[in] otherEST The index (zero based) of the EST with which the reference EST is to be compared.

Returns:: This method returns true if all of the heuristics say the EST pair should be analyzed, and false if any heuristic does not. (Conceivably a subclass could extend this class and use some sort of "consensus" among heuristics.)

Definition at line 199 of file HeuristicChain.h.

References chain.

Referenced by ESTAnalyzer::analyze().

void HeuristicChain::showArguments ( std::ostream & os ) [virtual]

Display valid command line arguments for heuristics in the chain.

This method simply calls the showArguments method on each heuristic in the chain.

Parameters:

[out] os The output stream to which the valid command line arguments must be written.

Definition at line 48 of file HeuristicChain.cpp.

References chain.

Referenced by showUsage().

Member Data Documentation

std::vector<Heuristic*> HeuristicChain::chain [private]

The vector containing a list of heuristics in the chain.

This vector contains the list of hueristics assocaited with this chain. Heuristics are added to the list via the addHeuristic() method. The heuristics are used by the shouldAnalyze() method.

Definition at line 339 of file HeuristicChain.h.

Referenced by addHeuristic(), getHeuristic(), initialize(), parseArguments(), printStats(), setReferenceEST(), shouldAnalyze(), showArguments(), and ~HeuristicChain().

StringIntMap HeuristicChain::hints [protected]

A hash map to store hints from heuristics.

This hash map is used to rapidly store and retrieve hints that are generated by various heuristics as they operate. These hints may be used by other heuristics in the chain or by heavy weight EST analyzers to further optimize their operations. Entries are added via the setHint method. Entries may be accessed via the getHint method.

Note:: Currently hints are restricted to be integers. Possibly at a later date this could be changed to store non-integer values as well.

Definition at line 322 of file HeuristicChain.h.

Referenced by getHint(), and setHint().

HeuristicChain * HeuristicChain::ptrInstance = NULL [static, private]

The pointer to the singleton instance of this class.

Again, this is made private so that only methods of this class can access it. The getHeuristicChain() method in this class must be used to obtain an instance of this class.

Definition at line 347 of file HeuristicChain.h.

Referenced by getHeuristicChain(), and setupChain().

The documentation for this class was generated from the following files:

HeuristicChain Class Reference

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation