hone-python 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hone/__init__.py +5 -0
- hone/sensitivity_analysis.py +523 -0
- {hone_python-0.12.2.dist-info → hone_python-0.13.0.dist-info}/METADATA +29 -1
- {hone_python-0.12.2.dist-info → hone_python-0.13.0.dist-info}/RECORD +6 -5
- {hone_python-0.12.2.dist-info → hone_python-0.13.0.dist-info}/WHEEL +0 -0
- {hone_python-0.12.2.dist-info → hone_python-0.13.0.dist-info}/licenses/LICENSE +0 -0
hone/__init__.py
CHANGED
|
@@ -18,6 +18,7 @@ from hone.optimizers import (
|
|
|
18
18
|
from hone.parameters import ChoiceParameter, Condition, Constraint, FixedParameter, InfeasibleSearchSpace, RangeParameter, SearchSpace
|
|
19
19
|
from hone.pareto import Front, ParetoGenerationStats, ParetoPoint, ParetoProgress, ParetoResult
|
|
20
20
|
from hone.result import GenerationStats, Progress, Result, RunInfo, print_progress
|
|
21
|
+
from hone.sensitivity_analysis import Interval, ParameterSensitivity, SensitivityReport, sensitivity
|
|
21
22
|
|
|
22
23
|
__all__ = [
|
|
23
24
|
"BayesianConfig",
|
|
@@ -36,6 +37,7 @@ __all__ = [
|
|
|
36
37
|
"GeneticOptimizer",
|
|
37
38
|
"GeneticOptimizerConfig",
|
|
38
39
|
"InfeasibleSearchSpace",
|
|
40
|
+
"Interval",
|
|
39
41
|
"MultiObjectiveBayesian",
|
|
40
42
|
"MultiObjectiveBayesianConfig",
|
|
41
43
|
"MultiObjectiveConfig",
|
|
@@ -45,6 +47,7 @@ __all__ = [
|
|
|
45
47
|
"NSGA2Config",
|
|
46
48
|
"Optimizer",
|
|
47
49
|
"OptimizerConfig",
|
|
50
|
+
"ParameterSensitivity",
|
|
48
51
|
"ParetoGenerationStats",
|
|
49
52
|
"ParetoPoint",
|
|
50
53
|
"ParetoProgress",
|
|
@@ -57,6 +60,8 @@ __all__ = [
|
|
|
57
60
|
"RunInfo",
|
|
58
61
|
"SearchSpace",
|
|
59
62
|
"SelectionMethod",
|
|
63
|
+
"sensitivity",
|
|
64
|
+
"SensitivityReport",
|
|
60
65
|
"Trial",
|
|
61
66
|
"UnsupportedSearchSpace",
|
|
62
67
|
]
|
|
@@ -0,0 +1,523 @@
|
|
|
1
|
+
"""Which parameters matter: global sensitivity analysis, before or instead of optimizing.
|
|
2
|
+
|
|
3
|
+
sensitivity() evaluates the objective at points chosen to measure each parameter's effect,
|
|
4
|
+
through the same workers, time limits and failure handling as optimize(), and reports each
|
|
5
|
+
parameter's importance. On small budgets it uses Morris screening, which ranks the
|
|
6
|
+
parameters; on larger ones Sobol indices, which say what share of the objective's variance
|
|
7
|
+
each parameter accounts for, alone and with its interactions.
|
|
8
|
+
|
|
9
|
+
Every parameter is measured on the scale the optimizers search it on: a log range evenly in
|
|
10
|
+
its logarithm, an integer range rounded, and a choice parameter by picking among its choices,
|
|
11
|
+
so an effect is the change across the parameter's whole range. Fixed parameters aren't
|
|
12
|
+
measured. A parameter a condition switches off isn't passed to the objective at that point,
|
|
13
|
+
so it has no effect there, which its indices include.
|
|
14
|
+
"""
|
|
15
|
+
import math
|
|
16
|
+
from functools import partial
|
|
17
|
+
from typing import Any, Callable, Literal, Sequence
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
from pydantic import BaseModel, ConfigDict
|
|
21
|
+
from scipy.stats import qmc
|
|
22
|
+
|
|
23
|
+
from hone.objective_function import ObjectiveFunction
|
|
24
|
+
from hone.optimizers.core import UnsupportedSearchSpace, _evaluate
|
|
25
|
+
from hone.optimizers._pool import EvaluationPool
|
|
26
|
+
from hone.parameters import ChoiceParameter, FixedParameter, Parameter, RangeParameter, SearchSpace
|
|
27
|
+
|
|
28
|
+
type Method = Literal["morris", "sobol"]
|
|
29
|
+
|
|
30
|
+
MORRIS_LEVELS = 4 # grid levels per parameter; the step is half the grid, so each level pairs with another
|
|
31
|
+
MORRIS_STEP = MORRIS_LEVELS / (2 * (MORRIS_LEVELS - 1)) # 2/3 of the range
|
|
32
|
+
MIN_TRAJECTORIES = 2 # Morris needs at least two trajectories to estimate sigma
|
|
33
|
+
MIN_SOBOL_SAMPLES = 16 # Sobol rows below which its indices are too noisy to report
|
|
34
|
+
AUTO_SOBOL_SAMPLES = 64 # rows at which sensitivity() picks Sobol over Morris by itself
|
|
35
|
+
BOOTSTRAP_RESAMPLES = 1000
|
|
36
|
+
DEFAULT_SOBOL_THRESHOLD = 0.05 # a total index below which reduced() fixes a parameter
|
|
37
|
+
DEFAULT_MORRIS_THRESHOLD = 0.1 # a share of the largest mu_star below which reduced() fixes a parameter
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class Interval(BaseModel):
|
|
41
|
+
"""A confidence interval."""
|
|
42
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
43
|
+
|
|
44
|
+
low: float
|
|
45
|
+
"""The lower end."""
|
|
46
|
+
high: float
|
|
47
|
+
"""The upper end."""
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class ParameterSensitivity(BaseModel):
|
|
51
|
+
"""How much one parameter matters.
|
|
52
|
+
|
|
53
|
+
importance ranks the parameters: mu_star for Morris, the total index for Sobol. The
|
|
54
|
+
other fields are None for the method that wasn't used.
|
|
55
|
+
"""
|
|
56
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
57
|
+
|
|
58
|
+
name: str
|
|
59
|
+
"""The parameter's name."""
|
|
60
|
+
importance: float
|
|
61
|
+
"""mu_star for Morris, the total index for Sobol."""
|
|
62
|
+
interval: Interval | None = None
|
|
63
|
+
"""The confidence interval of importance; None when too few evaluations succeeded to estimate it."""
|
|
64
|
+
mu_star: float | None = None
|
|
65
|
+
"""Morris: the mean size of the parameter's effect, the change in the objective across its whole
|
|
66
|
+
range, whichever way it goes. Small means the parameter barely matters."""
|
|
67
|
+
mu: float | None = None
|
|
68
|
+
"""Morris: the mean effect with its sign. Well below mu_star means the effect changes direction."""
|
|
69
|
+
sigma: float | None = None
|
|
70
|
+
"""Morris: the standard deviation of the effect. Large against mu_star means the effect depends on
|
|
71
|
+
the other parameters, through interactions or a curved response."""
|
|
72
|
+
first: float | None = None
|
|
73
|
+
"""Sobol: the share of the objective's variance the parameter accounts for alone."""
|
|
74
|
+
first_interval: Interval | None = None
|
|
75
|
+
"""Sobol: the confidence interval of first."""
|
|
76
|
+
total: float | None = None
|
|
77
|
+
"""Sobol: the share of the variance the parameter accounts for with all its interactions; near 0
|
|
78
|
+
means it can be fixed at any value with little effect. Estimates can fall slightly below 0."""
|
|
79
|
+
total_interval: Interval | None = None
|
|
80
|
+
"""Sobol: the confidence interval of total, the same as interval."""
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class SensitivityReport(BaseModel):
|
|
84
|
+
"""What sensitivity() measured: each parameter's importance, most important first."""
|
|
85
|
+
model_config = ConfigDict(frozen=True, use_attribute_docstrings=True)
|
|
86
|
+
|
|
87
|
+
method: Method
|
|
88
|
+
"""How the parameters were measured: "morris" or "sobol"."""
|
|
89
|
+
parameters: list[ParameterSensitivity]
|
|
90
|
+
"""Each parameter measured, most important first."""
|
|
91
|
+
evaluations: int
|
|
92
|
+
"""Evaluations made, failed ones included."""
|
|
93
|
+
failures: int
|
|
94
|
+
"""Evaluations that failed, timed out or crashed their worker."""
|
|
95
|
+
confidence: float
|
|
96
|
+
"""The confidence level of the intervals."""
|
|
97
|
+
best_params: dict[str, Any] | None
|
|
98
|
+
"""The best point evaluated, as the objective was called with it; None if every evaluation failed."""
|
|
99
|
+
best_value: float | None
|
|
100
|
+
"""The objective's value at best_params; None if every evaluation failed."""
|
|
101
|
+
maximize: bool
|
|
102
|
+
"""Whether higher values were counted as better in choosing best_params."""
|
|
103
|
+
|
|
104
|
+
@property
|
|
105
|
+
def ranking(self) -> list[str]:
|
|
106
|
+
"""The parameters' names, most important first."""
|
|
107
|
+
return [parameter.name for parameter in self.parameters]
|
|
108
|
+
|
|
109
|
+
def __getitem__(self, name: str) -> ParameterSensitivity:
|
|
110
|
+
for parameter in self.parameters:
|
|
111
|
+
if parameter.name == name:
|
|
112
|
+
return parameter
|
|
113
|
+
raise KeyError(name)
|
|
114
|
+
|
|
115
|
+
def unimportant(self, threshold: float | None = None) -> list[str]:
|
|
116
|
+
"""The parameters that can be fixed with little effect: those whose whole interval is below threshold.
|
|
117
|
+
|
|
118
|
+
For Sobol, threshold is a total index, 0.05 unless given: the parameter accounts for
|
|
119
|
+
under 5% of the objective's variance, interactions included. For Morris it is a share of
|
|
120
|
+
the largest mu_star, 0.1 unless given. Only the upper end of each interval is compared,
|
|
121
|
+
so a parameter whose importance is uncertain is kept. A parameter without an interval,
|
|
122
|
+
because too few of its evaluations succeeded, is kept too.
|
|
123
|
+
"""
|
|
124
|
+
if threshold is None:
|
|
125
|
+
threshold = DEFAULT_SOBOL_THRESHOLD if self.method == "sobol" else DEFAULT_MORRIS_THRESHOLD
|
|
126
|
+
if threshold < 0:
|
|
127
|
+
raise ValueError(f"threshold must be at least 0, got {threshold}")
|
|
128
|
+
if self.method == "morris":
|
|
129
|
+
largest = max((p.importance for p in self.parameters if math.isfinite(p.importance)), default=0.0)
|
|
130
|
+
threshold *= largest
|
|
131
|
+
return [p.name for p in self.parameters if p.interval is not None and p.interval.high < threshold]
|
|
132
|
+
|
|
133
|
+
def reduced(
|
|
134
|
+
self,
|
|
135
|
+
search_space: SearchSpace | Sequence[Parameter],
|
|
136
|
+
*,
|
|
137
|
+
threshold: float | None = None,
|
|
138
|
+
keep: int | None = None,
|
|
139
|
+
at: dict[str, Any] | None = None,
|
|
140
|
+
) -> SearchSpace:
|
|
141
|
+
"""The search space with its unimportant parameters fixed, ready for choose_optimizer.
|
|
142
|
+
|
|
143
|
+
The parameters unimportant() names are fixed, or with keep, every parameter but the
|
|
144
|
+
keep most important. Each is fixed at its value in at, if given, and otherwise at the best
|
|
145
|
+
point evaluated; one the conditions switched off there, or every parameter if every
|
|
146
|
+
evaluation failed, is fixed at the middle of its range, or its middle choice.
|
|
147
|
+
|
|
148
|
+
A fixed parameter is still passed to the objective, so the objective doesn't change.
|
|
149
|
+
Conditions and constraints are kept: a parameter one of them tests stays a range or
|
|
150
|
+
choice parameter, narrowed to its one value, so they still apply.
|
|
151
|
+
|
|
152
|
+
Args:
|
|
153
|
+
search_space: The search space the report measured.
|
|
154
|
+
threshold: Passed to unimportant(). Not with keep.
|
|
155
|
+
keep: Keep this many of the most important parameters, and fix the rest.
|
|
156
|
+
at: Values to fix parameters at, by name.
|
|
157
|
+
"""
|
|
158
|
+
space = search_space if isinstance(search_space, SearchSpace) else SearchSpace(search_space)
|
|
159
|
+
measured = [p.name for p in space.parameters if not isinstance(p, FixedParameter)]
|
|
160
|
+
if sorted(measured) != sorted(self.ranking):
|
|
161
|
+
raise ValueError(f"this report measured {', '.join(self.ranking)}, but the search space's parameters are {', '.join(measured)}")
|
|
162
|
+
if keep is not None:
|
|
163
|
+
if threshold is not None:
|
|
164
|
+
raise ValueError("give threshold or keep, not both")
|
|
165
|
+
if keep < 1:
|
|
166
|
+
raise ValueError(f"keep must be at least 1, got {keep}")
|
|
167
|
+
dropped = self.ranking[keep:]
|
|
168
|
+
else:
|
|
169
|
+
dropped = self.unimportant(threshold)
|
|
170
|
+
unknown = sorted(set(at or {}) - set(space.names))
|
|
171
|
+
if unknown:
|
|
172
|
+
raise ValueError(f"at names parameters the search space doesn't have: {', '.join(unknown)}")
|
|
173
|
+
tested = {name for c in space.conditions for name in c.when.names()} | {name for c in space.constraints for name in c.names()}
|
|
174
|
+
parameters = []
|
|
175
|
+
for parameter in space.parameters:
|
|
176
|
+
if parameter.name not in dropped:
|
|
177
|
+
parameters.append(parameter)
|
|
178
|
+
continue
|
|
179
|
+
if at is not None and parameter.name in at:
|
|
180
|
+
value = parameter.check(at[parameter.name])
|
|
181
|
+
elif self.best_params is not None and parameter.name in self.best_params:
|
|
182
|
+
value = self.best_params[parameter.name]
|
|
183
|
+
else:
|
|
184
|
+
value = _from_unit(parameter, 0.5)
|
|
185
|
+
parameters.append(_fixed(parameter, value, keep_kind=parameter.name in tested))
|
|
186
|
+
return SearchSpace(parameters, space.constraints, space.conditions)
|
|
187
|
+
|
|
188
|
+
def __str__(self) -> str:
|
|
189
|
+
if self.method == "morris":
|
|
190
|
+
header = ("parameter", "mu_star", "interval", "mu", "sigma")
|
|
191
|
+
rows = [
|
|
192
|
+
(p.name, _number(p.mu_star), _interval(p.interval), _number(p.mu), _number(p.sigma))
|
|
193
|
+
for p in self.parameters
|
|
194
|
+
]
|
|
195
|
+
else:
|
|
196
|
+
header = ("parameter", "total", "interval", "first", "interval")
|
|
197
|
+
rows = [
|
|
198
|
+
(p.name, _number(p.total), _interval(p.total_interval), _number(p.first), _interval(p.first_interval))
|
|
199
|
+
for p in self.parameters
|
|
200
|
+
]
|
|
201
|
+
widths = [max(len(row[i]) for row in [header, *rows]) for i in range(len(header))]
|
|
202
|
+
lines = [
|
|
203
|
+
f"{'Morris screening' if self.method == 'morris' else 'Sobol indices'}: {self.evaluations} evaluations, "
|
|
204
|
+
f"{self.failures} failed; {self.confidence:.0%} intervals"
|
|
205
|
+
]
|
|
206
|
+
for row in [header, *rows]:
|
|
207
|
+
lines.append(" ".join(cell.ljust(width) if i == 0 else cell.rjust(width) for i, (cell, width) in enumerate(zip(row, widths))))
|
|
208
|
+
return "\n".join(lines)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def sensitivity(
|
|
212
|
+
objective_function: Callable,
|
|
213
|
+
search_space: SearchSpace | Sequence[Parameter],
|
|
214
|
+
*,
|
|
215
|
+
max_evaluations: int = 500,
|
|
216
|
+
method: Method | None = None,
|
|
217
|
+
maximize: bool = False,
|
|
218
|
+
seed: int | None = None,
|
|
219
|
+
workers: int = 1,
|
|
220
|
+
timeout: float | None = None,
|
|
221
|
+
confidence: float = 0.95,
|
|
222
|
+
) -> SensitivityReport:
|
|
223
|
+
"""Measure how much each parameter of the search space matters to the objective.
|
|
224
|
+
|
|
225
|
+
Morris screening needs about 10 × (parameters + 1) evaluations to rank the parameters.
|
|
226
|
+
Sobol indices need about 64 × (parameters + 2) or more, and say what share of the
|
|
227
|
+
objective's variance each parameter accounts for. Without method, Sobol is used when
|
|
228
|
+
max_evaluations allows it, and Morris otherwise. Neither uses more than max_evaluations.
|
|
229
|
+
|
|
230
|
+
The objective is called as optimize() calls it: with one keyword argument per parameter
|
|
231
|
+
switched on, raising EvaluationFailed or returning NaN or infinity to record a failed
|
|
232
|
+
evaluation. Failed evaluations are left out of the indices.
|
|
233
|
+
|
|
234
|
+
Args:
|
|
235
|
+
objective_function: The function to measure.
|
|
236
|
+
search_space: The parameters, with any conditions; constraints aren't supported yet.
|
|
237
|
+
max_evaluations: The most evaluations to make.
|
|
238
|
+
method: "morris" or "sobol", rather than choosing from max_evaluations.
|
|
239
|
+
maximize: Whether higher values are better, which only decides best_params.
|
|
240
|
+
seed: Fixes the points evaluated and the intervals, so a run can be repeated.
|
|
241
|
+
workers: Evaluate this many points at once in background processes.
|
|
242
|
+
timeout: The longest, in seconds, one evaluation may take, as in optimize().
|
|
243
|
+
confidence: The confidence level of the intervals, from bootstrapping.
|
|
244
|
+
|
|
245
|
+
With workers > 1 or a timeout, each evaluation runs in a separate process, so the
|
|
246
|
+
function must be defined at the top level of a module.
|
|
247
|
+
"""
|
|
248
|
+
space = search_space if isinstance(search_space, SearchSpace) else SearchSpace(search_space)
|
|
249
|
+
if space.constraints:
|
|
250
|
+
raise UnsupportedSearchSpace(
|
|
251
|
+
"sensitivity() doesn't support constraints yet: Morris and Sobol assume each parameter can take any of its "
|
|
252
|
+
"values whatever the others are"
|
|
253
|
+
)
|
|
254
|
+
if workers < 1:
|
|
255
|
+
raise ValueError(f"workers must be at least 1, got {workers}")
|
|
256
|
+
if timeout is not None and timeout <= 0:
|
|
257
|
+
raise ValueError(f"timeout must be positive, got {timeout}")
|
|
258
|
+
if not 0 < confidence < 1:
|
|
259
|
+
raise ValueError(f"confidence must be between 0 and 1, got {confidence}")
|
|
260
|
+
measured = [parameter for parameter in space.parameters if not isinstance(parameter, FixedParameter)]
|
|
261
|
+
if not measured:
|
|
262
|
+
raise ValueError("every parameter is fixed, so there is nothing to measure")
|
|
263
|
+
k = len(measured)
|
|
264
|
+
method = method or ("sobol" if _sobol_samples(max_evaluations, k) >= AUTO_SOBOL_SAMPLES else "morris")
|
|
265
|
+
if method not in ("morris", "sobol"):
|
|
266
|
+
raise ValueError(f"method must be 'morris' or 'sobol', got {method!r}")
|
|
267
|
+
rng = np.random.default_rng(seed)
|
|
268
|
+
|
|
269
|
+
if method == "morris":
|
|
270
|
+
trajectories = max_evaluations // (k + 1)
|
|
271
|
+
if trajectories < MIN_TRAJECTORIES:
|
|
272
|
+
raise ValueError(
|
|
273
|
+
f"Morris screening of {k} parameters needs at least {MIN_TRAJECTORIES * (k + 1)} evaluations, "
|
|
274
|
+
f"and about {10 * (k + 1)} to rank them reliably; max_evaluations is {max_evaluations}"
|
|
275
|
+
)
|
|
276
|
+
units, steps = _morris_design(trajectories, k, rng)
|
|
277
|
+
else:
|
|
278
|
+
n = _sobol_samples(max_evaluations, k)
|
|
279
|
+
if n < MIN_SOBOL_SAMPLES:
|
|
280
|
+
raise ValueError(
|
|
281
|
+
f"Sobol indices of {k} parameters need at least {MIN_SOBOL_SAMPLES * (k + 2)} evaluations, "
|
|
282
|
+
f"and about {AUTO_SOBOL_SAMPLES * (k + 2)} to be reliable; max_evaluations is {max_evaluations}. "
|
|
283
|
+
"method='morris' ranks the parameters with fewer"
|
|
284
|
+
)
|
|
285
|
+
units = _sobol_design(n, k, rng)
|
|
286
|
+
|
|
287
|
+
points = [_point(space, measured, row) for row in units]
|
|
288
|
+
values = _evaluate_all(objective_function, space, points, workers, timeout)
|
|
289
|
+
ok = np.isfinite(values)
|
|
290
|
+
|
|
291
|
+
if method == "morris":
|
|
292
|
+
results = _morris_indices(measured, values, steps, confidence, rng)
|
|
293
|
+
else:
|
|
294
|
+
results = _sobol_indices(measured, values, n, confidence, rng)
|
|
295
|
+
results.sort(key=lambda parameter: -parameter.importance if math.isfinite(parameter.importance) else math.inf)
|
|
296
|
+
|
|
297
|
+
best_params, best_value = None, None
|
|
298
|
+
if ok.any():
|
|
299
|
+
best = int(np.nanargmax(values) if maximize else np.nanargmin(values))
|
|
300
|
+
best_params, best_value = space.active(points[best]), float(values[best])
|
|
301
|
+
return SensitivityReport(
|
|
302
|
+
method=method,
|
|
303
|
+
parameters=results,
|
|
304
|
+
evaluations=len(points),
|
|
305
|
+
failures=int((~ok).sum()),
|
|
306
|
+
confidence=confidence,
|
|
307
|
+
best_params=best_params,
|
|
308
|
+
best_value=best_value,
|
|
309
|
+
maximize=maximize,
|
|
310
|
+
)
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
# --- from the unit cube to points ----------------------------------------------
|
|
314
|
+
|
|
315
|
+
|
|
316
|
+
def _point(space: SearchSpace, measured: Sequence[Parameter], unit: np.ndarray) -> dict[str, Any]:
|
|
317
|
+
"""The point of space at position unit, one coordinate in [0, 1] per measured parameter."""
|
|
318
|
+
values = {parameter.name: _from_unit(parameter, float(u)) for parameter, u in zip(measured, unit)}
|
|
319
|
+
return {
|
|
320
|
+
parameter.name: parameter.value if isinstance(parameter, FixedParameter) else values[parameter.name]
|
|
321
|
+
for parameter in space.parameters
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _from_unit(parameter: Parameter, u: float) -> Any:
|
|
326
|
+
"""The parameter's value at u in [0, 1], on the scale the optimizers search it on."""
|
|
327
|
+
if isinstance(parameter, RangeParameter):
|
|
328
|
+
return parameter.from_unit(u)
|
|
329
|
+
assert isinstance(parameter, ChoiceParameter)
|
|
330
|
+
if parameter.choose_n is None:
|
|
331
|
+
return parameter.choices[min(int(u * len(parameter.choices)), len(parameter.choices) - 1)]
|
|
332
|
+
count = math.comb(len(parameter.choices), parameter.choose_n)
|
|
333
|
+
indices = _unrank_combination(min(int(u * count), count - 1), len(parameter.choices), parameter.choose_n)
|
|
334
|
+
return [parameter.choices[i] for i in indices]
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
def _fixed(parameter: Parameter, value: Any, keep_kind: bool) -> Parameter:
|
|
338
|
+
"""parameter held at value: a FixedParameter, or with keep_kind, a range or choice of that one value."""
|
|
339
|
+
if isinstance(parameter, RangeParameter):
|
|
340
|
+
if keep_kind:
|
|
341
|
+
return RangeParameter(parameter.name, value, value, integer=parameter.integer, log=parameter.log)
|
|
342
|
+
return FixedParameter(parameter.name, value)
|
|
343
|
+
assert isinstance(parameter, ChoiceParameter)
|
|
344
|
+
if parameter.choose_n is not None:
|
|
345
|
+
return ChoiceParameter(parameter.name, list(value), choose_n=parameter.choose_n)
|
|
346
|
+
return ChoiceParameter(parameter.name, [value]) if keep_kind else FixedParameter(parameter.name, value)
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def _unrank_combination(rank: int, n: int, k: int) -> list[int]:
|
|
350
|
+
"""The rank-th k-element subset of range(n), in lexicographic order."""
|
|
351
|
+
chosen: list[int] = []
|
|
352
|
+
candidate = 0
|
|
353
|
+
while len(chosen) < k:
|
|
354
|
+
with_candidate = math.comb(n - candidate - 1, k - len(chosen) - 1)
|
|
355
|
+
if rank < with_candidate:
|
|
356
|
+
chosen.append(candidate)
|
|
357
|
+
else:
|
|
358
|
+
rank -= with_candidate
|
|
359
|
+
candidate += 1
|
|
360
|
+
return chosen
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _evaluate_all(
|
|
364
|
+
objective_function: Callable, space: SearchSpace, points: list[dict[str, Any]], workers: int, timeout: float | None
|
|
365
|
+
) -> np.ndarray:
|
|
366
|
+
"""Each point's value, NaN where the evaluation failed, as optimize() evaluates them."""
|
|
367
|
+
objective = ObjectiveFunction(
|
|
368
|
+
name=getattr(objective_function, "__name__", "objective"), function=objective_function, search_space=space
|
|
369
|
+
)
|
|
370
|
+
evaluate = partial(_evaluate, objective)
|
|
371
|
+
called = [space.active(point) for point in points]
|
|
372
|
+
if workers == 1 and timeout is None:
|
|
373
|
+
outcomes = [evaluate(point) for point in called]
|
|
374
|
+
else:
|
|
375
|
+
with EvaluationPool(evaluate, workers, timeout) as pool:
|
|
376
|
+
outcomes = pool.map(called)
|
|
377
|
+
values = np.array([math.nan if outcome is None else outcome for outcome in outcomes], dtype=float)
|
|
378
|
+
values[~np.isfinite(values)] = math.nan
|
|
379
|
+
return values
|
|
380
|
+
|
|
381
|
+
|
|
382
|
+
# --- Morris screening ------------------------------------------------------------
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
def _morris_design(trajectories: int, k: int, rng: np.random.Generator) -> tuple[np.ndarray, list[list[tuple[int, int, float]]]]:
|
|
386
|
+
"""Morris's one-at-a-time trajectories through a grid of MORRIS_LEVELS levels.
|
|
387
|
+
|
|
388
|
+
Returns the points, trajectories × (k + 1) rows of k unit coordinates, and for each
|
|
389
|
+
trajectory its steps: (parameter, row it steps from, signed step size).
|
|
390
|
+
"""
|
|
391
|
+
levels = np.arange(MORRIS_LEVELS) / (MORRIS_LEVELS - 1)
|
|
392
|
+
rows: list[np.ndarray] = []
|
|
393
|
+
steps: list[list[tuple[int, int, float]]] = []
|
|
394
|
+
for _ in range(trajectories):
|
|
395
|
+
x = rng.choice(levels, size=k)
|
|
396
|
+
start = len(rows)
|
|
397
|
+
rows.append(x.copy())
|
|
398
|
+
trajectory = []
|
|
399
|
+
for position, i in enumerate(rng.permutation(k)):
|
|
400
|
+
step = MORRIS_STEP if x[i] + MORRIS_STEP <= 1 + 1e-12 else -MORRIS_STEP
|
|
401
|
+
x[i] = round(x[i] + step, 12)
|
|
402
|
+
rows.append(x.copy())
|
|
403
|
+
trajectory.append((int(i), start + position, step))
|
|
404
|
+
steps.append(trajectory)
|
|
405
|
+
return np.array(rows), steps
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
def _morris_indices(
|
|
409
|
+
measured: Sequence[Parameter], values: np.ndarray, steps: list[list[tuple[int, int, float]]], confidence: float, rng: np.random.Generator
|
|
410
|
+
) -> list[ParameterSensitivity]:
|
|
411
|
+
effects: list[list[float]] = [[] for _ in measured]
|
|
412
|
+
for trajectory in steps:
|
|
413
|
+
for i, row, step in trajectory:
|
|
414
|
+
before, after = values[row], values[row + 1]
|
|
415
|
+
if math.isfinite(before) and math.isfinite(after):
|
|
416
|
+
effects[i].append((after - before) / step)
|
|
417
|
+
results = []
|
|
418
|
+
for parameter, found in zip(measured, effects):
|
|
419
|
+
e = np.array(found)
|
|
420
|
+
if not len(e):
|
|
421
|
+
results.append(ParameterSensitivity(name=parameter.name, importance=math.nan))
|
|
422
|
+
continue
|
|
423
|
+
mu_star = float(np.mean(np.abs(e)))
|
|
424
|
+
interval = None
|
|
425
|
+
if len(e) >= 2:
|
|
426
|
+
resampled = np.abs(e[rng.integers(len(e), size=(BOOTSTRAP_RESAMPLES, len(e)))]).mean(axis=1)
|
|
427
|
+
interval = _percentiles(resampled, confidence)
|
|
428
|
+
results.append(
|
|
429
|
+
ParameterSensitivity(
|
|
430
|
+
name=parameter.name,
|
|
431
|
+
importance=mu_star,
|
|
432
|
+
interval=interval,
|
|
433
|
+
mu_star=mu_star,
|
|
434
|
+
mu=float(np.mean(e)),
|
|
435
|
+
sigma=float(np.std(e, ddof=1)) if len(e) >= 2 else None,
|
|
436
|
+
)
|
|
437
|
+
)
|
|
438
|
+
return results
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
# --- Sobol indices -----------------------------------------------------------------
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
def _sobol_samples(max_evaluations: int, k: int) -> int:
|
|
445
|
+
"""The most rows of Sobol's design that fit in max_evaluations: a power of 2, as its sequence needs."""
|
|
446
|
+
rows = max_evaluations // (k + 2)
|
|
447
|
+
return 2 ** int(math.log2(rows)) if rows >= 1 else 0
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
def _sobol_design(n: int, k: int, rng: np.random.Generator) -> np.ndarray:
|
|
451
|
+
"""Saltelli's design: matrices A and B, then for each parameter A with that column from B.
|
|
452
|
+
|
|
453
|
+
A and B are the two halves of one scrambled Sobol sequence of 2k dimensions, as scipy's
|
|
454
|
+
sobol_indices draws them. Returns the (k + 2) n rows in that order.
|
|
455
|
+
"""
|
|
456
|
+
a_b = qmc.Sobol(d=2 * k, scramble=True, seed=rng).random(n)
|
|
457
|
+
a, b = a_b[:, :k], a_b[:, k:]
|
|
458
|
+
blocks = [a, b]
|
|
459
|
+
for i in range(k):
|
|
460
|
+
ab = a.copy()
|
|
461
|
+
ab[:, i] = b[:, i]
|
|
462
|
+
blocks.append(ab)
|
|
463
|
+
return np.vstack(blocks)
|
|
464
|
+
|
|
465
|
+
|
|
466
|
+
def _saltelli(f_a: np.ndarray, f_b: np.ndarray, f_ab: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
|
|
467
|
+
"""First and total indices by Saltelli et al. (2010), as scipy's sobol_indices computes them.
|
|
468
|
+
|
|
469
|
+
The last axis is the rows; f_ab has one more leading axis, the parameter.
|
|
470
|
+
"""
|
|
471
|
+
mean = np.mean([f_a, f_b], axis=(0, -1), keepdims=True)[0]
|
|
472
|
+
f_a, f_b, f_ab = f_a - mean, f_b - mean, f_ab - mean
|
|
473
|
+
var = np.var([f_a, f_b], axis=(0, -1))
|
|
474
|
+
with np.errstate(divide="ignore", invalid="ignore"):
|
|
475
|
+
first = np.mean(f_b * (f_ab - f_a), axis=-1) / var
|
|
476
|
+
total = 0.5 * np.mean((f_a - f_ab) ** 2, axis=-1) / var
|
|
477
|
+
# An objective that doesn't vary has no variance to share out.
|
|
478
|
+
return np.where(np.isfinite(first), first, 0.0), np.where(np.isfinite(total), total, 0.0)
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
def _sobol_indices(measured: Sequence[Parameter], values: np.ndarray, n: int, confidence: float, rng: np.random.Generator) -> list[ParameterSensitivity]:
|
|
482
|
+
k = len(measured)
|
|
483
|
+
f_a, f_b = values[:n], values[n:2 * n]
|
|
484
|
+
f_ab = values[2 * n:].reshape(k, n)
|
|
485
|
+
# A failed evaluation spoils its row: keep the rows where every evaluation succeeded.
|
|
486
|
+
rows = np.flatnonzero(np.isfinite(f_a) & np.isfinite(f_b) & np.isfinite(f_ab).all(axis=0))
|
|
487
|
+
if len(rows) < 2:
|
|
488
|
+
return [ParameterSensitivity(name=parameter.name, importance=math.nan) for parameter in measured]
|
|
489
|
+
first, total = _saltelli(f_a[rows], f_b[rows], f_ab[:, rows])
|
|
490
|
+
firsts, totals = [], []
|
|
491
|
+
for start in range(0, BOOTSTRAP_RESAMPLES, 100):
|
|
492
|
+
picks = rows[rng.integers(len(rows), size=(min(100, BOOTSTRAP_RESAMPLES - start), len(rows)))]
|
|
493
|
+
s, t = _saltelli(f_a[picks], f_b[picks], f_ab[:, picks]) # (k, resamples) each
|
|
494
|
+
firsts.append(s)
|
|
495
|
+
totals.append(t)
|
|
496
|
+
first_samples, total_samples = np.concatenate(firsts, axis=-1), np.concatenate(totals, axis=-1)
|
|
497
|
+
return [
|
|
498
|
+
ParameterSensitivity(
|
|
499
|
+
name=parameter.name,
|
|
500
|
+
importance=float(total[i]),
|
|
501
|
+
interval=(total_interval := _percentiles(total_samples[i], confidence)),
|
|
502
|
+
first=float(first[i]),
|
|
503
|
+
first_interval=_percentiles(first_samples[i], confidence),
|
|
504
|
+
total=float(total[i]),
|
|
505
|
+
total_interval=total_interval,
|
|
506
|
+
)
|
|
507
|
+
for i, parameter in enumerate(measured)
|
|
508
|
+
]
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def _percentiles(samples: np.ndarray, confidence: float) -> Interval:
|
|
512
|
+
"""The percentile bootstrap interval of samples."""
|
|
513
|
+
tail = (1 - confidence) / 2 * 100
|
|
514
|
+
low, high = np.percentile(samples, [tail, 100 - tail])
|
|
515
|
+
return Interval(low=float(low), high=float(high))
|
|
516
|
+
|
|
517
|
+
|
|
518
|
+
def _number(value: float | None) -> str:
|
|
519
|
+
return "-" if value is None or not math.isfinite(value) else f"{value:.4g}"
|
|
520
|
+
|
|
521
|
+
|
|
522
|
+
def _interval(interval: Interval | None) -> str:
|
|
523
|
+
return "-" if interval is None else f"[{interval.low:.3g}, {interval.high:.3g}]"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: hone-python
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.13.0
|
|
4
4
|
Summary: A python-based optimization engine/library.
|
|
5
5
|
License-Expression: BSD-3-Clause
|
|
6
6
|
License-File: LICENSE
|
|
@@ -382,6 +382,34 @@ Everything else works as with one objective: constraints, conditions, workers an
|
|
|
382
382
|
|
|
383
383
|
[examples/cantilever_beam.py](examples/cantilever_beam.py) designs a beam in steel, aluminium or carbon fibre that is light, cheap and stiff, three objectives, under a stress limit that depends on the material, and chooses the stiffest design under a mass and a cost limit. Tuning for more than three objectives is out of scope for now: with many objectives nearly every design is on the front, and the search loses its pull.
|
|
384
384
|
|
|
385
|
+
### Which parameters matter
|
|
386
|
+
|
|
387
|
+
Before optimizing a dozen parameters, it can pay to find out which of them matter. `sensitivity()` evaluates the objective at points chosen to measure each parameter's effect, through the same `workers`, `timeout` and failure handling as `optimize()`, and reports them most important first:
|
|
388
|
+
|
|
389
|
+
```python
|
|
390
|
+
from hone import choose_optimizer, sensitivity
|
|
391
|
+
|
|
392
|
+
report = sensitivity(run_simulation, search_space, max_evaluations=500, workers=8, seed=0)
|
|
393
|
+
print(report)
|
|
394
|
+
reduced = report.reduced(search_space) # the unimportant parameters fixed
|
|
395
|
+
result = choose_optimizer(reduced, max_evaluations=200).optimize(run_simulation, workers=8)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
How it measures depends on the budget:
|
|
399
|
+
|
|
400
|
+
| Method | Evaluations | Reports |
|
|
401
|
+
| --- | --- | --- |
|
|
402
|
+
| Morris screening | About 10 × (parameters + 1), at least 2 × (parameters + 1) | `mu_star`, the mean size of each parameter's effect: the change in the objective across its whole range. `mu` is the mean with its sign, and `sigma` large against `mu_star` means the effect depends on the other parameters |
|
|
403
|
+
| Sobol indices | 64 × (parameters + 2) or more, in powers of 2 | `total`, the share of the objective's variance the parameter accounts for with its interactions, and `first`, the share it accounts for alone. A `total` near 0 means the parameter can be fixed with little effect |
|
|
404
|
+
|
|
405
|
+
Without `method=`, Sobol is used when at least 64 × (parameters + 2) evaluations fit in `max_evaluations`, and Morris otherwise. Each index comes with a 95% bootstrap interval. `report.ranking` lists the names, most important first, `report["fillet"]` gives one parameter, and `report.best_params` is the best point evaluated (`maximize=True` for the highest).
|
|
406
|
+
|
|
407
|
+
`report.reduced(search_space)` returns the search space with the parameters `report.unimportant()` names fixed: those whose whole interval is below 0.05 for Sobol, or a tenth of the largest `mu_star` for Morris. `threshold=` changes that, and `keep=4` keeps the four most important instead. A fixed parameter is still passed to the objective, at its value in the best point evaluated unless `at={...}` gives one. A parameter can barely change the objective and still have a best value, so fixing it can cost a little; fix one you know the best value of with `at=`.
|
|
408
|
+
|
|
409
|
+
Every kind of parameter is measured on the scale the optimizers search it on: a log range in its logarithm, an integer range rounded, and a choice parameter among its choices. A conditional parameter is passed only while switched on, so its indices include the points where it has no effect. Search spaces with constraints aren't supported yet.
|
|
410
|
+
|
|
411
|
+
[examples/heat_sink.py](examples/heat_sink.py) finds which of a heat sink's eight settings drive a chip's temperature, fixes the four that don't, and on a budget of 60 evaluations finds a cooler design than a search over all eight.
|
|
412
|
+
|
|
385
413
|
### Benchmarks
|
|
386
414
|
|
|
387
415
|
`hone.benchmarks` runs optimizers on test problems with known optima and reports how close each one gets:
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
hone/__init__.py,sha256=
|
|
1
|
+
hone/__init__.py,sha256=gO_LL5VPdE1BMl2k2dp1VrlfYQqvqT5rhwvDxT3ppPs,1898
|
|
2
2
|
hone/benchmarks/__init__.py,sha256=dYjoSBrYSWcCCpk4w4uF_KqcQYbF7JyfpfOTZHLhg9o,608
|
|
3
3
|
hone/benchmarks/__main__.py,sha256=1-rzY3ZxmPQ8OZDxCQ1u7Y2IARiF3_cBfj-G4Gl89wc,5711
|
|
4
4
|
hone/benchmarks/conditional.py,sha256=m1Q_UQ_qUVbpOwaabxSWKjBQszCoWV_yJWfq-q9E3ko,5031
|
|
@@ -39,7 +39,8 @@ hone/parameters/parameters.py,sha256=b6m9PlJtIYGvrJeLv4tktX-wa6ksPqbJOeJULXGlWBQ
|
|
|
39
39
|
hone/pareto.py,sha256=IFfvd5idY1ZFyXi_SnqhNFex5-B3B0Xc-BHDX0YLZRE,12452
|
|
40
40
|
hone/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
41
41
|
hone/result.py,sha256=-x3OGPC95nyTPsnbUqI6LSjC5rp0fIL-VBPRMkbRALc,5923
|
|
42
|
-
|
|
43
|
-
hone_python-0.
|
|
44
|
-
hone_python-0.
|
|
45
|
-
hone_python-0.
|
|
42
|
+
hone/sensitivity_analysis.py,sha256=OYsRSL04kOrIp2cSAbpJIUm7vx4z56_OmOkVtKKjTTg,25026
|
|
43
|
+
hone_python-0.13.0.dist-info/METADATA,sha256=-dzyd1OuXV091RYjh1A1UR7Sm3HMjAgThyPnUm5qbYE,41307
|
|
44
|
+
hone_python-0.13.0.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
|
|
45
|
+
hone_python-0.13.0.dist-info/licenses/LICENSE,sha256=M0sVPvCyGe4r-7bmB9znW4yTKe2joCIdF3tq0ht9vb4,1503
|
|
46
|
+
hone_python-0.13.0.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|