FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION > Class Template Reference

Implements hybrid selection step in sequential search type of methods. More...

#include <seq_step_hybrid.hpp>

Inheritance diagram for FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >:

Classes
class	SubsetCandidate
	Nested class to hold [Subset,criterion value] pair in the course of hybrid feature candidate evaluation in Sequential_Step_Hybrid. More...

Public Types
typedef Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >	parent
	the abstract Sequential_Step interface this class implements
typedef std::shared_ptr< FILTERCRITERION >	PFilterCriterion
	shared pointer to the (typically cheaper) criterion used to pre-filter candidates
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the main criterion the step optimizes
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a feature subset
typedef Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >	EVALUATORENGINE
	the candidate-evaluation interface driving the main-criterion phase
typedef std::shared_ptr< EVALUATORENGINE >	PEvaluatorEngine
Public Types inherited from FST::Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the criterion this step evaluates candidates against
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a feature subset
typedef std::shared_ptr< Result_Tracker< RETURNTYPE, SUBSET > >	PResultTracker
	shared pointer to the result tracker enabled via enable_result_tracking()

Public Member Functions
	Sequential_Step_Hybrid (const PFilterCriterion filtercrit, const DIMTYPE keep_perc, const DIMTYPE keep_max=1000, PEvaluatorEngine engine=PEvaluatorEngine())
void	set_prefiltering_limits (const DIMTYPE keep_perc, const DIMTYPE keep_max)
	reconfigures the pre-filtering percentage/cap (see the constructor parameters)
DIMTYPE	get_prefiltering_perc () const
	the currently configured keep_perc
DIMTYPE	get_prefiltering_max () const
	the currently configured keep_max
bool	evaluate_candidates (RETURNTYPE &result, const PSubset sub, const PCriterion crit, const DIMTYPE _generalization_level=1, std::ostream &os=std::cout) override
	chooses among subsets offered by sub->get*CandidateSubset()
virtual std::ostream &	print (std::ostream &os) const override
	writes a human-readable identification of the step, its prefiltering settings, filter criterion and (if enabled) result tracker
Public Member Functions inherited from FST::Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
void	enable_result_tracking (PResultTracker tracker)
	assigns a result tracker to this step, i.e., enables logging of all evaluated candidate subsets for future reuse (re-evaluation, etc.)
void	disable_result_tracking ()
	detaches any result tracker (result_tracker_active() then returns false)
bool	result_tracker_active () const
	true if a result tracker was assigned via enable_result_tracking() and not since disabled
void	set_output_detail (OutputDetail detail)
	sets the amount of information that is logged to output stream throughout the course of search
OutputDetail	get_output_detail () const
	the currently configured output detail level
bool	output_normal () const
	true unless output detail is SILENT
bool	output_detailed () const
	true only at the DETAILED output level

Protected Types
typedef std::list< SubsetCandidate >	CANDIDATELIST
	sorted (by filter criterion value, descending) list of surviving pre-filter candidates

Protected Member Functions
bool	filter_candidates (const PSubset sub, const DIMTYPE _generalization_level, std::ostream &os)
	evaluates every offered candidate with _filtercrit and keeps the top _listsize in _filterlist, sorted descending by filtercrit value (ties broken toward the smaller subset); always runs on the calling (master) thread
bool	test_candidate (const PSubset sub)
	evaluates one candidate with _filtercrit and inserts it into _filterlist in sorted position, trimming the list back to _listsize

Protected Attributes
PEvaluatorEngine	_engine
	candidate-evaluation engine driving the main-criterion phase
PFilterCriterion	_filtercrit
	the pre-filtering criterion supplied to the constructor
DIMTYPE	_keep_perc
	filter out (100-_keep_perc) % of candidate subsets
DIMTYPE	_keep_max
	when filtering keep maximally _keep_max candidate subsets (restriction on CANDIDATELIST size)
DIMTYPE	_listsize
	target size of _filterlist, recomputed from _keep_perc/_keep_max at each filter_candidates() call and floored to 1, so the shortlist is never empty
CANDIDATELIST	_filterlist
	the surviving pre-filter candidates, sorted descending by filter criterion value (lazy allocation)
CANDIDATELIST::iterator	iter
	scratch iterator reused by test_candidate()/filter_candidates()/evaluate_candidates() – not reentrant, matches the single-threaded pre-filter stage
Protected Attributes inherited from FST::Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
PResultTracker	_tracker
	the assigned result tracker, or null (see enable_result_tracking()/result_tracker_active())
OutputDetail	_detail
	the output detail level set via set_output_detail(); read by output_normal()/output_detailed()

Private Attributes
bool	track
	cached result_tracker_active() for the current evaluate_candidates() call

Detailed Description

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION, class FILTERCRITERION>
class FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >

Implements hybrid selection step in sequential search type of methods.

A "hybrid" step pre-filters the candidates with a second, presumably much cheaper criterion, so that the main (typically wrapper) criterion has to be evaluated on a small shortlist only. Every candidate offered by the working subset is first evaluated with filtercrit; the best keep_perc percent of them (at most keep_max, see set_prefiltering_limits()) are then evaluated with the main criterion, and the best of those is the step's result.

The two end points of keep_perc:

• keep_perc==100 keeps every candidate, so the main criterion sees the same candidate set as Sequential_Step_Straight and the step returns the same best VALUE - but the candidates reach the main criterion in filter order rather than in feature order, so when several candidates tie on the main criterion a different one may be chosen (the first in filter order wins); plus the cost of the extra filter pass.
• keep_perc==0 shortens the shortlist to a single candidate, the best one according to filtercrit. Note that the main criterion is still evaluated - on that one candidate - and ITS value is what the step returns; what keep_perc==0 bypasses is the SELECTION by the main criterion, not the main criterion itself. The returned value therefore stays comparable with the values the search sees in other steps.

Note

Like Sequential_Step_Straight this class serves both the sequential and the threaded execution model: the main-criterion phase over the prefiltered candidate list runs through the injected Candidate_Evaluator (default: sequential in-line evaluation; inject Candidate_Evaluator_Threaded for a thread-pooled main phase). The prefilter stage is a deterministic pre-sort and always stays on the calling (master) thread. Results are identical for any thread count: the engine fires per-result callbacks (tracker feed) in candidate order and breaks best-value ties by earliest candidate.

Member Typedef Documentation

PEvaluatorEngine

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION, class FILTERCRITERION>

typedef std::shared_ptr<EVALUATORENGINE> FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >::PEvaluatorEngine

shared pointer to an EVALUATORENGINE, as passed to the constructor

Constructor & Destructor Documentation

Sequential_Step_Hybrid()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION, class FILTERCRITERION>

FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >::Sequential_Step_Hybrid ( const PFilterCriterion filtercrit, const DIMTYPE keep_perc, const DIMTYPE keep_max = 1000, PEvaluatorEngine engine = PEvaluatorEngine() )

inline

Parameters

filtercrit	the pre-filtering criterion, evaluated on every offered candidate on the calling (master) thread
keep_perc	percentage of candidates (by filtercrit ranking) kept for the main-criterion phase; 100 bypasses pre-filtering, 0 shortlists one candidate only (see the class documentation). The shortlist never shrinks below one candidate, so the main criterion is always evaluated at least once
keep_max	hard cap on the number of candidates kept for the main-criterion phase, regardless of keep_perc (must be >0)
engine	evaluation-strategy engine for the main-criterion phase; defaults to a fresh Candidate_Evaluator_Sequential (inject Candidate_Evaluator_Threaded for a thread-pooled main phase)

Member Function Documentation

evaluate_candidates()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION, class FILTERCRITERION>

bool FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >::evaluate_candidates ( RETURNTYPE & result, const PSubset sub, const PCriterion crit, const DIMTYPE _generalization_level = 1, std::ostream & os = std::cout )

inlineoverridevirtual

chooses among subsets offered by sub->get*CandidateSubset()

Implements FST::Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

print()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION, class FILTERCRITERION>

std::ostream & FST::Sequential_Step_Hybrid< RETURNTYPE, DIMTYPE, SUBSET, CRITERION, FILTERCRITERION >::print ( std::ostream & os ) const

overridevirtual

writes a human-readable identification of the step, its prefiltering settings, filter criterion and (if enabled) result tracker

Reimplemented from FST::Sequential_Step< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

---

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

• /Users/psms/dev/devtest1/_src_search/seq_step_hybrid.hpp