milia.core.config.space#

Hyperparameter search spaces for Optuna.

SearchSpace validates a search-space definition and turns it into Optuna suggestions. A tuple (low, high) is a numeric range; a list is a categorical choice. Optuna is only needed when a trial is actually sampled, so the core install does not depend on it.

Functions

hashable(item)

Recursively convert lists to tuples so the values can be put in a set.

logscale(low, high)

Whether a numeric range is wide enough to sample on a log scale.

Classes

SearchSpace(**extra_data)

A validated hyperparameter search space.

milia.core.config.space.hashable(item)#

Recursively convert lists to tuples so the values can be put in a set.

Parameters:

item (Any) – Any value, possibly a nested list.

Return type:

Any

Returns:

The value with every list replaced by a tuple.

Examples

>>> hashable([1, [2, 3]])
(1, (2, 3))
class milia.core.config.space.SearchSpace(**extra_data)#

Bases: BaseModel

A validated hyperparameter search space.

Each field must be either a (low, high) tuple of numbers (a range) or a non-empty list (a categorical choice). Float ranges spanning at least one order of magnitude are sampled on a log scale.

Examples

>>> space = SearchSpace(n_estimators=(50, 500), max_features=[0.5, 1.0])
>>> sorted(space.model_dump())
['max_features', 'n_estimators']
checkfields()#

Check that every field is a valid range or categorical list.

Runs automatically after construction.

Return type:

SearchSpace

Returns:

The validated search space.

Raises:
  • ValueError – If a range is not low < high or does not have two elements, or a categorical list is empty or has duplicates.

  • TypeError – If a range holds non-numbers, or a field is neither a tuple nor a list.

suggest(trial, prefix='')#

Sample one value per field from an Optuna trial.

Parameters:
  • trial (Trial) – The active Optuna trial.

  • prefix (str) – Prepended to each trial parameter name, so several spaces can share one trial without collisions.

Return type:

dict[str, Any]

Returns:

Field name (without prefix) to sampled value.

check(config)#

Raise if a search-space field does not exist on config.

Catches a misspelled hyperparameter before any trial runs, rather than sampling a value that is silently never applied.

Parameters:

config (BaseModel) – The model config whose fields define the valid names.

Raises:

ValueError – If any field name is unknown to config.

Return type:

None

Examples

>>> from milia import get
>>> _, config = get("detector", "lof")
>>> SearchSpace(neighbours=(5, 50)).check(config())
Traceback (most recent call last):
...
ValueError: Search space contains unknown fields: ['neighbours']. ...
milia.core.config.space.logscale(low, high)#

Whether a numeric range is wide enough to sample on a log scale.

A range is sampled on a log scale when both bounds are positive and span at least one order of magnitude.

Parameters:
  • low (float) – Lower bound.

  • high (float) – Upper bound.

Return type:

bool

Returns:

True for a log-scale range.

Examples

>>> logscale(1e-4, 1e-2), logscale(0.1, 0.5), logscale(0.0, 10.0)
(True, False, False)