0
# Parametrization System
1

2
Comprehensive parameter handling system that supports scalar values, arrays, discrete choices, hierarchical structures, and constraints. The parametrization module provides the foundation for defining optimization search spaces with sophisticated parameter types and transformations.
3

4
## Capabilities
5

6
### Core Parameter Base Class
7

8
The fundamental Parameter class that all parameter types inherit from, providing common functionality for mutation, sampling, and value management.
9

10
```python { .api }
11
class Parameter:
12
    """
13
    Abstract base class for all parameter types.
14
    
15
    Properties:
16
    - value: The main value property (Any)
17
    - losses: Multi-objective losses (ArrayLike) 
18
    - args: Positional arguments (Tuple[Any, ...])
19
    - kwargs: Keyword arguments (Dict[str, Any])
20
    - dimension: Parameter dimension (int)
21
    - generation: Current generation (int)
22
    - random_state: Random state (np.random.RandomState)
23
    """
24
    value: Any
25
    losses: ArrayLike
26
    args: Tuple[Any, ...]
27
    kwargs: Dict[str, Any]
28
    dimension: int
29
    generation: int
30
    random_state: np.random.RandomState
31
    
32
    def mutate(self) -> None:
33
        """Mutate parameter in place."""
34
    
35
    def sample(self) -> 'Parameter':
36
        """Create new sample."""
37
    
38
    def recombine(self, *others) -> 'Parameter':
39
        """Recombine with other parameters."""
40
    
41
    def get_standardized_data(self, *, reference) -> np.ndarray:
42
        """Get standardized representation."""
43
    
44
    def set_standardized_data(self, data: np.ndarray, *, reference=None) -> None:
45
        """Set from standardized data."""
46
    
47
    def get_value_hash(self) -> str:
48
        """Get value hash."""
49
    
50
    def satisfies_constraints(self, ref=None, no_tabu=False) -> bool:
51
        """Check constraints."""
52
    
53
    def spawn_child(self, new_value=None) -> 'Parameter':
54
        """Create child parameter."""
55
    
56
    def copy(self) -> 'Parameter':
57
        """Create parameter copy."""
58
    
59
    def freeze(self) -> 'Parameter':
60
        """Freeze parameter (immutable)."""
61

62
class Constant(Parameter):
63
    """Parameter with constant, unchanging value."""
64

65
class MultiobjectiveReference(Constant):
66
    """Reference parameter for multi-objective optimization scenarios."""
67
```
68

69
### Data Parameter Types
70

71
Fundamental parameter types for continuous optimization including scalars, arrays, and log-scale parameters with support for bounds and constraints.
72

73
```python { .api }
74
class Data(Parameter):
75
    """
76
    Base class for continuous data parameters.
77
    
78
    Properties:
79
    - bounds: Parameter bounds (Tuple[float, float])
80
    - sigma: Mutation sigma parameter (float)
81
    - integer: Integer-valued flag (bool)
82
    """
83
    bounds: Tuple[float, float]
84
    sigma: float
85
    integer: bool
86
    
87
    def set_bounds(self, lower: float, upper: float, method: str = "clipping") -> 'Data':
88
        """Set parameter bounds."""
89
    
90
    def set_mutation(self, sigma: float = None) -> 'Data':
91
        """Configure mutation parameters."""
92
    
93
    def set_integer_casting(self) -> 'Data':
94
        """Enable integer casting."""
95

96
class Array(Data):
97
    """
98
    Multi-dimensional array parameter for vector/matrix optimization.
99
    
100
    Parameters:
101
    - shape: Array shape (tuple)
102
    - init: Initialization method
103
    """
104

105
class Scalar(Data):
106
    """
107
    Single scalar parameter for single-valued optimization.
108
    
109
    Parameters:
110
    - init: Initial value (float)
111
    """
112

113
class Log(Scalar):
114
    """
115
    Log-scale scalar parameter for log-distributed values.
116
    
117
    Parameters:
118
    - init: Initial value (float)
119
    - lower: Lower bound (float)
120
    - upper: Upper bound (float)
121
    """
122
```
123

124
### Container Parameter Types
125

126
Hierarchical parameter containers that organize multiple parameters into structured collections with dictionary and tuple semantics.
127

128
```python { .api }
129
class Container(Parameter):
130
    """Base class for parameter containers."""
131

132
class Dict(Container):
133
    """
134
    Dictionary-like parameter container.
135
    
136
    Methods provide dictionary-like access to contained parameters.
137
    """
138
    
139
    def keys(self) -> KeysView:
140
        """Get parameter keys."""
141
    
142
    def items(self) -> ItemsView:
143
        """Get parameter items."""
144
    
145
    def values(self) -> ValuesView:
146
        """Get parameter values."""
147

148
class Tuple(Container):
149
    """Tuple-like parameter container for ordered collections."""
150

151
class Instrumentation(Tuple):
152
    """
153
    Special tuple for function instrumentation with positional and keyword arguments.
154
    
155
    Automatically handles conversion between parameter values and function arguments.
156
    """
157
```
158

159
### Choice Parameter Types
160

161
Discrete choice parameters for categorical variables and selection from finite sets with support for uniform and weighted selection probabilities.
162

163
```python { .api }
164
class BaseChoice(Container):
165
    """Base class for discrete choice parameters."""
166

167
class Choice(BaseChoice):
168
    """
169
    Discrete choice parameter with uniform selection probabilities.
170
    
171
    Parameters:
172
    - choices: Available choices (list or iterable)
173
    """
174

175
class TransitionChoice(BaseChoice):
176
    """
177
    Choice parameter with configurable transition probabilities.
178
    
179
    Parameters:
180
    - choices: Available choices (list)
181
    - transitions: Transition probability matrix
182
    """
183
```
184

185
### Special Parameter Types
186

187
Specialized parameter types for specific domains including angular parameters and constraint handling.
188

189
```python { .api }
190
class Angles:
191
    """
192
    Angular parameter handling for circular/periodic variables.
193
    
194
    Handles wrap-around behavior and appropriate distance metrics
195
    for angular/periodic optimization variables.
196
    """
197
```
198

199
### Mutation System
200

201
Comprehensive mutation operators that define how parameters change during optimization, supporting various probability distributions and crossover strategies.
202

203
```python { .api }
204
class Mutation:
205
    """Base mutation class."""
206

207
class DataMutation(Mutation):
208
    """Mutation operators for data parameters."""
209

210
class MutationChoice:
211
    """Choice-based mutation operators."""
212

213
class Cauchy(Mutation):
214
    """Cauchy distribution mutation."""
215

216
class Crossover(Mutation):
217
    """Crossover recombination operator."""
218

219
class RavelCrossover(Crossover):
220
    """Ravel-based crossover operation."""
221

222
class Translation(Mutation):
223
    """Translation mutation operator."""
224

225
class Jumping(Mutation):
226
    """Jumping mutation for exploration."""
227

228
class LocalGaussian(Mutation):
229
    """Local Gaussian mutation operator."""
230
```
231

232
### Helper Functions
233

234
Utility functions for parameter analysis, manipulation, and deterministic sampling that assist in parameter structure analysis and optimization debugging.
235

236
```python { .api }
237
def flatten(parameter: Parameter) -> List[Data]:
238
    """
239
    Flatten parameter structure to list.
240
    
241
    Args:
242
        parameter: Parameter to flatten
243
        
244
    Returns:
245
        List of all Data parameters in the structure
246
    """
247

248
def list_data(parameter: Parameter) -> List[Data]:
249
    """
250
    List all data parameters.
251
    
252
    Args:
253
        parameter: Parameter to analyze
254
        
255
    Returns:
256
        List of Data parameters
257
    """
258

259
def analyze(parameter: Parameter) -> Dict:
260
    """
261
    Analyze parameter structure.
262
    
263
    Args:
264
        parameter: Parameter to analyze
265
        
266
    Returns:
267
        Analysis dictionary with structure information
268
    """
269

270
def deterministic_sampling(parameter: Parameter) -> Iterator:
271
    """
272
    Deterministic sampling iterator.
273
    
274
    Args:
275
        parameter: Parameter to sample
276
        
277
    Returns:
278
        Iterator yielding deterministic samples
279
    """
280
```
281

282
## Usage Examples
283

284
### Creating Basic Parameters
285

286
```python
287
import nevergrad as ng
288

289
# Scalar parameter with bounds
290
scalar = ng.p.Scalar(init=1.0).set_bounds(-10, 10)
291

292
# Array parameter with shape
293
array = ng.p.Array(shape=(5, 3))
294

295
# Log-scale parameter
296
log_param = ng.p.Log(init=0.01, lower=1e-6, upper=1.0)
297

298
# Choice parameter
299
choice = ng.p.Choice(["option1", "option2", "option3"])
300
```
301

302
### Creating Complex Parameter Structures
303

304
```python
305
# Dictionary parameter with mixed types
306
param_dict = ng.p.Dict({
307
    "learning_rate": ng.p.Log(init=0.01, lower=1e-5, upper=1.0),
308
    "batch_size": ng.p.Choice([16, 32, 64, 128]),
309
    "layers": ng.p.Array(shape=(3,)).set_bounds(1, 1000).set_integer_casting()
310
})
311

312
# Function instrumentation
313
def train_model(lr, batch_size, epochs=100, optimizer="adam"):
314
    return lr * batch_size + epochs
315

316
# Create instrumentation for the function
317
instrum = ng.p.Instrumentation(
318
    lr=ng.p.Log(init=0.01, lower=1e-5, upper=1.0),
319
    batch_size=ng.p.Choice([16, 32, 64]),
320
    epochs=ng.p.Scalar(init=100).set_bounds(10, 1000).set_integer_casting(),
321
    optimizer=ng.p.Choice(["adam", "sgd", "rmsprop"])
322
)
323
```
324

325
### Parameter Mutation and Sampling
326

327
```python
328
# Create parameter and sample variations
329
param = ng.p.Array(shape=(10,))
330

331
# Get a sample
332
sample = param.sample()
333

334
# Mutate in place
335
param.mutate()
336

337
# Create child with new value
338
child = param.spawn_child()
339

340
# Recombine parameters
341
param1 = ng.p.Scalar(init=1.0)
342
param2 = ng.p.Scalar(init=2.0)
343
combined = param1.recombine(param2)
344
```