SearchSpace

Manages the variable space for Bayesian optimization, including real, integer, categorical, and discrete variables.

---

Class Reference

alchemist_core.data.search_space.SearchSpace()

Class for storing and managing the search space in a consistent way across backends. Provides methods for conversions to different formats required by different backends.

add_variable(name, var_type, **kwargs)

Add a variable to the search space.

Parameters:

Name	Type	Description	Default
name	str	Variable name	required
var_type	str	"real", "integer", "categorical", "discrete", or "context"	required
**kwargs		Additional parameters: - real/integer: min, max - categorical: values (list of strings) - discrete: allowed_values (list of numbers, at least 2, no duplicates) - context: no additional parameters required	{}

from_dict(data)

Load search space from a list of dictionaries (used with JSON/CSV loading).

from_skopt(dimensions)

Load search space from skopt dimensions.

to_dict()

Convert search space to a list of dictionaries.

to_skopt()

Get skopt dimensions for scikit-learn.

to_ax_space()

Convert to Ax parameter format.

to_botorch_bounds()

Create bounds in BoTorch format.

For discrete variables, bounds span [min(allowed_values), max(allowed_values)]. The acquisition optimizer uses these as the continuous relaxation bounds; the discrete constraint is enforced separately via optimize_acqf_mixed.

get_variable_names()

Get all variable names, tunable variables first, then context variables.

get_tunable_variable_names()

Get names of all non-context (tunable) variables in registration order.

get_context_variable_names()

Get names of all context (observed, non-optimized) variables in registration order.

get_categorical_variables()

Get list of categorical variable names.

get_integer_variables()

Get list of integer variable names.

get_discrete_variables()

Get list of discrete variable names.

add_derived_variable(name, func, input_cols, description='')

Register a derived (non-tunable) variable.

Derived variables are deterministic functions of existing input variables. They are appended to the GP feature matrix at train and predict time, but the acquisition function never suggests values for them.

Parameters:

Name	Type	Description	Default
name	str	Column name for the derived feature.	required
func		Callable with signature func(row: dict) -> float. Pass None when restoring a stub from a saved session.	required
input_cols	List[str]	Base variable names this feature depends on (for documentation; the full row dict is still passed to func).	required
description	str	Human-readable description stored in session JSON.	''

Raises:

Type	Description
ValueError	If name conflicts with an existing tunable variable or an already-registered derived variable.

register_derived_variable(name, func)

Re-attach a callable to a derived variable stub after session load.

Parameters:

Name	Type	Description	Default
name	str	Name of the derived variable to update.	required
func		Callable with signature func(row: dict) -> float.	required

Raises:

Type	Description
ValueError	If no derived variable with the given name exists.

add_derived_variable_stub(name, input_cols, description='')

Restore a derived variable stub from session JSON (func=None).

has_derived_variables()

Return True if any derived variables are registered.

get_derived_variable_names()

Return list of derived variable names (in registration order).

derived_variables_to_dict()

Return serializable metadata for all derived variables (no func).

save_to_json(filepath)

Save search space to a JSON file.

load_from_json(filepath)

Load search space from a JSON file.

from_json(filepath) classmethod

Class method to create a SearchSpace from a JSON file.

add_constraint(constraint_type, coefficients, rhs, name=None)

Add linear input constraint.

Parameters:

Name	Type	Description	Default
constraint_type	str	'inequality' (sum(coeff_i * x_i) <= rhs) or 'equality' (sum(coeff_i * x_i) == rhs)	required
coefficients	Dict[str, float]	{variable_name: coefficient} mapping	required
rhs	float	right-hand side value	required
name	Optional[str]	optional human-readable name	None

get_constraints()

Return list of constraint dicts.

to_botorch_constraints(feature_names)

Convert to BoTorch format for optimize_acqf.

Each constraint is a tuple (indices_tensor, coefficients_tensor, rhs_float). BoTorch convention: inequality means sum(coeff_i * x_i) - rhs <= 0.

Parameters:

Name	Type	Description	Default
feature_names	List[str]	ordered list of feature column names matching model input	required

Returns:

Type	Description
Optional[List]	(inequality_constraints, equality_constraints) — each is a list of tuples
Optional[List]	or None if no constraints of that type exist.

---

See Also

• OptimizationSession - Uses SearchSpace for variable management