Abstract candidate-evaluation strategy (sequential-inline vs. thread-pooled). More...

#include <candidate_evaluator.hpp>

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

Public Types
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the criterion this engine evaluates candidates against
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a candidate feature subset
typedef std::shared_ptr< Result_Tracker< RETURNTYPE, SUBSET > >	PResultTracker
typedef std::function< bool(SUBSET &)>	Generator
	fills sub with the next candidate, returns false when no candidate remains (in the threaded implementation calls are serialized under a lock)
typedef std::function< void(const RETURNTYPE, const PSubset &, const DIMTYPE)>	ResultCallback
	fired once per evaluated batch candidate: (criterion value, candidate, feature tag as passed to add_candidate)
typedef std::function< void(const int, const unsigned long long, const RETURNTYPE, const PSubset &)>	BestCallback
typedef std::function< bool(const RETURNTYPE, const PSubset &, const RETURNTYPE, const PSubset &)>	BetterPredicate
	returns true if (value,subset) is better than (best value,best subset) - encodes per-search tie-breaking for evaluate_stream()

Public Member Functions
virtual unsigned int	get_max_threads () const =0
	1 in the sequential implementation
virtual bool	is_threaded () const =0
	true for the threaded engine (any --threads value), false for the sequential one – distinguishes the engine kind, not whether get_max_threads()>1
virtual void	initialize (const PCriterion &crit, const DIMTYPE max_candidates, ResultCallback on_result=ResultCallback())=0
	starts a new batch; max_candidates must bound the number of add_candidate() calls to follow
virtual bool	add_candidate (const PSubset &sub, const DIMTYPE feature=0)=0
	adds one candidate to the current batch; `sub` is copied, `feature` is an opaque tag handed back by the callbacks. Returns false on evaluation failure (sequential) or when more than the announced max_candidates candidates are added (threaded)
virtual bool	collect ()=0
	completes the batch (threaded: waits for the workers, fires the pending per-result callbacks in add-order); returns false if no candidate was successfully evaluated. Calling it twice on the same batch is harmless
virtual bool	getBestResult (RETURNTYPE &result, PSubset &sub, DIMTYPE &feature)=0
	completes the batch first, then hands out its best candidate (`sub` is set to the engine's own subset object, its contents are not copied and are overwritten by the following batch - copy them if they must outlive it); earliest added wins ties; false if the batch evaluated nothing or an evaluation failed
virtual bool	evaluate_stream (Generator generator, const PCriterion &crit, const PResultTracker tracker, BetterPredicate better, BestCallback on_best, RETURNTYPE &result, const PSubset bestsub)=0
	Evaluates candidates produced by `generator` until it reports exhaustion, keeping the best one.
virtual std::ostream &	print (std::ostream &os) const
	writes a human-readable identification of the engine; base default writes nothing
virtual void	invalidate_clones ()
	Drops any cached per-worker criterion clones, so that the next batch or stream re-clones from the criterion it is handed.

Detailed Description

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

Abstract candidate-evaluation strategy (sequential-inline vs. thread-pooled).

Search algorithms delegate candidate subset evaluation to an injected implementation of this interface, so that one algorithm body serves both the sequential and the threaded execution model. Which one is in effect is a property of the engine object passed to the search's constructor, not of the search class.

Two modes of use:

batch: initialize() once per candidate group, add_candidate() per candidate, then collect() or getBestResult(). The optional per-result callback fires exactly once per candidate with its criterion value: the sequential implementation fires it synchronously inside add_candidate(), so evaluation stays interleaved with the caller's own output, the threaded implementation fires it for all candidates in add-order while completing the batch. Ties on the best value are broken in favor of the earliest added candidate in both implementations.
streaming: evaluate_stream() pulls candidates from a generator until it is exhausted - for searches whose candidate count is too large to materialize (exhaustive, Monte Carlo). Result tracking - including per-worker tracker clones and their final join in the threaded case - is handled inside the implementation.

Warning: The threaded implementation clones the supplied criterion once per worker and re-uses the clones as long as the same criterion object is supplied. The clones' state is not re-synchronized with the original criterion afterwards, so an engine must not be carried across a change of the criterion's context (typically a change of the data split) - see the class documentation of Candidate_Evaluator_Threaded.

Member Typedef Documentation

◆ BestCallback

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

typedef std::function<void(const int, const unsigned long long, const RETURNTYPE, const PSubset&)> FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::BestCallback

fired when a best-so-far improves during evaluate_stream(): (worker index, or -1 if fired from the master/sequential replay; 0-based ordinal of the candidate in GENERATION order; criterion value; candidate). Both engines fire this on the master thread in generation order, with index -1 NOTE the ordinal is unsigned long long, NOT unsigned long: on LLP64 platforms (Windows) unsigned long is 32 bits and a long streaming search (Monte Carlo with a large trial count) would wrap it

◆ PResultTracker

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

typedef std::shared_ptr<Result_Tracker<RETURNTYPE,SUBSET> > FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::PResultTracker

shared pointer to the result tracker fed during evaluate_stream()

Member Function Documentation

◆ add_candidate()

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

virtual bool FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::add_candidate	(	const PSubset &	sub,
		const DIMTYPE	feature = 0 )

pure virtual

adds one candidate to the current batch; sub is copied, feature is an opaque tag handed back by the callbacks. Returns false on evaluation failure (sequential) or when more than the announced max_candidates candidates are added (threaded)

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ collect()

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

virtual bool FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::collect ( )

pure virtual

completes the batch (threaded: waits for the workers, fires the pending per-result callbacks in add-order); returns false if no candidate was successfully evaluated. Calling it twice on the same batch is harmless

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ evaluate_stream()

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

virtual bool FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::evaluate_stream	(	Generator	generator,
		const PCriterion &	crit,
		const PResultTracker	tracker,
		BetterPredicate	better,
		BestCallback	on_best,
		RETURNTYPE &	result,
		const PSubset	bestsub )

pure virtual

Evaluates candidates produced by generator until it reports exhaustion, keeping the best one.

Parameters

generator	called to fill the next candidate; false from it ends the stream
crit	the criterion to evaluate with; must be initialize()d
tracker	result tracker to log every evaluated candidate into, or null for no tracking
better	the search's own "is strictly better" predicate, deciding both improvement and tie-breaking
on_best	fired on each improvement; may be empty
result	receives the best criterion value; meaningful only if the call returns true
bestsub	non-null subset dimensioned for the full feature set, receiving the best candidate

Returns: false if no candidate was evaluated successfully (empty stream or criterion failure)

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ get_max_threads()

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

virtual unsigned int FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::get_max_threads ( ) const

pure virtual

1 in the sequential implementation

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ getBestResult()

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

virtual bool FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::getBestResult	(	RETURNTYPE &	result,
		PSubset &	sub,
		DIMTYPE &	feature )

pure virtual

completes the batch first, then hands out its best candidate (sub is set to the engine's own subset object, its contents are not copied and are overwritten by the following batch - copy them if they must outlive it); earliest added wins ties; false if the batch evaluated nothing or an evaluation failed

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ initialize()

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

virtual void FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::initialize	(	const PCriterion &	crit,
		const DIMTYPE	max_candidates,
		ResultCallback	on_result = ResultCallback() )

pure virtual

starts a new batch; max_candidates must bound the number of add_candidate() calls to follow

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ invalidate_clones()

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

virtual void FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::invalidate_clones ( )

inlinevirtual

Drops any cached per-worker criterion clones, so that the next batch or stream re-clones from the criterion it is handed.

The threaded implementation clones the criterion once per worker and keeps the clones across batches while the same criterion object is supplied (see the warning above). Call this whenever the ORIGINAL criterion's evaluation context has changed behind the clones' back - its data accessor moved to another data split (the next trial of a repeated-trials protocol), a filter model was re-estimated on new data, a wrapper's classifier or regressor was re-tuned - and the same criterion object is about to be evaluated again. Without it the workers keep evaluating in the old context: a trial protocol would repeat its first trial in every trial. The sequential implementation evaluates on the original and has nothing to drop, hence the empty default. Must not be called while a batch is open.

Reimplemented in FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ is_threaded()

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

virtual bool FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::is_threaded ( ) const

pure virtual

true for the threaded engine (any --threads value), false for the sequential one – distinguishes the engine kind, not whether get_max_threads()>1

Implemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ print()

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

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

inlinevirtual

writes a human-readable identification of the engine; base default writes nothing

Reimplemented in FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >, and FST::Candidate_Evaluator_Threaded< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

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

/Users/psms/dev/devtest1/_src_search/candidate_evaluator.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ BestCallback

◆ PResultTracker

Member Function Documentation

◆ add_candidate()

◆ collect()

◆ evaluate_stream()

◆ get_max_threads()

◆ getBestResult()

◆ initialize()

◆ invalidate_clones()

◆ is_threaded()

◆ print()