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 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.12.2
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=idy227TrSVIamk56qb9_pGPvOYM6URJReTH2K--NLxs,1709
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
- hone_python-0.12.2.dist-info/METADATA,sha256=TTfOblhdv3VqkDJoxxCSRv0azyanz2lnHVbzuvykWWM,38458
43
- hone_python-0.12.2.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
44
- hone_python-0.12.2.dist-info/licenses/LICENSE,sha256=M0sVPvCyGe4r-7bmB9znW4yTKe2joCIdF3tq0ht9vb4,1503
45
- hone_python-0.12.2.dist-info/RECORD,,
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,,