Parameter Iterators (piter)
The piter operator provides a lightweight, composable way to create parameter sweeps using simple dictionaries and operators. Unlike the Sweep class which requires @proto decorated classes, piter works with plain dictionaries and supports lazy evaluation for memory efficiency.
Syntax: piter @ {...}
params-proto uses the @ operator for clean, readable parameter iteration:
Both syntaxes are fully functional, but @ is preferred for cleaner, more readable code.
Operators Quick Reference
| Operator | Name | Description | Example | Result |
|---|---|---|---|---|
@ | Create | Create iterator from dict | piter @ {"lr": [0.001, 0.01]} | 2 configs |
* | Product | Cartesian product | piter @ {"lr": [0.001, 0.01]} * {"bs": [32, 64]} | 4 configs (2×2) |
% | Override | Add fixed params to all | configs % {"seed": 42} | Same count, +seed |
** | Repeat | Repeat each config n times | configs ** 3 | 3× count |
Operator Precedence
@ and * have the same precedence (both are multiplicative), evaluated left-to-right:
Precedence order (high to low): ** (power) > @ * (same level) > % (modulo)
Quick Start
Key Features
- Lazy evaluation: Configurations are generated on-the-fly, not stored in memory
- Composable: Combine iterators using operators (
*,%,**) - Reusable: Results are cached, so you can iterate multiple times
- Memory efficient: Only materializes when needed via
.to_list()orlen()
Basic Usage
Creating a piter
Materializing Configs
Operators
Cartesian Product (*)
Combine parameter iterators to create all possible combinations. When chaining multiple dicts, only the first needs piter @:
Use case: Exploring all combinations of independent hyperparameters.
Override (%)
Apply fixed parameters to all configurations:
Use case: Adding fixed parameters (seed, device, logging config) to all experiments.
Repeat (**)
Repeat each configuration n times:
Use case: Running multiple trials/seeds for each configuration.
Composition Patterns
Pattern 1: Grid Search with Fixed Seed
Pattern 2: Multiple Trials per Config
Pattern 3: Combining Multiple Parameter Groups
Pattern 4: Chained Composition
Integration with Sweep
The Sweep class also supports piter operators:
Comparison: piter vs Sweep
| Feature | piter | Sweep |
|---|---|---|
| Input | Plain dictionaries | @proto decorated classes |
| Syntax | piter @ {"lr": [0.001, 0.01]} | with sweep.product: Config.lr = [0.001, 0.01] |
| Default behavior | Zip (element-wise) | Context-dependent (.product, .zip, etc.) |
| Operators | * (product), % (override), ** (repeat) | Context managers (.product, .zip, .set) |
| Lazy | Yes | No (materializes in context) |
| Type checking | No | Yes (via @proto) |
| Proto integration | No | Yes (updates class attributes) |
| Use case | Quick sweeps, scripting | Production configs, type safety |
Best Practices
1. Use descriptive keys
2. Materialize only when necessary
3. Use operators for clarity
4. Combine with type-safe configs in production
Advanced Examples
Conditional Parameter Sweeps
Nested Grids with Fixed Outer Parameters
Hierarchical Parameter Groups
API Reference
piter @ spec or piter(spec: dict) -> ParameterIterator
Create a parameter iterator from a specification dictionary.
Syntax:
Args:
spec: Dict mapping parameter names (strings) to values or lists of values
Returns:
ParameterIteratorthat zips parameter lists element-wise
Note: For Cartesian product, use the * operator to chain multiple dicts. Only the first needs piter @:
ParameterIterator Methods
| Method | Description |
|---|---|
__iter__() | Iterate over configurations |
to_list() | Materialize all configs to a list |
.list | Property alias for to_list() |
__len__() | Return number of configs (materializes) |
__mul__(other) | Cartesian product with another iterator (*) |
__mod__(other) | Apply overrides to all configs (%) |
__pow__(n) | Repeat each config n times (**) |
Related
- Core Concepts - Decorators and basic usage
- Configuration Patterns - Function vs class configurations
- CLI Fundamentals - Basic CLI features
- Parameter Overrides - Override methods and context managers
Hyperparameter Sweeps- TraditionalSweepclass with@protointegrationAdvanced Patterns- Prefixes and composition