utils#

Functions

default_hyperparameter_parser(aq_kwargs, hps)

Default dummy hyperparameter parser

Classes

`AcquisitionConfig`(name, implementation, ...)	Configuration for an acquisition function
`AcquisitionRegistry`(BUILTIN_CONFIGS)	Singleton registry for acquisition function configurations
`ParserContext`	Context dictionary for acquisition function hyperparameter parsing.

class obsidian.acquisition.utils.AcquisitionConfig(name: str, implementation: type, hyperparameter_defaults: dict[str, dict[str, ~typing.Any]] = <factory>, hyperparameter_parser: ~typing.Callable[[dict[str, ~typing.Any], dict[str, ~typing.Any], ~typing.Any], dict[str, ~typing.Any]] = <function default_hyperparameter_parser>, modalities: list[str] = <factory>, task_types: list[str] = <factory>, is_external: bool = False, output_constraints: bool = True)[source]#

Bases: object

Configuration for an acquisition function

get_default_hyperparameters() → dict[str, Any][source]#: Get default hyperparameter values

hyperparameter_parser(hps: dict[str, Any], context: ParserContext | None = None) → dict[str, Any]#

Default dummy hyperparameter parser

Parameters:

aq_kwargs (dict[str, Any]) – Acquisition function keyword arguments partially processed from the optimizer, including all default arguments of the acquisition function
hps (dict[str, Any]) – Hyperparameters passed in when suggest is called
context (ParserContext | None, optional) – Parser context, a typed dictionary, currently contains
None. (contextual information for hyperparameter parsing. Check its docstring for details. Defaults to)

Returns:

Parsed acquisition function keyword arguments

Return type:

dict[str, Any]

instantiate(**kwargs) → Any[source]#: Instantiate the acquisition function with given parameters

merge_with_defaults(hps: dict[str, Any]) → dict[str, Any][source]#: Merge provided hyperparameters with defaults. This method does not perform validation or parsing, so users should ensure that the provided hyperparameters are valid and all required hyperparameters are included.

parse_hyperparameters(aq_kwargs: dict[str, Any], hps: dict[str, Any], context: ParserContext) → dict[str, Any][source]#: Apply hyperparameter parser for this acquisition function

class obsidian.acquisition.utils.AcquisitionRegistry(BUILTIN_CONFIGS: dict[str, dict[str, Any]])[source]#

Bases: object

Singleton registry for acquisition function configurations

property aq_class_dict: dict[str, type | None]#: Get dictionary of acquisition function implementations

property aq_hp_defaults: dict[str, dict[str, Any]]#: Get dictionary of acquisition function hyperparameter defaults

get_config(name: str) → AcquisitionConfig[source]#: Get configuration for an acquisition function

get_default_hyperparameters(name: str) → dict[str, Any][source]#: Get default hyperparameters for an acquisition function

get_valid_hyperparameters(name: str) → set[str][source]#: Get valid hyperparameter names for an acquisition function

instantiate_acquisition(name: str, **kwargs) → Any[source]#: Instantiate an acquisition function with parameters

parse_hyperparameters(name: str, aq_kwargs: dict[str, Any], hps: dict[str, Any], context: ParserContext) → dict[str, Any][source]#: Parse hyperparameters for a specific acquisition function

register_acquisition_function(name: str, implementation: Type | None, hp_defaults: dict | None = None, is_optimization: bool = False, is_characterization: bool = False, is_single_target: bool = False, is_multi_target: bool = False, set_as_default: bool = False, overloading: bool = False, reuse_parser: bool = False, parser: Callable | None = None, output_constraints: bool = True)[source]#

Parameters:

name (str) – Name of the acquisition function.
implementation (callable or None) – The function implementation. If None, no implementation stored.
hp_defaults (dict) – Optional hyperparameter defaults. If None and implementation provided, attempt to infer.
task_type (TaskType) – Task type this acquisition is intended for (optimization/characterization).
is_single_target (bool) – Whether this acquisition function is for single-target optimization.
is_multi_target (bool) – Whether this acquisition function is for multi-target optimization.
set_as_default (bool) – Whether to set this acquisition function as default for its modality(s).
overloading (bool) – Whether to allow overloading an existing acquisition function with the same name.
reuse_parser (bool) – Whether to use an internal hyperparameter parser from an existing config.
parser (Callable | None) – A function to parse arguments for the function.
output_constraints (bool) – Whether the acquisition function honors output constraints. Defaults to True. Set False for acquisitions that don’t accept/forward constraints= (e.g. UCB, Mean, characterization acqs).

reset(BUILTIN_CONFIGS: dict[str, dict[str, Any]])[source]#: Reset the registry to default state with only built-in functions

property valid_charact_aqs: dict[str, set[str]]#: Backward compatibility for valid_aqs

property valid_opt_aqs: dict[str, set[str]]#: Backward compatibility for valid_aqs

validate_hyperparameters(task_type: TaskType, o_dim: int, aq_name: str, hps: dict[str, Any], aq_kwargs: dict[str, Any]) → tuple[dict, dict][source]#

Validates acquisition function and prepares base arguments.

Parameters:

o_dim – Output dimensionality
acquisition – Acquisition function name (str) or {name: hyperparameters} dict
aq_kwargs – Base keyword arguments for the acquisition function

Returns:

tuple of (aq_name, aq_hps)

class obsidian.acquisition.utils.ParserContext[source]#

Bases: TypedDict

Context dictionary for acquisition function hyperparameter parsing.

This typed dictionary provides contextual information to hyperparameter parsers, allowing an unified interface for parsing across different acquisition functions.

f_t#

Transformed objective values for all observed data. Shape: (n_obs, n_targets). These are the transformed responses (via f_transform) for the target variables.

Type:: torch.Tensor

X_baseline#

Baseline input tensor containing all observed and pending points. Shape: (n_baseline, n_dim). Combines training data (X_train) and any pending evaluations (X_pending). Used by: - Noisy acquisition functions (NEI, NEHVI) for computing fantasies - Space-filling functions to avoid suggesting near-observed points - Objective transformations requiring reference to observed data

Type:: torch.Tensor

m_batch#

Number of candidates to propose in this batch. Used by acquisition functions that need to know batch size.

Type:: int

n_dim#

Dimensionality of the parameter space. Used for space-filling and other geometry-aware acquisition functions.

Type:: int

target#

List of Target objects describing the optimization objectives. Contains information about aim (max/min), transformation, tracking status, etc.

Type:: list[obsidian.parameters.targets.Target]

objective#

BoTorch MCAcquisitionObjective for transforming posterior samples. Used to scalarize multi-output models or apply custom transformations.

Type:: botorch.acquisition.objective.MCAcquisitionObjective | None

n_obs#

Number of training observations (data-state fingerprint). Used by randomized acquisition functions to derive a per-iteration random seed that is deterministic in the current data, so the random draw varies across iterations but is idempotent within a single suggest() call.

Type:: int

obsidian.acquisition.utils.default_hyperparameter_parser(aq_kwargs: dict[str, Any], hps: dict[str, Any], context: ParserContext | None = None) → dict[str, Any][source]#

Default dummy hyperparameter parser

Parameters:

aq_kwargs (dict[str, Any]) – Acquisition function keyword arguments partially processed from the optimizer, including all default arguments of the acquisition function
hps (dict[str, Any]) – Hyperparameters passed in when suggest is called
context (ParserContext | None, optional) – Parser context, a typed dictionary, currently contains
None. (contextual information for hyperparameter parsing. Check its docstring for details. Defaults to)

Returns:

Parsed acquisition function keyword arguments

Return type:

dict[str, Any]