hone-python 0.12.2__py3-none-any.whl → 0.14.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
@@ -15,9 +15,10 @@ from hone.optimizers import (
15
15
  choose_optimizer,
16
16
  choose_pareto_optimizer,
17
17
  )
18
- from hone.parameters import ChoiceParameter, Condition, Constraint, FixedParameter, InfeasibleSearchSpace, RangeParameter, SearchSpace
18
+ from hone.parameters import ChoiceParameter, Condition, Constraint, FixedParameter, InfeasibleSearchSpace, Output, 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,8 @@ __all__ = [
45
47
  "NSGA2Config",
46
48
  "Optimizer",
47
49
  "OptimizerConfig",
50
+ "Output",
51
+ "ParameterSensitivity",
48
52
  "ParetoGenerationStats",
49
53
  "ParetoPoint",
50
54
  "ParetoProgress",
@@ -57,6 +61,8 @@ __all__ = [
57
61
  "RunInfo",
58
62
  "SearchSpace",
59
63
  "SelectionMethod",
64
+ "sensitivity",
65
+ "SensitivityReport",
60
66
  "Trial",
61
67
  "UnsupportedSearchSpace",
62
68
  ]
@@ -8,6 +8,11 @@
8
8
  - pressure-vessel, tension-spring and welded-beam: three standard engineering design problems,
9
9
  scored against the best designs published for them. The welded beam's stress formulas need
10
10
  square roots, so its constraints are functions; the others are expressions.
11
+
12
+ Each engineering problem also comes with its limits on outputs, as the -outputs version: the
13
+ objective reports the volume, stresses and so on that the limits apply to, as a simulation
14
+ would, and the optimizer only learns that a design breaks a limit after evaluating it. The
15
+ pairs show what is lost by not knowing a limit beforehand.
11
16
  """
12
17
  import math
13
18
  import zlib
@@ -15,7 +20,7 @@ from typing import Any
15
20
 
16
21
  import numpy as np
17
22
 
18
- from hone.parameters import Constraint, RangeParameter, SearchSpace
23
+ from hone.parameters import Constraint, Output, RangeParameter, SearchSpace
19
24
 
20
25
  from .problems import BOUND, Problem, _shift
21
26
 
@@ -166,7 +171,102 @@ def welded_beam() -> Problem:
166
171
  return Problem(name="welded-beam", function=welded_beam, search_space=space, optimum=1.724852, tags=frozenset({"constrained", "engineering"}))
167
172
 
168
173
 
174
+ def pressure_vessel_outputs() -> Problem:
175
+ """The pressure vessel, with its limits on what it reports: the plate thicknesses its radius needs, and its volume."""
176
+ problem = pressure_vessel()
177
+ shell, head = RangeParameter("shell", 1, 99, integer=True), RangeParameter("head", 1, 99, integer=True)
178
+ radius, length = RangeParameter("radius", 10, 200), RangeParameter("length", 10, 200)
179
+ cost = problem.function
180
+
181
+ def pressure_vessel_outputs(shell: int, head: int, radius: float, length: float) -> dict[str, float]:
182
+ return {
183
+ "objective": cost(shell=shell, head=head, radius=radius, length=length),
184
+ "shell_needed": 0.0193 * radius,
185
+ "head_needed": 0.00954 * radius,
186
+ "volume": math.pi * radius**2 * length + 4 / 3 * math.pi * radius**3,
187
+ }
188
+
189
+ space = SearchSpace(
190
+ [shell, head, radius, length],
191
+ [shell / 16 >= Output("shell_needed"), head / 16 >= Output("head_needed"), Output("volume") >= 1_296_000],
192
+ )
193
+ return problem.model_copy(update={"name": "pressure-vessel-outputs", "function": pressure_vessel_outputs, "search_space": space, "tags": problem.tags | {"outputs"}})
194
+
195
+
196
+ def tension_spring_outputs() -> Problem:
197
+ """The tension spring, with its deflection, shear stress and surge frequency limits on what it reports."""
198
+ problem = tension_spring()
199
+ d, coil, n = RangeParameter("wire", 0.05, 2.0), RangeParameter("coil", 0.25, 1.3), RangeParameter("turns", 2.0, 15.0)
200
+ weight = problem.function
201
+
202
+ def tension_spring_outputs(wire: float, coil: float, turns: float) -> dict[str, float]:
203
+ if coil == wire:
204
+ return {"objective": math.nan, "deflection": math.nan, "shear": math.nan, "surge": math.nan} # the shear divides by zero: failed
205
+ return {
206
+ "objective": weight(wire=wire, coil=coil, turns=turns),
207
+ "deflection": coil**3 * turns / (71785 * wire**4),
208
+ "shear": (4 * coil**2 - wire * coil) / (12566 * (coil * wire**3 - wire**4)) + 1 / (5108 * wire**2),
209
+ "surge": 140.45 * wire / (coil**2 * turns),
210
+ }
211
+
212
+ space = SearchSpace(
213
+ [d, coil, n],
214
+ [Output("deflection") >= 1, Output("shear") <= 1, Output("surge") >= 1, d + coil <= 1.5],
215
+ )
216
+ return problem.model_copy(update={"name": "tension-spring-outputs", "function": tension_spring_outputs, "search_space": space, "tags": problem.tags | {"outputs"}})
217
+
218
+
219
+ def welded_beam_outputs() -> Problem:
220
+ """The welded beam, with its shear, bending, buckling and deflection limits on what it reports.
221
+
222
+ The geometric limits, weld <= width and the cost cap, stay on the parameters, as they would
223
+ in practice: they need no simulation.
224
+ """
225
+ problem = welded_beam()
226
+ weld, length = RangeParameter("weld", 0.1, 2.0), RangeParameter("length", 0.1, 10.0)
227
+ thickness, width = RangeParameter("thickness", 0.1, 10.0), RangeParameter("width", 0.1, 2.0)
228
+ cost = problem.function
229
+
230
+ def welded_beam_outputs(weld: float, length: float, thickness: float, width: float) -> dict[str, float]:
231
+ return {
232
+ "objective": cost(weld=weld, length=length, thickness=thickness, width=width),
233
+ "shear": _shear(weld, length, thickness),
234
+ "bending": 6 * P * L / (width * thickness**2),
235
+ "buckling": _buckling(thickness, width),
236
+ "deflection": 4 * P * L**3 / (E * thickness**3 * width),
237
+ }
238
+
239
+ space = SearchSpace(
240
+ [weld, length, thickness, width],
241
+ [
242
+ Output("shear") <= 13600,
243
+ Output("bending") <= 30000,
244
+ weld <= width,
245
+ 0.10471 * weld**2 + 0.04811 * thickness * width * (14 + length) <= 5,
246
+ Output("deflection") <= 0.25,
247
+ Output("buckling") >= P,
248
+ ],
249
+ )
250
+ return problem.model_copy(update={"name": "welded-beam-outputs", "function": welded_beam_outputs, "search_space": space, "tags": problem.tags | {"outputs"}})
251
+
252
+
169
253
  def constrained_problems(dimensions: tuple[int, ...] = (2, 5, 10)) -> list[Problem]:
170
- """The constrained suite: boundary sphere and ellipsoid in each dimension, Rosenbrock in a disk, and three engineering designs."""
254
+ """The constrained suite: boundary sphere and ellipsoid in each dimension, Rosenbrock in a disk, and three engineering designs.
255
+
256
+ Each engineering design comes twice: with its limits on the parameters, and on its outputs.
257
+ """
171
258
  problems = [factory(d) for d in dimensions for factory in (boundary_sphere, boundary_ellipsoid)]
172
- return problems + [rosenbrock_disk(), pressure_vessel(), tension_spring(), welded_beam()]
259
+ return problems + [
260
+ rosenbrock_disk(),
261
+ pressure_vessel(),
262
+ tension_spring(),
263
+ welded_beam(),
264
+ pressure_vessel_outputs(),
265
+ tension_spring_outputs(),
266
+ welded_beam_outputs(),
267
+ ]
268
+
269
+
270
+ def output_problems() -> list[Problem]:
271
+ """The engineering designs with their limits on outputs only, for a quick comparison with the parameter versions."""
272
+ return [pressure_vessel_outputs(), tension_spring_outputs(), welded_beam_outputs()]
hone/benchmarks/runner.py CHANGED
@@ -1,6 +1,7 @@
1
1
  """Run optimizers on benchmark problems and summarize how close they get to each optimum."""
2
2
  import functools
3
3
  import json
4
+ import math
4
5
  import multiprocessing
5
6
  import statistics
6
7
  import zlib
@@ -79,7 +80,7 @@ class Run(BaseModel):
79
80
  optimizer: str
80
81
  budget_per_dimension: int
81
82
  seed: int
82
- error: float # best value found minus the problem's optimum; 0 means the optimum was found
83
+ error: float # best value found minus the problem's optimum; 0 means the optimum was found, infinity that nothing feasible was
83
84
  evaluations: int
84
85
  trace: list[tuple[int, float]] # (evaluations so far, error of the best so far), once per generation
85
86
 
@@ -100,7 +101,7 @@ class Summary(BaseModel):
100
101
  @classmethod
101
102
  def of(cls, runs: list[Run], tolerance: float) -> "Summary":
102
103
  errors = sorted(run.error for run in runs)
103
- quartiles = statistics.quantiles(errors, n=4, method="inclusive") if len(errors) > 1 else errors * 3
104
+ quartiles = [_quantile(errors, q) for q in (0.25, 0.5, 0.75)]
104
105
  return cls(
105
106
  problem=runs[0].problem,
106
107
  optimizer=runs[0].optimizer,
@@ -113,6 +114,15 @@ class Summary(BaseModel):
113
114
  )
114
115
 
115
116
 
117
+ def _quantile(ordered: list[float], q: float) -> float:
118
+ """The q quantile of sorted values, interpolated as statistics.quantiles' inclusive method does, allowing infinity."""
119
+ position = (len(ordered) - 1) * q
120
+ low, high = math.floor(position), math.ceil(position)
121
+ if ordered[low] == ordered[high] or position == low:
122
+ return ordered[low]
123
+ return ordered[low] + (ordered[high] - ordered[low]) * (position - low)
124
+
125
+
116
126
  def run_benchmark(
117
127
  problems: Iterable[Problem],
118
128
  optimizers: dict[str, OptimizerFactory] | None = None,
@@ -172,6 +182,7 @@ def _run(problem: Problem, name: str, per_dimension: int, seed: int, optimizer:
172
182
  # noisy value it saw there, which is likely to be a lucky one.
173
183
  return problem.function(**params) if problem.noise else fitness
174
184
 
185
+ # With constraints on outputs, generations' bests are of feasible points only, so the trace is too.
175
186
  trace, best = [], float("inf")
176
187
  for generation in result.generations:
177
188
  if generation.best_fitness is not None and generation.best_params is not None:
@@ -182,7 +193,7 @@ def _run(problem: Problem, name: str, per_dimension: int, seed: int, optimizer:
182
193
  optimizer=name,
183
194
  budget_per_dimension=per_dimension,
184
195
  seed=seed,
185
- error=max(true_value(result.best_fitness, result.best_params) - problem.optimum, 0.0),
196
+ error=max(true_value(result.best_fitness, result.best_params) - problem.optimum, 0.0) if result.feasible else math.inf,
186
197
  evaluations=result.evaluations,
187
198
  trace=trace,
188
199
  )
@@ -19,9 +19,15 @@ class ObjectiveFunction(BaseModel):
19
19
  # Checked after validation rather than in a validator, so a mismatch raises a plain ValueError.
20
20
  self._check_signature()
21
21
 
22
- def __call__(self, params: dict[str, Any]) -> float:
23
- """Evaluate the function at params, which must return a real number."""
22
+ def __call__(self, params: dict[str, Any]) -> Any:
23
+ """Evaluate the function at params, which returns a real number.
24
+
25
+ With constraints on outputs the function returns a dict of the objective's value and the outputs
26
+ instead, which is checked when it is told to the optimizer, in the main process.
27
+ """
24
28
  value = self.function(**params)
29
+ if self.search_space.output_constraints:
30
+ return value
25
31
  if not isinstance(value, numbers.Real):
26
32
  raise TypeError(f"{self.name}() must return a number, but returned {value!r}")
27
33
  return float(value)
hone/optimizers/base.py CHANGED
@@ -9,6 +9,7 @@ from hone.result import GenerationStats, Progress, Result
9
9
 
10
10
  from .core import (
11
11
  CHECKPOINT_FORMAT,
12
+ OBJECTIVE,
12
13
  EvaluationFailed,
13
14
  Individual,
14
15
  OptimizerCore,
@@ -21,6 +22,7 @@ from .core import (
21
22
 
22
23
  __all__ = [
23
24
  "CHECKPOINT_FORMAT",
25
+ "OBJECTIVE",
24
26
  "EvaluationFailed",
25
27
  "Individual",
26
28
  "Optimizer",
@@ -60,6 +62,12 @@ class Optimizer(OptimizerCore[Result]):
60
62
 
61
63
  The objective returns a number. To record an evaluation as failed instead, it can raise
62
64
  EvaluationFailed or return NaN or infinity.
65
+
66
+ With constraints on outputs, the objective returns a dict instead: its value under
67
+ "objective", and a number for each output the constraints use. Evaluations are then ranked
68
+ by Deb's feasibility rule: a point that satisfies every output constraint beats one that
69
+ doesn't, feasible points rank by value, and the others by their total violation, so no
70
+ penalty weight is needed. Failed evaluations rank below them all.
63
71
  """
64
72
 
65
73
  def reset(self) -> None:
@@ -71,6 +79,7 @@ class Optimizer(OptimizerCore[Result]):
71
79
  self._points: dict[tuple, dict[str, Any]] = {}
72
80
  self._finalists: list[tuple] = []
73
81
  self._final_round = False
82
+ self._infeasible = 0 # evaluations that broke a constraint on the outputs
74
83
 
75
84
  # --- what a value is ---------------------------------------------------
76
85
 
@@ -79,6 +88,11 @@ class Optimizer(OptimizerCore[Result]):
79
88
  return True
80
89
  if value is None:
81
90
  raise ValueError("pass the trial's value, or failed=True")
91
+ outputs = self.search_space.outputs
92
+ if outputs:
93
+ return not _check_outputs(
94
+ value, [OBJECTIVE, *outputs], f"the value, since the search space has constraints on the outputs {', '.join(outputs)},"
95
+ )
82
96
  if isinstance(value, bool) or not isinstance(value, numbers.Real):
83
97
  raise TypeError(f"the value must be a number, got {value!r}")
84
98
  return not math.isfinite(value)
@@ -87,6 +101,11 @@ class Optimizer(OptimizerCore[Result]):
87
101
  individual.fitness = -math.inf if self.config.maximize else math.inf
88
102
 
89
103
  def _record(self, individual: Individual, value: Any) -> None:
104
+ if isinstance(value, dict):
105
+ individual.outputs = {name: float(value[name]) for name in self.search_space.outputs}
106
+ individual.violation = self.search_space.output_violation(individual.params, individual.outputs)
107
+ self._infeasible += individual.violation > 0
108
+ value = value[OBJECTIVE]
90
109
  individual.fitness = float(value)
91
110
  if self.config.noise:
92
111
  # Average every evaluation of the same point, so a lucky value regresses toward its mean.
@@ -94,7 +113,7 @@ class Optimizer(OptimizerCore[Result]):
94
113
  self._observations.setdefault(key, []).append(float(value))
95
114
  self._points.setdefault(key, dict(individual.params))
96
115
  individual.fitness = float(np.mean(self._observations[key]))
97
- if self._best is None or self._is_better(individual.fitness, _fitness(self._best)):
116
+ if self._best is None or self._rank(individual) < self._rank(self._best):
98
117
  self._best = individual
99
118
 
100
119
  def _has_result(self) -> bool:
@@ -108,12 +127,16 @@ class Optimizer(OptimizerCore[Result]):
108
127
  if best is None:
109
128
  raise RuntimeError("no successful evaluations yet")
110
129
  best_fitness, best_params = best
130
+ assert self._best is not None
111
131
  return Result(
112
132
  best_fitness=best_fitness,
113
133
  best_params=dict(best_params),
134
+ best_outputs=dict(self._best.outputs) if self._best.outputs is not None else None,
135
+ feasible=self._best.violation == 0,
114
136
  generations=self._history,
115
137
  evaluations=self._evaluations,
116
138
  failures=self._failures,
139
+ infeasible=self._infeasible,
117
140
  reached_threshold=self._reached_threshold,
118
141
  stopped=self._stopped,
119
142
  run=self._run_info(),
@@ -141,6 +164,7 @@ class Optimizer(OptimizerCore[Result]):
141
164
  evaluations=stats.evaluations,
142
165
  best_fitness=best[0] if best is not None else None,
143
166
  best_params=dict(best[1]) if best is not None else None,
167
+ feasible=self._best is None or self._best.violation == 0,
144
168
  elapsed=self._elapsed(),
145
169
  )
146
170
  if callback(progress) and not self._done:
@@ -152,7 +176,8 @@ class Optimizer(OptimizerCore[Result]):
152
176
 
153
177
  def _goal_reached(self) -> bool:
154
178
  best = self._best_point()
155
- return best is not None and self._reached(best[0])
179
+ # Only a point that satisfies every constraint on the outputs can reach the threshold.
180
+ return best is not None and self._best is not None and self._best.violation == 0 and self._reached(best[0])
156
181
 
157
182
  def _begin_final_round(self) -> bool:
158
183
  if self.config.reserved_evaluations and not self._final_round and self._observations:
@@ -207,13 +232,19 @@ class Optimizer(OptimizerCore[Result]):
207
232
 
208
233
  # --- ranking ---------------------------------------------------------------
209
234
 
210
- def _is_better(self, fitness: float, other: float) -> bool:
211
- """Whether fitness beats other in the configured direction."""
212
- return fitness > other if self.config.maximize else fitness < other
235
+ def _rank(self, individual: Individual) -> tuple[bool, float, float]:
236
+ """A sort key putting the best individual first, by Deb's feasibility rule.
237
+
238
+ Successful before failed; among those, smaller violation of the output constraints
239
+ first, which puts every feasible point (violation 0) ahead; then better fitness. Without
240
+ output constraints every violation is 0, so this ranks by fitness alone.
241
+ """
242
+ fitness = _fitness(individual)
243
+ return individual.failed, individual.violation, -fitness if self.config.maximize else fitness
213
244
 
214
245
  def _ranked(self, individuals: list[Individual]) -> list[Individual]:
215
- """The individuals, best first. Failed individuals sort last."""
216
- return sorted(individuals, key=_fitness, reverse=self.config.maximize)
246
+ """The individuals, best first: by feasibility, then fitness. Failed individuals sort last."""
247
+ return sorted(individuals, key=self._rank)
217
248
 
218
249
  def _reached(self, fitness: float) -> bool:
219
250
  """Whether fitness is good enough to stop early. Never true without a threshold."""
@@ -223,15 +254,19 @@ class Optimizer(OptimizerCore[Result]):
223
254
 
224
255
  def _summarize(self, generation: int, evaluations: int, population: list[Individual]) -> GenerationStats:
225
256
  evaluated = [ind for ind in population if ind.fitness is not None]
226
- succeeded = self._ranked([ind for ind in evaluated if not ind.failed])
227
- failures = len(evaluated) - len(succeeded)
257
+ ranked = self._ranked([ind for ind in evaluated if not ind.failed])
258
+ failures = len(evaluated) - len(ranked)
259
+ # The fitness statistics cover only points that satisfy the output constraints.
260
+ succeeded = [ind for ind in ranked if ind.violation == 0]
261
+ infeasible = len(ranked) - len(succeeded)
228
262
  if not succeeded:
229
- return GenerationStats(generation=generation, evaluations=evaluations, failures=failures)
263
+ return GenerationStats(generation=generation, evaluations=evaluations, failures=failures, infeasible=infeasible)
230
264
  fitnesses = [_fitness(ind) for ind in succeeded]
231
265
  return GenerationStats(
232
266
  generation=generation,
233
267
  evaluations=evaluations,
234
268
  failures=failures,
269
+ infeasible=infeasible,
235
270
  best_fitness=succeeded[0].fitness,
236
271
  best_params=self.search_space.active(succeeded[0].params),
237
272
  worst_fitness=succeeded[-1].fitness,
@@ -241,6 +276,21 @@ class Optimizer(OptimizerCore[Result]):
241
276
  )
242
277
 
243
278
 
279
+ def _check_outputs(value: Any, names: list[str], what: str) -> bool:
280
+ """Check value is a dict with a number for exactly the given names, raising TypeError if not. Returns whether every number is finite."""
281
+ if not isinstance(value, dict):
282
+ raise TypeError(f"{what} must be a dict with a number for each of {', '.join(names)}, got {value!r}")
283
+ missing, extra = [n for n in names if n not in value], sorted(set(value) - set(names))
284
+ if missing or extra:
285
+ problems = [f"missing {', '.join(missing)}"] * bool(missing) + [f"unknown {', '.join(map(str, extra))}"] * bool(extra)
286
+ raise TypeError(f"{what} must have exactly {', '.join(names)}: {'; '.join(problems)}")
287
+ for name in names:
288
+ number = value[name]
289
+ if isinstance(number, bool) or not isinstance(number, numbers.Real):
290
+ raise TypeError(f"the value of {name} must be a number, got {number!r}")
291
+ return all(math.isfinite(value[name]) for name in names)
292
+
293
+
244
294
  def _fitness(individual: Individual) -> float:
245
295
  """The fitness of an individual that has been evaluated."""
246
296
  assert individual.fitness is not None, "an individual was ranked before it was evaluated"
@@ -10,6 +10,11 @@ parameter becomes one column per choice, holding 1 for the chosen one and 0 for
10
10
  A parameter a condition switches off is encoded the same way whatever value it holds: a range at
11
11
  INACTIVE, and a choice with every column 0. So points that differ only where parameters are
12
12
  switched off are the same point to the model, and the values they happen to hold add no noise.
13
+
14
+ With constraints on outputs, a Gaussian process models each one's margin, which is zero or less
15
+ where it is satisfied. The acquisition is multiplied by the probability that every one holds,
16
+ so the search learns where the infeasible region is from the evaluations that broke a limit
17
+ (Gardner et al., 2014; Gelbart, Snoek and Adams, 2014).
13
18
  """
14
19
  import math
15
20
  from typing import Any, Callable, List
@@ -23,7 +28,7 @@ from hone.config import BayesianConfig
23
28
  from hone.optimizers._gp import GaussianProcess
24
29
  from hone.optimizers.base import Individual, Optimizer, UnsupportedSearchSpace
25
30
  from hone.parameters import ChoiceParameter, Parameter, RangeParameter, SearchSpace
26
- from hone.parameters.conditions import ChoiceTest, holds
31
+ from hone.parameters.conditions import ChoiceTest, ConditionalConstraint, holds
27
32
 
28
33
  GLOBAL_CANDIDATES = 1000 # random candidates per search of the model
29
34
  LOCAL_CANDIDATES = 500 # candidates near the best points found so far
@@ -31,17 +36,94 @@ REFINED = 5 # the best candidates are refined by gradient search
31
36
  REFIT_EVERY = 5 # past FIT_EVERY_UNTIL observations, refit the model's hyperparameters only this often
32
37
  FIT_EVERY_UNTIL = 50
33
38
  INACTIVE = 0.5 # where a range switched off by a condition is encoded
39
+ UNCOMPUTED_MARGIN = 1.0 # the least relative margin, 100% over, modelled where a constraint couldn't be computed
34
40
 
35
41
 
36
42
  class _ModelSearch:
37
43
  """Searching an acquisition function for the next candidate, over the encoded space, keeping to constraints.
38
44
 
39
- Shared by single- and multi-objective Bayesian optimization.
45
+ Shared by single- and multi-objective Bayesian optimization, which also share the models of
46
+ constraints on outputs: _absorb_outputs records each evaluation's margins, and
47
+ _constraint_models and _log_feasibility turn them into the probability that a point
48
+ satisfies every one.
40
49
  """
41
50
  search_space: SearchSpace
42
51
  rng: np.random.Generator
43
52
  _encoding: "_Encoding"
44
53
 
54
+ def _reset_outputs(self) -> None:
55
+ self._margins: list[list[float | None] | None] = [] # each evaluated point's margins, or None if it failed
56
+ self._violations: list[float] = [] # each evaluated point's total violation; infinity if it failed
57
+ self._constraint_thetas: dict[int, np.ndarray] = {} # each constraint model's hyperparameters, kept between fits
58
+ self._constraint_fitted_at: dict[int, int] = {}
59
+
60
+ def _absorb_outputs(self, individual: Individual) -> None:
61
+ """Record an evaluated individual's margins and violation, alongside its row of X."""
62
+ if individual.failed or individual.outputs is None:
63
+ self._margins.append(None)
64
+ else:
65
+ self._margins.append(self.search_space.output_margins(individual.params, individual.outputs))
66
+ self._violations.append(math.inf if individual.failed else individual.violation)
67
+
68
+ def _constraint_models(self, X: np.ndarray, pending: list[np.ndarray]) -> list[tuple[int, GaussianProcess]]:
69
+ """A Gaussian process of each output constraint's margin, by the constraint's position, with pending points believed.
70
+
71
+ Each is fitted to the points where its constraint applies, to its relative margin
72
+ through the bilog transform, sign(m) log(1 + |m|) (Eriksson and Poloczek, 2021), which
73
+ keeps the sign, so the limit stays at zero, and tames the far tails that stresses and
74
+ the like have near a design's edges. A margin that couldn't be computed counts as the
75
+ largest seen, and at least UNCOMPUTED_MARGIN, so it is never taken for feasible. A constraint with fewer than two such points has no model yet.
76
+ """
77
+ models = []
78
+ for j in range(len(self.search_space.output_constraints)):
79
+ rows = [i for i, margins in enumerate(self._margins) if margins is not None and margins[j] is not None]
80
+ if len(rows) < 2:
81
+ continue
82
+ values = np.array([_margin(self._margins[i], j) for i in rows], dtype=np.float64)
83
+ finite = np.isfinite(values)
84
+ if not finite.any():
85
+ continue
86
+ # A margin that couldn't be computed counts as infeasible: at least 100% over, or the worst seen.
87
+ values[~finite] = max(values[finite].max(), UNCOMPUTED_MARGIN)
88
+ values = _bilog(values)
89
+ theta = self._constraint_thetas.get(j)
90
+ model = GaussianProcess(X[rows], values, theta)
91
+ if theta is None or len(rows) <= FIT_EVERY_UNTIL or len(rows) - self._constraint_fitted_at.get(j, 0) >= REFIT_EVERY:
92
+ model.fit(restarts=2 if theta is None else 0, rng=self.rng)
93
+ self._constraint_thetas[j], self._constraint_fitted_at[j] = model.theta, len(rows)
94
+ for x in pending:
95
+ model = _believed(model, x)
96
+ models.append((j, model))
97
+ return models
98
+
99
+ def _log_feasibility(self, models: list[tuple[int, GaussianProcess]]) -> Callable[[np.ndarray], np.ndarray]:
100
+ """log P(every output constraint holds) at each row of X, by the constraints' models, treated as independent.
101
+
102
+ A conditional constraint counts only at points where it applies.
103
+ """
104
+ constraints = self.search_space.output_constraints
105
+ conditional = self.search_space.conditions or any(isinstance(c, ConditionalConstraint) for c in constraints)
106
+
107
+ def log_probability(X: np.ndarray) -> np.ndarray:
108
+ total = np.zeros(len(X))
109
+ params = [self._encoding.decode(x) for x in X] if conditional and models else []
110
+ for j, model in models:
111
+ mean, sd = model.predict(X)
112
+ log_p = log_ndtr((float(model.standardize(0.0)) - mean) / sd)
113
+ if conditional:
114
+ applies = np.array([constraints[j].applies(self.search_space.active(p)) for p in params], dtype=bool)
115
+ log_p = np.where(applies, log_p, 0.0)
116
+ total += log_p
117
+ return total
118
+
119
+ return log_probability
120
+
121
+ def _feasible_leaders(self, X: np.ndarray, scores: np.ndarray, count: int = 5) -> np.ndarray:
122
+ """The count best rows of X: feasible points by score, lowest first, then the rest by violation."""
123
+ violations = np.array(self._violations) if self._violations else np.zeros(len(X))
124
+ order = np.lexsort((scores, violations))
125
+ return X[order[:count]]
126
+
45
127
  def _search(self, acquisition: Callable[[np.ndarray], np.ndarray], leaders: np.ndarray, seen: np.ndarray) -> np.ndarray:
46
128
  """The candidate with the highest acquisition not yet evaluated: from random points, points near the leaders, and the best of those refined."""
47
129
  encoding = self._encoding
@@ -59,7 +141,7 @@ class _ModelSearch:
59
141
  scores = np.append(scores, self._only_feasible(refined, acquisition(refined)))
60
142
 
61
143
  for index in np.argsort(-scores):
62
- if scores[index] == -np.inf and self.search_space.constraints:
144
+ if scores[index] == -np.inf and self.search_space.parameter_constraints:
63
145
  break # the rest break a constraint
64
146
  if not np.any(np.all(np.abs(seen - candidates[index]) < 1e-9, axis=1)):
65
147
  return candidates[index]
@@ -70,15 +152,15 @@ class _ModelSearch:
70
152
  def _feasible_spread(self, count: int) -> np.ndarray:
71
153
  """count points spread over the space, any that break a constraint replaced by random feasible points."""
72
154
  X = self._encoding.spread(self.rng, count)
73
- if self.search_space.constraints:
155
+ if self.search_space.parameter_constraints:
74
156
  for i, x in enumerate(X):
75
157
  if not self.search_space.feasible(self._encoding.decode(x)):
76
158
  X[i] = self._encoding.encode(self.search_space.sample(self.rng))
77
159
  return X
78
160
 
79
161
  def _only_feasible(self, X: np.ndarray, scores: np.ndarray) -> np.ndarray:
80
- """scores, with those of points that break a constraint set to minus infinity."""
81
- if not self.search_space.constraints:
162
+ """scores, with those of points that break a constraint on the parameters set to minus infinity."""
163
+ if not self.search_space.parameter_constraints:
82
164
  return scores
83
165
  feasible = np.array([self.search_space.feasible(self._encoding.decode(x)) for x in X], dtype=bool)
84
166
  return np.where(feasible, scores, -np.inf)
@@ -92,6 +174,10 @@ class BayesianOptimizer(Optimizer, _ModelSearch):
92
174
  largest expected improvement on the best value so far. Failed evaluations are modelled as
93
175
  the worst value seen, which steers the search away from them.
94
176
 
177
+ With constraints on outputs, each one's margin gets a Gaussian process of its own, and the
178
+ expected improvement on the best feasible value is multiplied by the probability that every
179
+ constraint holds. Until a feasible point is found, candidates maximize that probability.
180
+
95
181
  Range parameters, integer or not, and choice parameters are supported, but not choice
96
182
  parameters with choose_n. Fixed parameters are passed through.
97
183
 
@@ -124,6 +210,7 @@ class BayesianOptimizer(Optimizer, _ModelSearch):
124
210
  self._y: list[float | None] = [] # its value to minimize, or None if it failed
125
211
  self._theta: np.ndarray | None = None # the model's hyperparameters, kept between fits
126
212
  self._fitted_at = 0 # observations at the last hyperparameter fit
213
+ self._reset_outputs()
127
214
 
128
215
  def _next_population(self, previous: list[Individual] | None, generation: int) -> list[Individual]:
129
216
  if previous is None:
@@ -145,6 +232,7 @@ class BayesianOptimizer(Optimizer, _ModelSearch):
145
232
  self._X.append(self._encoding.encode(individual.params))
146
233
  value = individual.fitness if not self.config.maximize else -individual.fitness
147
234
  self._y.append(None if individual.failed else value)
235
+ self._absorb_outputs(individual)
148
236
  # The model's matrices are small, and splitting their arithmetic across threads makes it many
149
237
  # times slower. One thread also makes results the same on every machine.
150
238
  with threadpool_limits(limits=1, user_api="blas"):
@@ -164,25 +252,64 @@ class BayesianOptimizer(Optimizer, _ModelSearch):
164
252
  model.fit(restarts=2 if self._theta is None else 0, rng=self.rng)
165
253
  self._theta, self._fitted_at = model.theta, len(X)
166
254
 
167
- # The best value so far. With noise, the best observation is likely a lucky one, so use the
168
- # lowest the model predicts at any evaluated point instead.
169
- best = float(model.predict(X)[0].min()) if self.config.noise else float(model.z.min())
170
255
  # Candidates still being evaluated are assumed to come out as predicted, so none is proposed again.
171
- for individual in self._outstanding():
172
- x = self._encoding.encode(individual.params)
173
- model = model.with_observation(x, float(model.predict(x)[0][0]))
256
+ pending = [self._encoding.encode(individual.params) for individual in self._outstanding()]
257
+ constraints = self._constraint_models(X, pending) if self.search_space.output_constraints else []
258
+ feasible = np.array(self._violations) == 0 if self.search_space.output_constraints else np.ones(len(X), dtype=bool)
259
+ best: float | None
260
+ if self.config.noise:
261
+ # The best value so far. With noise, the best observation is likely a lucky one, so use the
262
+ # lowest the model predicts at any evaluated point instead.
263
+ best = float(model.predict(X)[0].min())
264
+ elif feasible.any():
265
+ best = float(model.z[feasible].min()) # the best value of a point that satisfies every output constraint
266
+ else:
267
+ best = None if constraints else float(model.z.min())
268
+ # With output constraints, search near the best observed points that satisfy them.
269
+ leaders = self._feasible_leaders(X, model.z) if self.search_space.output_constraints else None
270
+ for x in pending:
271
+ model = _believed(model, x)
174
272
  chosen = []
175
273
  for _ in range(count):
176
- x = self._maximize_improvement(model, best)
274
+ x = self._maximize_improvement(model, best, constraints, leaders)
177
275
  chosen.append(x)
178
- # Pretend the model's prediction came true, so the next candidate of the batch goes elsewhere.
179
- mean, _ = model.predict(x)
180
- model = model.with_observation(x, float(mean[0]))
276
+ # Pretend the models' predictions came true, so the next candidate of the batch goes elsewhere.
277
+ model = _believed(model, x)
278
+ constraints = [(j, _believed(m, x)) for j, m in constraints]
181
279
  return chosen
182
280
 
183
- def _maximize_improvement(self, model: GaussianProcess, best: float) -> np.ndarray:
184
- leaders = model.X[np.argsort(model.z)[:5]]
185
- return self._search(lambda X: _log_expected_improvement(model, X, best), leaders, model.X)
281
+ def _maximize_improvement(
282
+ self, model: GaussianProcess, best: float | None, constraints: list[tuple[int, GaussianProcess]], leaders: np.ndarray | None
283
+ ) -> np.ndarray:
284
+ """The candidate with the largest expected improvement on best, times the probability it satisfies the output constraints.
285
+
286
+ With no feasible point yet, best is None, and the candidate is the one likeliest to be feasible.
287
+ Without leaders, the search starts near the lowest values the model holds, believed ones included.
288
+ """
289
+ if leaders is None:
290
+ leaders = model.X[np.argsort(model.z)[:5]]
291
+ if not constraints:
292
+ assert best is not None
293
+ return self._search(lambda X: _log_expected_improvement(model, X, best), leaders, model.X)
294
+ log_feasibility = self._log_feasibility(constraints)
295
+ if best is None:
296
+ return self._search(log_feasibility, leaders, model.X)
297
+ return self._search(lambda X: _log_expected_improvement(model, X, best) + log_feasibility(X), leaders, model.X)
298
+
299
+
300
+ def _bilog(values: np.ndarray) -> np.ndarray:
301
+ """sign(v) log(1 + |v|): the same sign, the same near zero, and logarithmic far from it."""
302
+ return np.sign(values) * np.log1p(np.abs(values))
303
+
304
+
305
+ def _margin(margins: list[float | None] | None, j: int) -> float:
306
+ assert margins is not None and margins[j] is not None
307
+ return float(margins[j]) # type: ignore[arg-type]
308
+
309
+
310
+ def _believed(model: GaussianProcess, x: np.ndarray) -> GaussianProcess:
311
+ """model with an observation at x of what it predicts there: the kriging believer, for points not yet evaluated."""
312
+ return model.with_observation(x, float(model.predict(x)[0][0]))
186
313
 
187
314
 
188
315
  def _refine(acquisition: Callable[[np.ndarray], np.ndarray], starts: np.ndarray, columns: np.ndarray) -> np.ndarray: