Parameters¶

Parameter sources define the space of configurations to explore. metalab supports grid search, random sampling, and manual parameter specification.

Grid Search¶

Define exhaustive combinations of parameter values.

metalab.grid ¶

GridSource: Cartesian product parameter generation.

Generates all combinations of the provided parameter values.

GridSource ¶

GridSource(**kwargs: list[Any])

Parameter source that generates a Cartesian product of values.

Example:

source = GridSource(learning_rate=[0.01, 0.1], batch_size=[32, 64])
# Yields 4 cases: all combinations of learning_rate x batch_size

Initialize with parameter names mapped to lists of values.

Parameters:

Name	Type	Description	Default
`**kwargs`	`list[Any]`	Parameter names mapped to lists of possible values.	`{}`

getitem ¶

__getitem__(index: int) -> ParamCase

Get parameter case by index without enumerating all cases.

Uses modular arithmetic to compute the combination for a given index. The ordering matches iter (sorted keys, Cartesian product order).

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the parameter case (0-based).	required

Returns:

Type	Description
`ParamCase`	The ParamCase at the given index.

Raises:

Type	Description
`IndexError`	If index is out of range.

iter ¶

__iter__() -> Iterator[ParamCase]

Yield all combinations of parameter values.

len ¶

__len__() -> int

Return the total number of parameter combinations.

from_manifest_dict `classmethod` ¶

from_manifest_dict(manifest: dict[str, Any]) -> 'GridSource'

Reconstruct GridSource from manifest dict.

Parameters:

Name	Type	Description	Default
`manifest`	`dict[str, Any]`	Dict with "spec" containing parameter name -> values mapping.	required

Returns:

Type	Description
`'GridSource'`	A GridSource with the same configuration.

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation for experiment manifests.

grid ¶

grid(**kwargs: list[Any]) -> GridSource

Create a GridSource for Cartesian product parameter generation.

Parameters:

Name	Type	Description	Default
`**kwargs`	`list[Any]`	Parameter names mapped to lists of possible values.	`{}`

Returns:

Type	Description
`GridSource`	A GridSource that yields all combinations.

Example:

params = grid(
    n_samples=[1000, 10000, 100000],
    store_points=[True, False],
)
# Yields 6 cases: 3 n_samples values x 2 store_points values

Random Search¶

Sample parameters from probability distributions.

metalab.random ¶

RandomSource: Replayable random parameter sampling.

Generates random parameter combinations using a seeded RNG, ensuring reproducibility.

Choice `dataclass` ¶

Choice(options: tuple[Any, ...])

Uniform choice from a list of options.

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation.

Distribution ¶

Bases: Protocol

Protocol for parameter distributions.

sample ¶

sample(rng: Random) -> Any

Sample a value from this distribution.

LogUniform `dataclass` ¶

LogUniform(low: float, high: float)

Log-uniform distribution over [low, high).

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation.

LogUniformInt `dataclass` ¶

LogUniformInt(low: int, high: int)

Log-uniform distribution over integers in [low, high].

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation.

RandInt `dataclass` ¶

RandInt(low: int, high: int)

Uniform distribution over integers in [low, high].

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation.

RandomSource ¶

RandomSource(space: dict[str, Distribution], n_trials: int, seed: int)

Parameter source that generates random samples.

Uses a seeded RNG for reproducibility. Given the same seed and space, always generates the same sequence of parameter cases.

Supports O(1) index-based access via getitem, where each index derives its own deterministic seed, enabling SLURM array submission without pre-generating all samples.

Initialize the random source.

Parameters:

Name	Type	Description	Default
`space`	`dict[str, Distribution]`	Parameter names mapped to Distribution objects.	required
`n_trials`	`int`	Number of random samples to generate.	required
`seed`	`int`	Random seed for reproducibility.	required

getitem ¶

__getitem__(index: int) -> ParamCase

Get parameter case by index in O(1) time.

Each index derives its own deterministic seed, so accessing source[i] always returns the same sample regardless of what other indices have been accessed.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the parameter case (0-based).	required

Returns:

Type	Description
`ParamCase`	The ParamCase at the given index.

Raises:

Type	Description
`IndexError`	If index is out of range.

iter ¶

__iter__() -> Iterator[ParamCase]

Yield random parameter cases.

len ¶

__len__() -> int

Return the number of trials.

from_manifest_dict `classmethod` ¶

from_manifest_dict(manifest: dict[str, Any]) -> 'RandomSource'

Reconstruct RandomSource from manifest dict.

Parameters:

Name	Type	Description	Default
`manifest`	`dict[str, Any]`	Dict with "space", "n_trials", and "seed" fields.	required

Returns:

Type	Description
`'RandomSource'`	A RandomSource with the same configuration.

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation for experiment manifests.

Uniform `dataclass` ¶

Uniform(low: float, high: float)

Uniform distribution over [low, high).

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation.

choice ¶

choice(options: list[Any]) -> Choice

Create a uniform choice distribution from a list of options.

loguniform ¶

loguniform(low: float, high: float) -> LogUniform

Create a log-uniform distribution over [low, high).

loguniform_int ¶

loguniform_int(low: int, high: int) -> LogUniformInt

Create a log-uniform distribution over integers in [low, high].

randint ¶

randint(low: int, high: int) -> RandInt

Create a uniform distribution over integers in [low, high].

random ¶

random(space: dict[str, Distribution], n_trials: int, seed: int) -> RandomSource

Create a RandomSource for replayable random parameter sampling.

Parameters:

Name	Type	Description	Default
`space`	`dict[str, Distribution]`	Parameter names mapped to Distribution objects.	required
`n_trials`	`int`	Number of random samples to generate.	required
`seed`	`int`	Random seed for reproducibility.	required

Returns:

Type	Description
`RandomSource`	A RandomSource that yields random parameter cases.

Example

params = random(
    space={
        "n_samples": loguniform_int(1000, 1000000),
        "store_points": choice([True, False]),
    },
    n_trials=20,
    seed=123,
)

uniform ¶

uniform(low: float, high: float) -> Uniform

Create a uniform distribution over [low, high).

metalab.uniform ¶

uniform(low: float, high: float) -> Uniform

Create a uniform distribution over [low, high).

metalab.loguniform ¶

loguniform(low: float, high: float) -> LogUniform

Create a log-uniform distribution over [low, high).

metalab.choice ¶

choice(options: list[Any]) -> Choice

Create a uniform choice distribution from a list of options.

Manual¶

Specify explicit parameter cases directly.

metalab.manual ¶

ManualSource: Explicit list of parameter cases.

For when you want to specify exact parameter combinations.

ManualSource ¶

ManualSource(cases: list[dict[str, Any]], tags: list[str] | None = None)

Parameter source from an explicit list of parameter dictionaries.

Example:

source = ManualSource([
    {"learning_rate": 0.01, "batch_size": 32},
    {"learning_rate": 0.1, "batch_size": 64},
])

Initialize with a list of parameter dictionaries.

Parameters:

Name	Type	Description	Default
`cases`	`list[dict[str, Any]]`	List of parameter dictionaries.	required
`tags`	`list[str] \| None`	Optional tags to apply to all cases.	`None`

getitem ¶

__getitem__(index: int) -> ParamCase

Get parameter case by index.

Parameters:

Name	Type	Description	Default
`index`	`int`	The index of the parameter case (0-based, supports negative).	required

Returns:

Type	Description
`ParamCase`	The ParamCase at the given index.

Raises:

Type	Description
`IndexError`	If index is out of range.

iter ¶

__iter__() -> Iterator[ParamCase]

Yield parameter cases.

len ¶

__len__() -> int

Return the number of cases.

from_manifest_dict `classmethod` ¶

from_manifest_dict(manifest: dict[str, Any]) -> 'ManualSource'

Reconstruct ManualSource from manifest dict.

Parameters:

Name	Type	Description	Default
`manifest`	`dict[str, Any]`	Dict with "cases" list and optional "tags".	required

Returns:

Type	Description
`'ManualSource'`	A ManualSource with the same configuration.

to_manifest_dict ¶

to_manifest_dict() -> dict[str, Any]

Return a JSON-serializable dict representation for experiment manifests.

manual ¶

manual(cases: list[dict[str, Any]], tags: list[str] | None = None) -> ManualSource

Create a ManualSource from an explicit list of parameter dictionaries.

Parameters:

Name	Type	Description	Default
`cases`	`list[dict[str, Any]]`	List of parameter dictionaries.	required
`tags`	`list[str] \| None`	Optional tags to apply to all cases.	`None`

Returns:

Type	Description
`ManualSource`	A ManualSource that yields the specified cases.

Example:

params = manual([
    {"learning_rate": 0.01, "batch_size": 32},
    {"learning_rate": 0.1, "batch_size": 64},
])

Parameters¶

Grid Search¶

metalab.grid ¶

GridSource ¶

__getitem__ ¶

__iter__ ¶

__len__ ¶

from_manifest_dict classmethod ¶

to_manifest_dict ¶

grid ¶

Random Search¶

metalab.random ¶

Choice dataclass ¶

to_manifest_dict ¶

Distribution ¶

sample ¶

LogUniform dataclass ¶

to_manifest_dict ¶

LogUniformInt dataclass ¶

to_manifest_dict ¶

RandInt dataclass ¶

to_manifest_dict ¶

RandomSource ¶

__getitem__ ¶

__iter__ ¶

__len__ ¶

from_manifest_dict classmethod ¶

to_manifest_dict ¶

Uniform dataclass ¶

to_manifest_dict ¶

choice ¶

loguniform ¶

loguniform_int ¶

randint ¶

random ¶

uniform ¶

metalab.uniform ¶

metalab.loguniform ¶

metalab.choice ¶

Manual¶

metalab.manual ¶

ManualSource ¶

__getitem__ ¶

__iter__ ¶

__len__ ¶

from_manifest_dict classmethod ¶

to_manifest_dict ¶

manual ¶

getitem ¶

iter ¶

len ¶

from_manifest_dict `classmethod` ¶

Choice `dataclass` ¶

LogUniform `dataclass` ¶

LogUniformInt `dataclass` ¶

RandInt `dataclass` ¶

getitem ¶

iter ¶

len ¶

from_manifest_dict `classmethod` ¶

Uniform `dataclass` ¶

getitem ¶

iter ¶

len ¶

from_manifest_dict `classmethod` ¶