pineforge::hpo::TpeSampler Class Reference

Independent, single-objective Tree-structured Parzen Estimator sampler. More...

#include <pineforge/hpo/sampler.hpp>

Inheritance diagram for pineforge::hpo::TpeSampler:

Public Member Functions
	TpeSampler (SearchSpace space, std::uint64_t seed, ObjectiveDirection direction=ObjectiveDirection::Maximize, std::uint64_t max_candidates=0, TpeSamplerConfig config={}, CandidatePolicy candidate_policy=CandidatePolicy::SamplerDefault)
	Constructs a native TPE sampler; max_candidates == 0 means unbounded generation.
	~TpeSampler () override
	TpeSampler (const TpeSampler &)=delete
TpeSampler &	operator= (const TpeSampler &)=delete
	TpeSampler (TpeSampler &&) noexcept
TpeSampler &	operator= (TpeSampler &&) noexcept
std::optional< Candidate >	next () override
	Alias for ask().
std::optional< Candidate >	ask ()
	Atomically issues and reserves the next candidate.
void	tell (std::uint64_t candidate_id, double objective_value)
	Completes an outstanding candidate with its original finite objective value.
void	abandon (std::uint64_t candidate_id)
	Removes an outstanding failed or pruned candidate without training TPE.
bool	warm_start (const std::vector< WarmStartObservation > &observations, std::uint64_t replay_batch_size=0, const std::string &sampler_state={})
	Imports attempted candidates into a pristine sampler without consuming its new budget.
bool	warm_start (std::shared_ptr< const WarmStartSource > source, std::uint64_t replay_batch_size=0, const std::string &sampler_state={})
	Restores exact ordered observations while retaining the immutable source by reference.
std::string	sampler_state () const
	Returns a versioned, checksummed checkpoint bound to the configuration and observations.
void	reset () override
	Restores the seeded initial state and clears finite-space reservations.
std::uint64_t	generated () const noexcept override
	Returns the number of candidates issued since construction or reset.
std::uint64_t	completed () const noexcept
	Returns the number of candidates completed through tell().
std::uint64_t	outstanding () const noexcept
	Returns the number of candidates awaiting tell() or abandon().
std::size_t	retained_observations () const
	Returns the bounded number of completed observations kept for density estimation.
std::uint64_t	duplicate_proposals_skipped () const noexcept
	Returns internal duplicate proposals rejected by a finite policy.
std::uint64_t	seed () const noexcept
	Returns the reproducibility seed.
ObjectiveDirection	direction () const noexcept
	Returns the configured optimization direction.
const TpeSamplerConfig &	config () const noexcept
	Returns the immutable TPE tuning configuration.
CandidatePolicy	candidate_policy () const noexcept
	Returns the configured uniqueness/coverage policy.
Public Member Functions inherited from pineforge::hpo::Sampler
virtual	~Sampler ()=default

Detailed Description

Independent, single-objective Tree-structured Parzen Estimator sampler.

Numeric dimensions use bounded Gaussian mixtures in normalized coordinates; integer and stepped-real dimensions decode onto legal grids. Boolean and categorical dimensions use smoothed weighted histograms. Fitted candidate generation samples from the good model l(x) and retains the proposal maximizing l(x) / g(x).

next() is an alias for ask(). Every returned candidate remains outstanding until tell() or abandon() receives its ID. Public methods are thread-safe, although deterministic replay requires the same ordering of ask/tell/abandon calls.

By default, proposals use the exact full-history estimator for the entire study. An explicit history_switch opts into bounded models after that many completed observations. Thereafter the sampler retains at most gamma_cap elite observations and 64 recent non-elite observations plus bad_reservoir_size older non-elites from a separate seeded reservoir. Outstanding or abandoned proposals never advance the switch. Numeric density tables, elite-change good-model refits, and 32-completion bad-model epochs bound work independently of study length.

Definition at line 181 of file sampler.hpp.

Constructor & Destructor Documentation

TpeSampler() [1/3]

pineforge::hpo::TpeSampler::TpeSampler	(	SearchSpace	space,
		std::uint64_t	seed,
		ObjectiveDirection	direction = ObjectiveDirection::Maximize,
		std::uint64_t	max_candidates = 0,
		TpeSamplerConfig	config = {},
		CandidatePolicy	candidate_policy = CandidatePolicy::SamplerDefault
	)

Constructs a native TPE sampler; max_candidates == 0 means unbounded generation.

Finite policies validate exact cardinality and budget compatibility at construction.

Exceptions

std::invalid_argument

for invalid configuration, direction, policy, or finite policy/budget combination.

~TpeSampler()

pineforge::hpo::TpeSampler::~TpeSampler ( )

override

TpeSampler() [2/3]

pineforge::hpo::TpeSampler::TpeSampler ( const TpeSampler &  )

delete

TpeSampler() [3/3]

pineforge::hpo::TpeSampler::TpeSampler ( TpeSampler &&  )

noexcept

Member Function Documentation

abandon()

void pineforge::hpo::TpeSampler::abandon

(

std::uint64_t

candidate_id

)

Removes an outstanding failed or pruned candidate without training TPE.

Exceptions

std::invalid_argument

when candidate_id is not outstanding.

ask()

std::optional< Candidate > pineforge::hpo::TpeSampler::ask

(

)

Atomically issues and reserves the next candidate.

Returns std::nullopt at the configured budget or exact finite-space exhaustion.

candidate_policy()

CandidatePolicy pineforge::hpo::TpeSampler::candidate_policy ( ) const

inlinenoexcept

Returns the configured uniqueness/coverage policy.

Definition at line 263 of file sampler.hpp.

completed()

std::uint64_t pineforge::hpo::TpeSampler::completed ( ) const

noexcept

Returns the number of candidates completed through tell().

config()

const TpeSamplerConfig & pineforge::hpo::TpeSampler::config ( ) const

inlinenoexcept

Returns the immutable TPE tuning configuration.

Definition at line 261 of file sampler.hpp.

direction()

ObjectiveDirection pineforge::hpo::TpeSampler::direction ( ) const

inlinenoexcept

Returns the configured optimization direction.

Definition at line 259 of file sampler.hpp.

Referenced by pineforge_hpo.neighbourhood.Study::better(), and pineforge_hpo.neighbourhood.Study::gap().

duplicate_proposals_skipped()

std::uint64_t pineforge::hpo::TpeSampler::duplicate_proposals_skipped ( ) const

noexcept

Returns internal duplicate proposals rejected by a finite policy.

generated()

std::uint64_t pineforge::hpo::TpeSampler::generated ( ) const

overridevirtualnoexcept

Returns the number of candidates issued since construction or reset.

Implements pineforge::hpo::Sampler.

next()

std::optional< Candidate > pineforge::hpo::TpeSampler::next ( )

overridevirtual

Alias for ask().

Implements pineforge::hpo::Sampler.

operator=() [1/2]

TpeSampler & pineforge::hpo::TpeSampler::operator= ( const TpeSampler &  )

delete

operator=() [2/2]

TpeSampler & pineforge::hpo::TpeSampler::operator= ( TpeSampler &&  )

noexcept

outstanding()

std::uint64_t pineforge::hpo::TpeSampler::outstanding ( ) const

noexcept

Returns the number of candidates awaiting tell() or abandon().

reset()

void pineforge::hpo::TpeSampler::reset ( )

overridevirtual

Restores the seeded initial state and clears finite-space reservations.

Exceptions

std::logic_error

while a candidate is outstanding, preventing a late pre-reset result from being accepted after candidate IDs are reused.

Implements pineforge::hpo::Sampler.

retained_observations()

std::size_t pineforge::hpo::TpeSampler::retained_observations

(

)

const

Returns the bounded number of completed observations kept for density estimation.

sampler_state()

std::string pineforge::hpo::TpeSampler::sampler_state

(

)

const

Returns a versioned, checksummed checkpoint bound to the configuration and observations.

No candidate may be outstanding. Preserve this alongside the complete attempted history. Numeric caches retain their fitting observation IDs, not redundant kernel arrays.

Exceptions

std::logic_error

if a candidate is outstanding.

seed()

std::uint64_t pineforge::hpo::TpeSampler::seed ( ) const

inlinenoexcept

Returns the reproducibility seed.

Definition at line 257 of file sampler.hpp.

tell()

void pineforge::hpo::TpeSampler::tell	(	std::uint64_t	candidate_id,
		double	objective_value
	)

Completes an outstanding candidate with its original finite objective value.

Exceptions

std::invalid_argument

for a non-finite value or non-outstanding ID.

warm_start() [1/2]

bool pineforge::hpo::TpeSampler::warm_start	(	const std::vector< WarmStartObservation > &	observations,
		std::uint64_t	replay_batch_size = 0,
		const std::string &	sampler_state = {}
	)

Imports attempted candidates into a pristine sampler without consuming its new budget.

Feasible objectives train the same estimator as tell(); other attempts only reserve points. IDs continue after the largest imported ID. No historical proposals are generated. A matching sampler_state() checkpoint restores the exact RNG/model state and returns true. Without one, history is rebuilt with continuation_seed() and returns false. The retained replay_batch_size argument is ignored; legacy histories cannot recover rejection draws.

Exceptions

std::invalid_argument	for invalid candidates, IDs, or non-finite objectives.
std::logic_error	if the sampler is not pristine.

warm_start() [2/2]

bool pineforge::hpo::TpeSampler::warm_start	(	std::shared_ptr< const WarmStartSource >	source,
		std::uint64_t	replay_batch_size = 0,
		const std::string &	sampler_state = {}
	)

Restores exact ordered observations while retaining the immutable source by reference.

Import consumes every row; checkpoint restoration matches the vector overload.

---

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

• sampler.hpp