Parameter sweeps

Compose parameter combinations, iterate experiments, and save or reload configurations. Start with Sweep; piter builds parameter iterators. The proxy and iterator classes below describe the supporting objects.

python

from params_proto import Sweep

See hyperparameter sweeps for complete examples.

API index

Name	Kind	Defined in
`BaseProxy`	class	`params_proto.hyper.proxies`
`ClassProxy`	class	`params_proto.hyper.proxies`
`FuncProxy`	class	`params_proto.hyper.proxies`
`PrefixProxy`	class	`params_proto.hyper.proxies`
`ParameterIterator`	class	`params_proto.hyper.sweep`
`PiterFactory`	class	`params_proto.hyper.sweep`
`dot_join`	function	`params_proto.hyper.sweep`
`key_items`	function	`params_proto.hyper.sweep`
`flatten_items`	function	`params_proto.hyper.sweep`
`SweepProxy`	class	`params_proto.hyper.sweep`
`Sweep`	class	`params_proto.hyper.sweep`
`piter`	singleton	`params_proto.hyper.sweep`

params_proto.hyper

Hyperparameter sweep module for params-proto v3.

Public imports

These symbols are available from this module. Their definitions are documented in the linked modules.

ParameterIterator — params_proto.hyper.sweep.ParameterIterator
Sweep — params_proto.hyper.sweep.Sweep
piter — params_proto.hyper.sweep.piter

params_proto.hyper.proxies

Proxy classes for Sweep integration with v3 proto decorators.

`BaseProxy`

classparams_proto.hyper.proxies.BaseProxySource ↗

BaseProxy(proto_obj)

Base proxy providing common Sweep interface.

Parameters

Parameter	Type / default	Description
`proto_obj`	`—` required	—

`BaseProxy.init`

methodparams_proto.hyper.proxies.BaseProxy.__init__Source ↗

BaseProxy.__init__(proto_obj)

Wrap a proto object.

Parameters

Parameter	Type / default	Description
`proto_obj`	`—` required	—

`ClassProxy`

classparams_proto.hyper.proxies.ClassProxySource ↗

class ClassProxy(BaseProxy)

Bases: BaseProxy

Proxy for @proto decorated classes (non-prefix).

Inherited members

__init__ — from params_proto.hyper.proxies.BaseProxy

`FuncProxy`

classparams_proto.hyper.proxies.FuncProxySource ↗

class FuncProxy(BaseProxy)

Bases: BaseProxy

Proxy for @proto.cli decorated functions (non-prefix).

Inherited members

__init__ — from params_proto.hyper.proxies.BaseProxy

`PrefixProxy`

classparams_proto.hyper.proxies.PrefixProxySource ↗

class PrefixProxy(BaseProxy)

Bases: BaseProxy

Proxy for @proto.prefix decorated classes/functions.

Inherited members

__init__ — from params_proto.hyper.proxies.BaseProxy

Public imports

These symbols are available from this module. Their definitions are documented in the linked modules.

ProtoWrapper — params_proto.proto.ProtoWrapper

params_proto.hyper.sweep

v3 hyperparameter sweep implementation.

`ParameterIterator`

classparams_proto.hyper.sweep.ParameterIteratorSource ↗

ParameterIterator(iterator, protos = None)

Lazy iterator over parameter configurations.

Supports operations like product (*), override (%), and power (**).

Parameters

Parameter	Type / default	Description
`iterator`	`—` required	Generator or iterable of config dicts
`protos`	`—` = None	Optional dict of proto objects for context

`ParameterIterator.init`

methodparams_proto.hyper.sweep.ParameterIterator.__init__Source ↗

ParameterIterator.__init__(iterator, protos = None)

Initialize parameter iterator.

Parameters

Parameter	Type / default	Description
`iterator`	`—` required	Generator or iterable of config dicts
`protos`	`—` = None	Optional dict of proto objects for context

`ParameterIterator.list`

propertyparams_proto.hyper.sweep.ParameterIterator.listSource ↗

ParameterIterator.list

Materialize all configs into a list.

`ParameterIterator.to_list`

methodparams_proto.hyper.sweep.ParameterIterator.to_listSource ↗

ParameterIterator.to_list()

Materialize all configs into a list (alias for .list).

`ParameterIterator.save`

methodparams_proto.hyper.sweep.ParameterIterator.saveSource ↗

ParameterIterator.save(filename = 'sweep.jsonl', overwrite = True, verbose = True)

Save parameter configurations to JSONL file.

Example

python

configs = piter @ {"lr": [0.001, 0.01]} * {"batch_size": [32, 64]}
configs.save("experiment.jsonl")

Parameters

Parameter	Type / default	Description
`filename`	`—` = 'sweep.jsonl'	Path to output file (str or PathLike)
`overwrite`	`—` = True	If True, overwrite existing file; if False, append
`verbose`	`—` = True	If True, print save confirmation

`ParameterIterator.load`

static methodparams_proto.hyper.sweep.ParameterIterator.loadSource ↗

ParameterIterator.load(filename = 'sweep.jsonl')

Load parameter configurations from JSONL file.

Example

python

configs = ParameterIterator.load("experiment.jsonl")
for config in configs:
    run_experiment(**config)

Parameters

Parameter	Type / default	Description
`filename`	`—` = 'sweep.jsonl'	Path to input file (str or PathLike)

Returns

ParameterIterator with loaded configurations

`PiterFactory`

classparams_proto.hyper.sweep.PiterFactorySource ↗

class PiterFactory

Factory for creating parameter iterators.

Supports both function-call syntax and @ operator syntax:

python

piter({"lr": [0.001, 0.01]})      # function call
piter @ {"lr": [0.001, 0.01]}     # @ operator

The @ operator enables clean chaining:

python

piter @ {"lr": [0.001, 0.01]} * piter @ {"batch_size": [32, 64]}

`dot_join`

functionparams_proto.hyper.sweep.dot_joinSource ↗

dot_join(*keys)

Remove Nones from the keys, but not empty strings.

Parameters

Parameter	Type / default	Description
`*keys`	`—` variadic	—

`key_items`

functionparams_proto.hyper.sweep.key_itemsSource ↗

key_items(d, prefix = None)

Takes in tuples of [key, value], or [None, [[key, value], ...]]. Yields items with optional prefix.

Parameters

Parameter	Type / default	Description
`d`	`—` required	—
`prefix`	`—` = None	—

`flatten_items`

functionparams_proto.hyper.sweep.flatten_itemsSource ↗

flatten_items(row) → Iterable[Item]

Recursively flatten nested items.

Parameters

Parameter	Type / default	Description
`row`	`—` required	—

Returns

Iterable[Item]

`SweepProxy`

classparams_proto.hyper.sweep.SweepProxySource ↗

SweepProxy(proto_obj)

Proxy that switches between normal delegation and sweep interception.

When not in sweep context: delegates all access directly to wrapped ptype class When in sweep context: intercepts setattr to record sweep configurations

Parameters

Parameter	Type / default	Description
`proto_obj`	`—` required	The actual proto class (ptype instance) or ProtoWrapper

`SweepProxy.init`

methodparams_proto.hyper.sweep.SweepProxy.__init__Source ↗

SweepProxy.__init__(proto_obj)

Wrap a ptype class or ProtoWrapper.

Parameters

Parameter	Type / default	Description
`proto_obj`	`—` required	The actual proto class (ptype instance) or ProtoWrapper

`Sweep`

classparams_proto.hyper.sweep.SweepSource ↗

Sweep(*protos)

Hyperparameter sweep for v3 @proto decorated classes and functions.

Supports product, zip, chain, and set operations for combining parameter configurations.

Parameters

Parameter	Type / default	Description
`*protos`	`—` variadic	ProtoWrapper instances or metaclass-based proto classes

`Sweep.init`

methodparams_proto.hyper.sweep.Sweep.__init__Source ↗

Sweep.__init__(*protos)

Initialize Sweep with proto objects.

Parameters

Parameter	Type / default	Description
`*protos`	`—` variadic	ProtoWrapper instances or metaclass-based proto classes

`Sweep.items`

methodparams_proto.hyper.sweep.Sweep.itemsSource ↗

Sweep.items()

Return enumerated sweep configurations.

`Sweep.list`

propertyparams_proto.hyper.sweep.Sweep.listSource ↗

Sweep.list

Convert sweep to list of configuration dicts.

`Sweep.to_list`

methodparams_proto.hyper.sweep.Sweep.to_listSource ↗

Sweep.to_list()

Convert sweep to list of configuration dicts (alias for .list).

`Sweep.dataframe`

propertyparams_proto.hyper.sweep.Sweep.dataframeSource ↗

Sweep.dataframe

Convert sweep to pandas DataFrame.

`Sweep.noot`

propertyparams_proto.hyper.sweep.Sweep.nootSource ↗

Sweep.noot

Return deep copy of root protos.

`Sweep.snack`

propertyparams_proto.hyper.sweep.Sweep.snackSource ↗

Sweep.snack

Return deep copy of stack.

`Sweep.original`

propertyparams_proto.hyper.sweep.Sweep.originalSource ↗

Sweep.original

Get original parameter values for each proto.

`Sweep.set_param`

methodparams_proto.hyper.sweep.Sweep.set_paramSource ↗

Sweep.set_param(name, params, prefix = None)

Add parameter to current sweep stack.

Parameters

Parameter	Type / default	Description
`name`	`—` required	—
`params`	`—` required	—
`prefix`	`—` = None	—

`Sweep.product`

propertyparams_proto.hyper.sweep.Sweep.productSource ↗

Sweep.product: ContextManager[None]

Context manager for Cartesian product of parameters.

Type

ContextManager[None]

`Sweep.zip`

propertyparams_proto.hyper.sweep.Sweep.zipSource ↗

Sweep.zip: ContextManager[None]

Context manager for element-wise zip of parameters.

Type

ContextManager[None]

`Sweep.set`

propertyparams_proto.hyper.sweep.Sweep.setSource ↗

Sweep.set: ContextManager[None]

Context manager for setting fixed parameter values.

Type

ContextManager[None]

`Sweep.chain`

propertyparams_proto.hyper.sweep.Sweep.chainSource ↗

Sweep.chain: ContextManager[None]

Context manager for chaining multiple sweep configurations.

Type

ContextManager[None]

`Sweep.each`

methodparams_proto.hyper.sweep.Sweep.eachSource ↗

Sweep.each(fn)

Useful for setting values that dynamically depend on other sweep values.

Parameters

Parameter	Type / default	Description
`fn`	`—` required	—

`Sweep.save`

methodparams_proto.hyper.sweep.Sweep.saveSource ↗

Sweep.save(filename = 'sweep.jsonl', overwrite = True, verbose = True)

Save sweep configurations to JSONL file.

Parameters

Parameter	Type / default	Description
`filename`	`—` = 'sweep.jsonl'	Path to output file (str or PathLike)
`overwrite`	`—` = True	If True, overwrite existing file; if False, append
`verbose`	`—` = True	If True, print save confirmation

`Sweep.log`

static methodparams_proto.hyper.sweep.Sweep.logSource ↗

Sweep.log(deps, filename)

Append single config to JSONL file.

Parameters

Parameter	Type / default	Description
`deps`	`—` required	—
`filename`	`—` required	—

`Sweep.read`

static methodparams_proto.hyper.sweep.Sweep.readSource ↗

Sweep.read(filename)

Read JSONL file into list of dicts.

Parameters

Parameter	Type / default	Description
`filename`	`—` required	—

`Sweep.load`

methodparams_proto.hyper.sweep.Sweep.loadSource ↗

Sweep.load(file: Union[str, 'os.PathLike[str]', List[Dict[str, Any]], 'pd.DataFrame'] = 'sweep.jsonl', strict: bool = True, silent: bool = False)

Load sweep configurations from JSONL file or list.

Parameters

Parameter	Type / default	Description
`file`	`Union[str, 'os.PathLike[str]', List[Dict[str, Any]], 'pd.DataFrame']` = 'sweep.jsonl'	Filename (str or PathLike), list of dicts, or pandas DataFrame
`strict`	`bool` = True	Raise error on missing attributes (default True)
`silent`	`bool` = False	Suppress warnings about missing attributes (default False)

Returns

self for chaining

`piter`

callable singletonparams_proto.hyper.sweep.piterSource ↗

piter = PiterFactory()

Factory for creating parameter iterators.

Supports both function-call syntax and @ operator syntax:

python

piter({"lr": [0.001, 0.01]})      # function call
piter @ {"lr": [0.001, 0.01]}     # @ operator

The @ operator enables clean chaining:

python

piter @ {"lr": [0.001, 0.01]} * piter @ {"batch_size": [32, 64]}

`piter.call`

methodparams_proto.hyper.sweep.piter.__call__Source ↗

piter.__call__(spec)

Create parameter iterator (function-call syntax).

Parameters

Parameter	Type / default	Description
`spec`	`—` required	—

`piter.matmul`

methodparams_proto.hyper.sweep.piter.__matmul__Source ↗

piter.__matmul__(spec)

Create parameter iterator (@ operator syntax).

Parameters

Parameter	Type / default	Description
`spec`	`—` required	—

Public imports

These symbols are available from this module. Their definitions are documented in the linked modules.

ProtoWrapper — params_proto.proto.ProtoWrapper
ptype — params_proto.proto.ptype