mixle.evolve.space module

A small typed search space: the categorical/integer/box gap-filler over the numeric BO backend.

mixle.doe optimizes over a continuous numeric box (a sequence of (low, high) bounds). Real configuration search needs categorical and integer knobs too, and the evolutionary/bandit backends want to sample and walk neighbors natively. Space is the encoding layer that gives both:

• Space.to_bounds() – a continuous (low, high) box for the BO backend, with categoricals encoded as integer indices ([-0.5, k - 0.5] so a round lands on each level with equal width).

• Space.encode() / Space.decode() – the lossy round-trip between a config dict and the numeric vector the BO backend proposes (decode rounds integers / categorical indices, clips to range).

• Space.sample() / Space.neighbors() – native draws and local moves for the evolutionary/bandit backends that handle categoricals without going through the numeric box.

The space lives in evolve (not doe) on purpose: doe stays a pure numeric-box optimizer, and the encoding policy that bridges categoricals into it is an evolve concern.

class Space(dims)

Bases: object

A typed, named search space over Real / Integer / Categorical dims.

Construct from a dict mapping each parameter name to its dimension:

space = Space({"mu": Real(-5, 5), "k": Integer(1, 4), "family": Categorical(["a", "b"])})

Dimension order is the insertion order of the dict; encode() / decode() and to_bounds() all use that same fixed order so the numeric vector and the box align.

Parameters:

dims (dict[str, Dimension])

property ndim: int

Number of dimensions in the fixed search-space order.

to_bounds()

The continuous (low, high) box for the BO backend (categoricals as integer indices).

Return type:

list[tuple[float, float]]

sample(rng)

Draw a random config dict, each dimension sampled natively.

Parameters:

rng (RandomState)

Return type:

dict[str, Any]

encode(config)

Encode a config dict into the numeric vector (in the fixed dimension order).

Parameters:

config (dict[str, Any])

Return type:

ndarray

decode(vector)

Decode a numeric vector (BO proposal) back into a config dict (rounding / clipping).

Parameters:

vector (Sequence[float])

Return type:

dict[str, Any]

neighbors(point)

All configs one local move away in exactly one dimension (the evolutionary mutation set).

Parameters:

point (dict[str, Any])

Return type:

list[dict[str, Any]]

class Real(lo, hi)

Bases: object

A continuous dimension over [lo, hi].

Parameters:

• lo (float)

• hi (float)

bounds()

Return the numeric bounds used by continuous optimizers.

Return type:

tuple[float, float]

sample(rng)

Draw a uniformly distributed value from the interval.

Parameters:

rng (RandomState)

Return type:

float

encode(value)

Clip and encode value as a floating-point coordinate.

Parameters:

value (Any)

Return type:

float

decode(x)

Clip a numeric optimizer coordinate back into the interval.

Parameters:

x (float)

Return type:

float

neighbors(value)

A coarse local move: +/- 10% of the range, clipped to bounds.

Parameters:

value (Any)

Return type:

list[float]

class Integer(lo, hi)

Bases: object

An integer dimension over the inclusive range [lo, hi].

Parameters:

• lo (int)

• hi (int)

bounds()

Return widened numeric bounds so rounding covers each integer level.

Return type:

tuple[float, float]

sample(rng)

Draw an integer uniformly from the inclusive range.

Parameters:

rng (RandomState)

Return type:

int

encode(value)

Round, clip, and encode value as a numeric coordinate.

Parameters:

value (Any)

Return type:

float

decode(x)

Round and clip a numeric optimizer coordinate to an integer value.

Parameters:

x (float)

Return type:

int

neighbors(value)

Return adjacent integer values within the range.

Parameters:

value (Any)

Return type:

list[int]

class Categorical(choices)

Bases: object

An unordered categorical dimension over a finite list of choices.

Parameters:

choices (tuple[Any, ...])

bounds()

Return widened index bounds so rounding covers each categorical choice.

Return type:

tuple[float, float]

sample(rng)

Draw one choice uniformly at random.

Parameters:

rng (RandomState)

Return type:

Any

encode(value)

Encode a choice as its floating-point index.

Parameters:

value (Any)

Return type:

float

decode(x)

Round and clip an optimizer coordinate back to a choice.

Parameters:

x (float)

Return type:

Any

neighbors(value)

Return all choices except value.

Parameters:

value (Any)

Return type:

list[Any]