pineforge::hpo::SearchSpace Class Reference

Ordered product of named dimensions with validation and finite-space codecs. More...

#include <pineforge/hpo/search_space.hpp>

Public Member Functions
	SearchSpace ()=default
	Constructs an empty search space whose finite cardinality is one.
	SearchSpace (std::vector< Dimension > dimensions)
	Constructs a search space in declaration order.
void	add (Dimension dimension)
	Appends a dimension while preserving declaration order.
const std::vector< Dimension > &	dimensions () const noexcept
	Returns all dimensions in declaration order.
const Dimension *	find (std::string_view name) const noexcept
	Returns the named dimension, or nullptr when it is not declared.
std::vector< ValidationIssue >	validate (const Candidate &candidate, bool reject_unknown=true) const
	Returns every missing, mistyped, off-grid, or optionally unknown parameter issue.
bool	is_valid (const Candidate &candidate, bool reject_unknown=true) const
	Returns whether validate() would produce no issues for the same arguments.
std::map< std::string, std::string >	serialize_candidate (const Candidate &candidate, bool reject_unknown=true) const
	Validates and serializes a candidate for the PineForge strategy ABI.
std::optional< std::uint64_t >	finite_cardinality () const
	Returns the exact Cartesian-product cardinality when every dimension is finite.
Candidate	candidate_at (std::uint64_t ordinal, std::uint64_t id=0) const
	Decodes a mixed-radix ordinal into its canonical finite-space candidate.
std::uint64_t	candidate_ordinal (const Candidate &candidate) const
	Encodes a canonical finite-space candidate into its mixed-radix ordinal.

Detailed Description

Ordered product of named dimensions with validation and finite-space codecs.

Dimension names are unique. Declaration order is significant for mixed-radix finite enumeration: the last declared dimension varies fastest.

Definition at line 157 of file search_space.hpp.

Constructor & Destructor Documentation

SearchSpace() [1/2]

pineforge::hpo::SearchSpace::SearchSpace ( )

default

Constructs an empty search space whose finite cardinality is one.

SearchSpace() [2/2]

pineforge::hpo::SearchSpace::SearchSpace ( std::vector< Dimension >  dimensions )

explicit

Constructs a search space in declaration order.

Exceptions

std::invalid_argument

if dimension names are duplicated.

Member Function Documentation

add()

void pineforge::hpo::SearchSpace::add

(

Dimension

dimension

)

Appends a dimension while preserving declaration order.

Exceptions

std::invalid_argument

if its name is already present.

candidate_at()

Candidate pineforge::hpo::SearchSpace::candidate_at	(	std::uint64_t	ordinal,
		std::uint64_t	id = 0
	)		const

Decodes a mixed-radix ordinal into its canonical finite-space candidate.

The last declared dimension varies fastest, matching GridSampler enumeration order.

Exceptions

std::invalid_argument	if the space is continuous.
std::out_of_range	if ordinal is outside the finite space.

candidate_ordinal()

std::uint64_t pineforge::hpo::SearchSpace::candidate_ordinal

(

const Candidate &

candidate

)

const

Encodes a canonical finite-space candidate into its mixed-radix ordinal.

Only canonical grid values are accepted, preserving a one-to-one mapping between ordinals and strategy-ABI parameter vectors.

Exceptions

std::invalid_argument

if the space is continuous or the candidate is not a complete canonical finite-grid assignment.

dimensions()

const std::vector< Dimension > & pineforge::hpo::SearchSpace::dimensions ( ) const

inlinenoexcept

Returns all dimensions in declaration order.

Definition at line 170 of file search_space.hpp.

Referenced by pineforge_hpo.neighbourhood.Study::rank(), pineforge_hpo.neighbourhood.Study::row_values(), and pineforge_hpo.neighbourhood.Study::sort_values().

find()

const Dimension * pineforge::hpo::SearchSpace::find ( std::string_view  name ) const

noexcept

Returns the named dimension, or nullptr when it is not declared.

finite_cardinality()

std::optional< std::uint64_t > pineforge::hpo::SearchSpace::finite_cardinality

(

)

const

Returns the exact Cartesian-product cardinality when every dimension is finite.

A varying real dimension without a step returns std::nullopt. Fixed real dimensions have cardinality one without requiring a step.

Exceptions

std::overflow_error	if a dimension or product exceeds std::uint64_t.
std::invalid_argument	if a stepped-real grid cannot map injectively to ABI values.

is_valid()

bool pineforge::hpo::SearchSpace::is_valid	(	const Candidate &	candidate,
		bool	reject_unknown = true
	)		const

Returns whether validate() would produce no issues for the same arguments.

serialize_candidate()

std::map< std::string, std::string > pineforge::hpo::SearchSpace::serialize_candidate	(	const Candidate &	candidate,
		bool	reject_unknown = true
	)		const

Validates and serializes a candidate for the PineForge strategy ABI.

Exceptions

std::invalid_argument

containing all validation failures when the candidate is invalid.

validate()

std::vector< ValidationIssue > pineforge::hpo::SearchSpace::validate	(	const Candidate &	candidate,
		bool	reject_unknown = true
	)		const

Returns every missing, mistyped, off-grid, or optionally unknown parameter issue.

---

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

• search_space.hpp