cotengra.hyperoptimizers.hyper_random

Hyper optimization using random or Latin Hypercube sampling.

Classes

RandomSpace
LHSRandomSpace	Latin Hypercube Sampled random space. Pre-generates n samples with
RandomSampler	Random parameter sampler with optional LHS warm-up.
RandomOptLib	Random sampling optimizer with optional Latin Hypercube warm-up.

Functions

sample_bool(rng)
sample_int(rng, low, high)
sample_option(rng, options)
sample_uniform(rng, low, high)
sample_loguniform(rng, low, high)

Module Contents

cotengra.hyperoptimizers.hyper_random.sample_bool(rng)

cotengra.hyperoptimizers.hyper_random.sample_int(rng, low, high)

cotengra.hyperoptimizers.hyper_random.sample_option(rng, options)

cotengra.hyperoptimizers.hyper_random.sample_uniform(rng, low, high)

cotengra.hyperoptimizers.hyper_random.sample_loguniform(rng, low, high)

class cotengra.hyperoptimizers.hyper_random.RandomSpace(space, seed=None)

rng

_samplers

sample()

class cotengra.hyperoptimizers.hyper_random.LHSRandomSpace(space, n, seed=None)

Latin Hypercube Sampled random space. Pre-generates n samples with stratified coverage over each parameter’s native domain. For continuous parameters (FLOAT, FLOAT_EXP, INT) the range is divided into n equal strata with one sample per stratum. For categorical parameters (STRING, BOOL) the options are cycled through in balanced fashion and randomly permuted. Once all pre-generated samples are exhausted, falls back to pure random sampling.

Parameters:

• space (dict[str, dict]) – The search space for a single method.

• n (int) – Number of LHS samples to pre-generate.

• seed (None or int or random.Random, optional) – Random seed.

rng

_n

_params

_fallback

_samples = []

_stratify_float(n, lo, hi)

Divide [lo, hi] into n equal strata, sample one uniform point per stratum, then randomly permute.

_stratify_int(n, lo, hi)

Stratify an integer range [lo, hi].

The continuous interval [lo, hi + 1) is divided into n strata, a uniform float is drawn per stratum, and then floored to an integer (clamped to hi).

_stratify_categorical(n, options)

Cycle through options in balanced fashion with random permutation. Each option appears either floor(n / k) or ceil(n / k) times, where k = len(options).

sample()

Return the next sample. Uses pre-generated LHS points first, then falls back to pure random sampling.

class cotengra.hyperoptimizers.hyper_random.RandomSampler(methods, spaces, n_samples=None, seed=None)

Random parameter sampler with optional LHS warm-up.

Parameters:

• methods (list[str]) – The contraction methods to sample from.

• spaces (dict[str, dict[str, dict]]) – The per-method search spaces.

• n_samples (int or None, optional) – If given, use Latin Hypercube Sampling for the first n_samples calls per method, then fall back to pure random. If None, use pure random sampling throughout.

• seed (None or int or random.Random, optional) – Random seed.

rng

_rmethods

ask()

class cotengra.hyperoptimizers.hyper_random.RandomOptLib

Bases: cotengra.hyperoptimizers.hyper.HyperOptLib

Random sampling optimizer with optional Latin Hypercube warm-up.

When lhs=True (the default), the first batch of samples per method uses Latin Hypercube Sampling for better coverage of the search space. The batch size is derived from the parent optimizer’s max_repeats attribute divided by the number of methods. After the LHS batch is exhausted, sampling falls back to pure random.

setup(methods, space, optimizer=None, lhs=False, seed=None, **kwargs)

Initialize random sampling.

Parameters:

• methods (list[str]) – The list of contraction methods to sample from.

• space (dict[str, dict[str, dict]]) – The search space.

• optimizer (HyperOptimizer, optional) – The parent optimizer instance, used for max_repeats.

• lhs (bool, optional) – Whether to use Latin Hypercube Sampling for the initial batch. Default True.

• seed (None or int, optional) – Random seed.

get_setting()

Suggest the next setting to trial.

Returns:

setting – Must contain at least {"method": str, "params": dict}. May also include tokens for reporting.

Return type:

dict

report_result(setting, trial, score)

Report the result of a trial.

Parameters:

• setting (dict) – The setting dict returned by get_setting.

• trial (dict) – The trial result dict.

• score (float) – The scalar score for this trial.