0
# Operations and Transformations
1

2
Specialized parameter operations including constraint handling, mutation operators for evolutionary algorithms, and parameter transformations for discrete optimization. The operations module provides advanced functionality for customizing optimization behavior beyond basic parametrization.
3

4
## Capabilities
5

6
### Constraint Handling
7

8
Apply optimization constraints to parameters using dedicated constraint functions that guide the optimization process towards feasible solutions.
9

10
```python { .api }
11
class Constraint:
12
    """
13
    Operator for applying constraints on Parameters during optimization.
14
    
15
    The constraint function should return positive values when constraints 
16
    are violated, and zero or negative values when constraints are satisfied.
17
    
18
    Parameters:
19
    - func: Constraint function that returns positive values for violations
20
    - optimizer: Optimizer name for constraint solving (str, default="NGOpt")
21
    - budget: Budget for constraint application (int, default=100)
22
    """
23
    
24
    def __init__(self, func: Callable, optimizer: str = "NGOpt", budget: int = 100):
25
        """Initialize constraint with function and solver parameters."""
26
    
27
    def __call__(self, parameter: Parameter) -> Parameter:
28
        """Apply constraint to parameter, returning constrained version."""
29
    
30
    def apply_constraint(self, parameter: Parameter) -> Parameter:
31
        """Find parameter that better satisfies the constraint."""
32
    
33
    def function(self, parameter: Parameter) -> float:
34
        """Wrapper ensuring constraint returns non-negative values."""
35
    
36
    def stopping_criterion(self, parameter: Parameter) -> bool:
37
        """Check if acceptable solution was found."""
38
```
39

40
### Mutation Operations
41

42
Advanced genetic operators for evolutionary algorithms, providing customizable mutation and recombination strategies for parameter evolution.
43

44
```python { .api }
45
class Mutation:
46
    """
47
    Base class for custom mutation and recombination operations.
48
    
49
    All mutations follow the pattern: mutation(parameter) or mutation()(parameter)
50
    """
51
    
52
    def __call__(self, parameter: Parameter, inplace: bool = False) -> Parameter:
53
        """Apply mutation to parameter."""
54
    
55
    def root(self) -> Parameter:
56
        """Get root parameter being mutated."""
57

58
class DataMutation(Mutation):
59
    """Base class for mutations that operate on Data parameters."""
60

61
class Crossover(DataMutation):
62
    """
63
    Array crossover operation that merges parts of arrays.
64
    
65
    Parameters:
66
    - axis: Axis along which to perform crossover (int, optional)
67
    - max_size: Maximum size for crossover segments (int, optional)
68
    - fft: Use FFT-based crossover (bool, default=False)
69
    """
70
    
71
    def __init__(self, axis: int = None, max_size: int = None, fft: bool = False):
72
        """Initialize crossover with parameters."""
73

74
class RavelCrossover(Crossover):
75
    """
76
    Crossover operation after flattening arrays.
77
    
78
    Parameters:
79
    - max_size: Maximum size for crossover segments (int, optional)
80
    """
81

82
class Translation(DataMutation):
83
    """
84
    Array translation that shifts elements along specified axes.
85
    
86
    Parameters:
87
    - axis: Axis or axes for translation (None, int, or iterable of ints)
88
    """
89
    
90
    def __init__(self, axis = None):
91
        """Initialize translation with axis specification."""
92

93
class Jumping(DataMutation):
94
    """
95
    Array jumping that moves chunks between positions.
96
    
97
    Parameters:
98
    - axis: Axis for jumping operation (int, optional)
99
    - size: Size of chunks to move (int, optional)
100
    """
101

102
class LocalGaussian(DataMutation):
103
    """
104
    Local Gaussian noise applied to specific regions.
105
    
106
    Parameters:
107
    - size: Size of local region (int, optional)
108
    - axes: Axes for local application (optional)
109
    """
110

111
class Cauchy(Mutation):
112
    """Cauchy mutation applied to entire parameter."""
113

114
class MutationChoice(DataMutation):
115
    """
116
    Selection between multiple mutations based on Choice parameter.
117
    
118
    Parameters:
119
    - mutations: List of mutation operations
120
    - with_default: Include default mutation (bool, default=True)
121
    """
122
```
123

124
### Integer Casting
125

126
Convert continuous parameters to discrete integer values with deterministic or probabilistic rounding strategies.
127

128
```python { .api }
129
def Int(deterministic: bool = True):
130
    """
131
    Cast Data parameters as integers or integer arrays.
132
    
133
    Parameters:
134
    - deterministic: Rounding strategy (bool, default=True)
135
        - True: Round to nearest integer
136
        - False: Probabilistic sampling of surrounding integers
137
    
138
    Returns:
139
        Function that applies integer casting to parameters
140
    
141
    Examples:
142
        Deterministic: 0.2 → 0, 0.8 → 1
143
        Probabilistic: 0.2 → 0 (80% chance) or 1 (20% chance)
144
    """
145
```
146

147
## Usage Examples
148

149
### Applying Constraints
150

151
```python
152
import nevergrad as ng
153

154
# Define constraint function (returns positive when violated)
155
def constraint_func(x):
156
    # Constraint: sum of squares should be <= 1
157
    return max(0, sum(x.value**2) - 1)
158

159
# Create constrained parameter
160
param = ng.p.Array(shape=(3,))
161
constrained_param = ng.ops.constraints.Constraint(constraint_func)(param)
162

163
# Use in optimization
164
optimizer = ng.optimizers.CMA(parametrization=constrained_param, budget=100)
165
```
166

167
### Custom Mutation Operations
168

169
```python
170
# Apply crossover mutation
171
param = ng.p.Array(shape=(10,))
172
mutated = ng.ops.mutations.Crossover(axis=0)(param)
173

174
# Apply translation along specific axis
175
translated = ng.ops.mutations.Translation(axis=1)(param)
176

177
# Apply local Gaussian noise
178
local_noise = ng.ops.mutations.LocalGaussian(size=3)(param)
179

180
# Chain multiple mutations
181
mutation_combo = ng.ops.mutations.MutationChoice([
182
    ng.ops.mutations.Crossover(),
183
    ng.ops.mutations.Translation(),
184
    ng.ops.mutations.Cauchy()
185
])
186
result = mutation_combo(param)
187
```
188

189
### Integer Parameter Casting
190

191
```python
192
# Deterministic integer casting
193
continuous_param = ng.p.Array(shape=(5,)).set_bounds(-10, 10)
194
integer_param = ng.ops.Int(deterministic=True)(continuous_param)
195

196
# Probabilistic integer casting
197
prob_integer = ng.ops.Int(deterministic=False)(continuous_param)
198

199
# Use in optimization
200
optimizer = ng.optimizers.DE(parametrization=integer_param, budget=50)
201

202
def discrete_function(x):
203
    # Function that works with integer inputs
204
    return sum(int(val)**2 for val in x.value)
205

206
recommendation = optimizer.minimize(discrete_function)
207
print(f"Best integer solution: {[int(x) for x in recommendation.value]}")
208
```
209

210
### Advanced Constraint Example
211

212
```python
213
# Multi-constraint optimization
214
def volume_constraint(x):
215
    # Volume must be positive
216
    return max(0, -x.value[0] * x.value[1] * x.value[2])
217

218
def surface_constraint(x):
219
    # Surface area must be <= 100
220
    a, b, c = x.value
221
    surface = 2 * (a*b + b*c + a*c)
222
    return max(0, surface - 100)
223

224
# Apply multiple constraints
225
param = ng.p.Array(shape=(3,)).set_bounds(0.1, 10)
226
constrained = ng.ops.constraints.Constraint(volume_constraint)(param)
227
constrained = ng.ops.constraints.Constraint(surface_constraint)(constrained)
228

229
# Optimize with constraints
230
optimizer = ng.optimizers.CMA(parametrization=constrained, budget=200)
231
```