0
# Type System and Error Handling
1
2
Rich type system with protocol definitions and comprehensive error handling for robust optimization workflows. Provides type safety, clear interfaces, and structured error reporting throughout the nevergrad ecosystem.
3
4
## Capabilities
5
6
### Core Type Definitions
7
8
Fundamental type aliases and protocol definitions that provide clear interfaces for optimization components and ensure type safety.
9
10
```python { .api }
11
# Nevergrad-specific type aliases
12
ArgsKwargs = Tuple[Tuple[Any, ...], Dict[str, Any]]
13
"""Type for function arguments and keyword arguments."""
14
15
ArrayLike = Union[Tuple[float, ...], List[float], np.ndarray]
16
"""Array-like structures for numerical data."""
17
18
PathLike = Union[str, Path]
19
"""Path-like objects for file system operations."""
20
21
FloatLoss = float
22
"""Single-objective loss value."""
23
24
Loss = Union[float, ArrayLike]
25
"""Single or multi-objective loss values."""
26
27
BoundValue = Optional[Union[float, int, np.int_, np.float64, ArrayLike]]
28
"""Bound values for parameter constraints."""
29
```
30
31
### Standard Python Types
32
33
Re-exported standard Python typing components for convenience and consistency across the nevergrad codebase.
34
35
```python { .api }
36
# Standard typing imports (re-exported)
37
Any: Type
38
Generic: Type
39
Type: Type
40
TypeVar: Type
41
Optional: Type
42
Union: Type
43
Dict: Type
44
Tuple: Type
45
List: Type
46
Set: Type
47
Deque: Type
48
Sequence: Type
49
NamedTuple: Type
50
MutableMapping: Type
51
Iterator: Type
52
Iterable: Type
53
Generator: Type
54
KeysView: Type
55
ValuesView: Type
56
ItemsView: Type
57
Callable: Type
58
Hashable: Type
59
Match: Type
60
Path: Type
61
Protocol: Type
62
63
def cast(typ: Type, val: Any) -> Any:
64
"""Type casting function."""
65
```
66
67
### Protocol Definitions
68
69
Protocol classes that define interfaces for job execution and parallel computation patterns used throughout nevergrad.
70
71
```python { .api }
72
class JobLike(Protocol[X]):
73
"""
74
Protocol for job-like objects with asynchronous execution capabilities.
75
76
Defines interface for objects that can be executed asynchronously
77
and provide completion status and result retrieval.
78
"""
79
80
def done(self) -> bool:
81
"""
82
Check if job execution is complete.
83
84
Returns:
85
True if job has finished execution
86
"""
87
88
def result(self) -> X:
89
"""
90
Get job execution result.
91
92
Returns:
93
Result of job execution
94
95
Raises:
96
Exception if job failed or is not yet complete
97
"""
98
99
class ExecutorLike(Protocol):
100
"""
101
Protocol for executor-like objects that can submit tasks for execution.
102
103
Defines interface for parallel execution frameworks compatible
104
with nevergrad's optimization workflows.
105
"""
106
107
def submit(self, fn: Callable, *args, **kwargs) -> JobLike:
108
"""
109
Submit function for execution.
110
111
Args:
112
fn: Function to execute
113
*args: Positional arguments for function
114
**kwargs: Keyword arguments for function
115
116
Returns:
117
Job-like object for tracking execution
118
"""
119
```
120
121
### Base Exception Classes
122
123
Foundation exception and warning classes that provide structured error handling throughout the nevergrad library.
124
125
```python { .api }
126
class NevergradError(Exception):
127
"""
128
Base exception class for all Nevergrad errors.
129
130
All custom exceptions in nevergrad inherit from this class,
131
enabling catch-all error handling for nevergrad-specific issues.
132
"""
133
134
class NevergradWarning(UserWarning):
135
"""
136
Base warning class for all Nevergrad warnings.
137
138
All custom warnings in nevergrad inherit from this class,
139
enabling structured warning handling and filtering.
140
"""
141
```
142
143
### Runtime Error Classes
144
145
Error classes for runtime issues and execution problems during optimization.
146
147
```python { .api }
148
class NevergradEarlyStopping(StopIteration, NevergradError):
149
"""
150
Stops the minimization loop when raised.
151
152
Used by early stopping mechanisms and convergence criteria
153
to cleanly terminate optimization runs.
154
"""
155
156
class NevergradRuntimeError(RuntimeError, NevergradError):
157
"""
158
Runtime errors raised by Nevergrad during execution.
159
160
Covers general runtime issues that occur during optimization
161
or parameter manipulation.
162
"""
163
164
class NevergradTypeError(TypeError, NevergradError):
165
"""
166
Type errors raised by Nevergrad for incorrect types.
167
168
Raised when function arguments or parameter types don't match
169
expected interfaces or protocols.
170
"""
171
172
class NevergradValueError(ValueError, NevergradError):
173
"""
174
Value errors raised by Nevergrad for incorrect values.
175
176
Raised when parameter values are outside valid ranges or
177
configuration settings are invalid.
178
"""
179
```
180
181
### Implementation Error Classes
182
183
Error classes for unimplemented functionality and unsupported operations.
184
185
```python { .api }
186
class NevergradNotImplementedError(NotImplementedError, NevergradError):
187
"""
188
Raised when functionality is not yet implemented.
189
190
Used for features that are planned but not yet available,
191
or abstract methods that must be implemented by subclasses.
192
"""
193
194
class TellNotAskedNotSupportedError(NevergradNotImplementedError):
195
"""
196
Raised by optimizers which do not support tell_not_asked interface.
197
198
Some optimizers cannot handle evaluation results for candidates
199
they did not generate through the ask() method.
200
"""
201
202
class ExperimentFunctionCopyError(NevergradNotImplementedError):
203
"""
204
Raised when experiment function fails to copy itself.
205
206
Occurs when benchmark functions cannot be properly serialized
207
or copied for parallel execution.
208
"""
209
210
class UnsupportedExperiment(unittest.SkipTest, NevergradRuntimeError):
211
"""
212
Raised if experiment is not compatible with current settings.
213
214
Used in benchmarking when experiment requirements don't match
215
the current execution environment or configuration.
216
"""
217
218
class NevergradDeprecationError(NevergradRuntimeError):
219
"""
220
Raised when deprecated functionality is used.
221
222
Indicates that code uses deprecated APIs that have been removed
223
or are no longer supported.
224
"""
225
226
class UnsupportedParameterOperationError(NevergradRuntimeError):
227
"""
228
Raised when operation is not supported by parameter type.
229
230
Occurs when attempting operations that are not valid for
231
specific parameter types (e.g., bounds on discrete parameters).
232
"""
233
```
234
235
### Warning Classes
236
237
Warning classes for non-fatal issues and optimization guidance.
238
239
```python { .api }
240
class NevergradDeprecationWarning(DeprecationWarning, NevergradWarning):
241
"""
242
Deprecated function/class warnings.
243
244
Issued when deprecated APIs are used but still functional,
245
providing migration guidance to users.
246
"""
247
248
class NevergradRuntimeWarning(RuntimeWarning, NevergradWarning):
249
"""
250
Runtime warnings raised by nevergrad.
251
252
General warnings about potentially problematic runtime conditions
253
or suboptimal configurations.
254
"""
255
256
class InefficientSettingsWarning(NevergradRuntimeWarning):
257
"""
258
Optimization settings are not optimal.
259
260
Warns when algorithm or parameter settings may lead to
261
poor optimization performance.
262
"""
263
264
class BadLossWarning(NevergradRuntimeWarning):
265
"""
266
Provided loss is unhelpful for optimization.
267
268
Issued when loss values are constant, infinite, or otherwise
269
don't provide optimization guidance.
270
"""
271
272
class LossTooLargeWarning(BadLossWarning):
273
"""
274
Loss is clipped because it is too large.
275
276
Warns when loss values exceed internal limits and are
277
automatically clipped to prevent numerical issues.
278
"""
279
280
class NevergradBehaviorChangesWarning(NevergradRuntimeWarning):
281
"""
282
Notifies about changes in nevergrad behavior.
283
284
Informs users about behavioral changes in algorithms or
285
interfaces that may affect existing code.
286
"""
287
288
class FinishedUnderlyingOptimizerWarning(NevergradRuntimeWarning):
289
"""
290
Underlying scipy optimizer finished early.
291
292
Warns when wrapped scipy optimizers terminate before
293
the allocated budget is exhausted.
294
"""
295
296
class FailedConstraintWarning(NevergradRuntimeWarning):
297
"""
298
Constraint could not be applied successfully.
299
300
Issued when constraint satisfaction fails or constraint
301
functions cannot be properly evaluated.
302
"""
303
```
304
305
## Usage Examples
306
307
### Type-Safe Function Definitions
308
309
```python
310
import nevergrad as ng
311
from nevergrad.typing import ArrayLike, Loss, ExecutorLike
312
313
def optimization_function(x: ArrayLike) -> Loss:
314
"""Type-safe optimization function."""
315
import numpy as np
316
return float(np.sum(np.array(x) ** 2))
317
318
def parallel_optimize(
319
function: Callable[[ArrayLike], Loss],
320
parametrization: ng.p.Parameter,
321
executor: ExecutorLike,
322
budget: int
323
) -> ng.p.Parameter:
324
"""Type-safe parallel optimization."""
325
optimizer = ng.optimizers.CMA(parametrization=parametrization, budget=budget)
326
327
jobs = []
328
for _ in range(budget):
329
x = optimizer.ask()
330
job = executor.submit(function, x.value)
331
jobs.append((x, job))
332
333
for x, job in jobs:
334
loss = job.result()
335
optimizer.tell(x, loss)
336
337
return optimizer.provide_recommendation()
338
```
339
340
### Comprehensive Error Handling
341
342
```python
343
import nevergrad as ng
344
from nevergrad import errors
345
346
def robust_optimization(function, parametrization, budget=100):
347
"""Optimization with comprehensive error handling."""
348
try:
349
optimizer = ng.optimizers.CMA(parametrization=parametrization, budget=budget)
350
351
for i in range(budget):
352
try:
353
x = optimizer.ask()
354
loss = function(x.value)
355
356
if not isinstance(loss, (int, float)):
357
raise errors.NevergradTypeError(f"Loss must be numeric, got {type(loss)}")
358
359
if loss != loss: # Check for NaN
360
raise errors.NevergradValueError("Loss is NaN")
361
362
optimizer.tell(x, loss)
363
364
except errors.NevergradEarlyStopping:
365
print(f"Early stopping at iteration {i}")
366
break
367
368
except errors.TellNotAskedNotSupportedError:
369
print("Optimizer doesn't support tell_not_asked, skipping...")
370
continue
371
372
except errors.UnsupportedParameterOperationError as e:
373
print(f"Parameter operation not supported: {e}")
374
continue
375
376
return optimizer.provide_recommendation()
377
378
except errors.NevergradRuntimeError as e:
379
print(f"Runtime error during optimization: {e}")
380
return None
381
382
except errors.NevergradError as e:
383
print(f"Nevergrad error: {e}")
384
return None
385
```
386
387
### Warning Handling
388
389
```python
390
import warnings
391
import nevergrad as ng
392
from nevergrad import errors
393
394
# Configure warning filters
395
warnings.filterwarnings("always", category=errors.InefficientSettingsWarning)
396
warnings.filterwarnings("ignore", category=errors.NevergradDeprecationWarning)
397
398
def optimization_with_warnings(function, parametrization):
399
"""Handle optimization warnings appropriately."""
400
401
with warnings.catch_warnings(record=True) as w:
402
warnings.simplefilter("always")
403
404
optimizer = ng.optimizers.CMA(parametrization=parametrization, budget=10)
405
result = optimizer.minimize(function)
406
407
# Process warnings
408
for warning in w:
409
if issubclass(warning.category, errors.InefficientSettingsWarning):
410
print(f"Efficiency warning: {warning.message}")
411
elif issubclass(warning.category, errors.BadLossWarning):
412
print(f"Loss warning: {warning.message}")
413
elif issubclass(warning.category, errors.NevergradBehaviorChangesWarning):
414
print(f"Behavior change: {warning.message}")
415
416
return result
417
```
418
419
### Custom Error Classes
420
421
```python
422
from nevergrad import errors
423
424
class CustomOptimizationError(errors.NevergradRuntimeError):
425
"""Custom error for specific optimization scenarios."""
426
pass
427
428
class ConvergenceFailedError(CustomOptimizationError):
429
"""Raised when optimization fails to converge."""
430
431
def __init__(self, iterations, tolerance):
432
super().__init__(f"Failed to converge after {iterations} iterations with tolerance {tolerance}")
433
self.iterations = iterations
434
self.tolerance = tolerance
435
436
def strict_optimization(function, parametrization, tolerance=1e-6):
437
"""Optimization with strict convergence requirements."""
438
optimizer = ng.optimizers.CMA(parametrization=parametrization, budget=1000)
439
440
prev_loss = float('inf')
441
patience = 0
442
max_patience = 50
443
444
for i in range(optimizer.budget):
445
x = optimizer.ask()
446
loss = function(x.value)
447
optimizer.tell(x, loss)
448
449
if abs(prev_loss - loss) < tolerance:
450
patience += 1
451
else:
452
patience = 0
453
454
if patience >= max_patience:
455
raise ConvergenceFailedError(i, tolerance)
456
457
prev_loss = loss
458
459
return optimizer.provide_recommendation()
460
```
461
462
### Protocol Implementation
463
464
```python
465
from nevergrad.typing import ExecutorLike, JobLike
466
from concurrent.futures import ThreadPoolExecutor, Future
467
468
class NevergradExecutor(ExecutorLike):
469
"""Custom executor implementation for nevergrad."""
470
471
def __init__(self, max_workers=4):
472
self.executor = ThreadPoolExecutor(max_workers=max_workers)
473
474
def submit(self, fn, *args, **kwargs) -> JobLike:
475
"""Submit function for execution."""
476
future = self.executor.submit(fn, *args, **kwargs)
477
return NevergradJob(future)
478
479
class NevergradJob(JobLike):
480
"""Job wrapper for Future objects."""
481
482
def __init__(self, future: Future):
483
self.future = future
484
485
def done(self) -> bool:
486
"""Check if job is complete."""
487
return self.future.done()
488
489
def result(self):
490
"""Get job result."""
491
return self.future.result()
492
493
# Usage with custom executor
494
executor = NevergradExecutor(max_workers=8)
495
result = parallel_optimize(sphere_function, parametrization, executor, budget=100)
496
```