hone-python 0.13.0__tar.gz → 0.14.0__tar.gz

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.
Files changed (47) hide show
  1. {hone_python-0.13.0 → hone_python-0.14.0}/PKG-INFO +35 -1
  2. {hone_python-0.13.0 → hone_python-0.14.0}/README.md +34 -0
  3. {hone_python-0.13.0 → hone_python-0.14.0}/hone/__init__.py +2 -1
  4. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/constrained.py +103 -3
  5. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/runner.py +14 -3
  6. {hone_python-0.13.0 → hone_python-0.14.0}/hone/objective_function/objective_function.py +8 -2
  7. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/base.py +60 -10
  8. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/bayesian.py +146 -19
  9. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/cmaes.py +4 -2
  10. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/core.py +18 -5
  11. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/genetic/nsga2.py +17 -2
  12. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/genetic/optimizer.py +6 -3
  13. hone_python-0.14.0/hone/optimizers/genetic/selection.py +51 -0
  14. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/multi.py +41 -9
  15. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/multi_bayesian.py +36 -10
  16. {hone_python-0.13.0 → hone_python-0.14.0}/hone/parameters/__init__.py +1 -1
  17. {hone_python-0.13.0 → hone_python-0.14.0}/hone/parameters/conditions.py +18 -2
  18. {hone_python-0.13.0 → hone_python-0.14.0}/hone/parameters/constraints.py +177 -36
  19. {hone_python-0.13.0 → hone_python-0.14.0}/hone/parameters/parameters.py +90 -10
  20. {hone_python-0.13.0 → hone_python-0.14.0}/hone/pareto.py +10 -2
  21. {hone_python-0.13.0 → hone_python-0.14.0}/hone/result.py +25 -3
  22. {hone_python-0.13.0 → hone_python-0.14.0}/hone/sensitivity_analysis.py +24 -11
  23. {hone_python-0.13.0 → hone_python-0.14.0}/pyproject.toml +1 -1
  24. hone_python-0.13.0/hone/optimizers/genetic/selection.py +0 -28
  25. {hone_python-0.13.0 → hone_python-0.14.0}/LICENSE +0 -0
  26. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/__init__.py +0 -0
  27. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/__main__.py +0 -0
  28. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/conditional.py +0 -0
  29. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/ml.py +0 -0
  30. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/multi.py +0 -0
  31. {hone_python-0.13.0 → hone_python-0.14.0}/hone/benchmarks/problems.py +0 -0
  32. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/__init__.py +0 -0
  33. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/bayesian_config.py +0 -0
  34. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/cmaes_config.py +0 -0
  35. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/genetic_optimizer_config.py +0 -0
  36. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/multi_objective_config.py +0 -0
  37. {hone_python-0.13.0 → hone_python-0.14.0}/hone/config/optimizer_config.py +0 -0
  38. {hone_python-0.13.0 → hone_python-0.14.0}/hone/objective_function/__init__.py +0 -0
  39. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/__init__.py +0 -0
  40. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/_gp.py +0 -0
  41. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/_pool.py +0 -0
  42. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/choice.py +0 -0
  43. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/genetic/__init__.py +0 -0
  44. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/genetic/breeding.py +0 -0
  45. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/genetic/variation.py +0 -0
  46. {hone_python-0.13.0 → hone_python-0.14.0}/hone/optimizers/random_search.py +0 -0
  47. {hone_python-0.13.0 → hone_python-0.14.0}/hone/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hone-python
3
- Version: 0.13.0
3
+ Version: 0.14.0
4
4
  Summary: A python-based optimization engine/library.
5
5
  License-Expression: BSD-3-Clause
6
6
  License-File: LICENSE
@@ -111,6 +111,8 @@ def good_enough_or_overnight(progress):
111
111
  return good_enough or progress.elapsed > 8 * 3600
112
112
  ```
113
113
 
114
+ With constraints on outputs (see "Constraints on outputs" under Constraints), the best so far can break one while nothing has satisfied them all; check `progress.feasible` too before stopping on its value.
115
+
114
116
  Pressing Ctrl+C stops the run too. Either way, `optimize()` stops the workers and returns the best result so far, with `stopped` set.
115
117
 
116
118
  ### Resuming a run
@@ -212,6 +214,38 @@ Constraints should be quick to check: hone checks them for every candidate it co
212
214
 
213
215
  Starting points must satisfy the constraints. If the constraints leave nothing to search, or a region too small to find in 100,000 random draws, the optimizer raises `InfeasibleSearchSpace` when it's created, before any evaluation. Each optimizer keeps to constraints in its own way: random search and Bayesian optimization only consider points that satisfy them, CMA-ES draws a candidate again while it breaks one, and the genetic optimizer moves such a child back toward its fitter parent until it is feasible, which tends to land it near the boundary, where constrained optima usually are. On the benchmark's constrained problems the choice between optimizers follows the same pattern as without constraints; see [benchmarks/README.md](benchmarks/README.md#constrained-problems). [examples/pressure_vessel.py](examples/pressure_vessel.py) designs a pressure vessel of least cost under three constraints and finds the best published design. [examples/maintenance_schedule.py](examples/maintenance_schedule.py) chooses a maintenance schedule for a production line, scored by a noisy simulation of a year, with a constraint on technician hours and a function constraint that depends on the chosen shift; it halves the expected yearly cost of a sensible schedule chosen by hand.
214
216
 
217
+ #### Constraints on outputs
218
+
219
+ Some limits can't be checked until a design has been evaluated: the peak stress a simulation reports, a temperature, a latency. Write them the same way, with `Output` standing for the reported value, and pass them in the same list:
220
+
221
+ ```python
222
+ from hone import BayesianOptimizer, Output, SearchSpace
223
+
224
+ stress = Output("stress")
225
+ search_space = SearchSpace(
226
+ [width, height],
227
+ constraints=[
228
+ width * height <= 40, # on the parameters: checked before evaluating
229
+ stress <= 250, # on an output: judged once the evaluation reports it
230
+ stress <= 50 * width, # outputs and parameters can mix
231
+ ],
232
+ )
233
+
234
+ def simulate(width, height):
235
+ ...
236
+ return {"objective": mass, "stress": peak_stress}
237
+
238
+ result = BayesianOptimizer(search_space).optimize(simulate)
239
+ result.feasible # whether best_params satisfies every limit on the outputs
240
+ result.best_outputs # {"stress": ...} at best_params
241
+ ```
242
+
243
+ With constraints on outputs, the objective returns a dict: its value under `"objective"`, and a number for each output the constraints use. With several objectives, the outputs go in the same dict as the objectives, and a name can be both, so `Output("cost") <= 20` limits an objective. A dict with missing or extra keys, or a value that isn't a number, raises `TypeError`, and NaN or infinity anywhere in it marks the evaluation as failed. `tell(trial, {...})` takes the same dict. Outputs work everywhere parameters do in an expression, including `test >> constraint`, as in `material["steel"] >> (stress <= 400)`. They can't appear in a test, on the left of `>>`, because which parameters the objective is passed can't depend on what it returns. A function constraint takes outputs by name too: `Constraint.function(f, outputs=["stress"])`.
244
+
245
+ A design that breaks a limit on an output has already been evaluated, so it can't be skipped; instead it is ranked by Deb's feasibility rule, with no penalty weight to tune. A design that satisfies every limit beats one that doesn't, those that do rank by their value, and those that don't rank by their total violation. Each violation is a share of its limit when the limit is a number, as in `stress <= 250`, so 10% over a stress limit counts the same as 10% over a deflection limit. A limit that varies with the design, such as `stress <= 50 * width`, a limit of zero and a function constraint count in their own units, so when several limits share a problem, write each with its number on one side, and have a function return a share, such as `stress / LIMIT - 1`. `best_params` is the best design that satisfies every limit. If none did, it is the one that came closest, and `feasible` is `False`. Each generation's statistics count the designs that broke a limit in `infeasible` and leave them out of the fitness figures. A threshold is reached only by a design that satisfies every limit. On a front, only such designs appear, and each point carries its `outputs`.
246
+
247
+ Bayesian optimization makes the most of these limits. It models each limit with a Gaussian process, learning from the designs that broke one, and multiplies its expected improvement by the probability that a candidate satisfies them all, treating the limits as independent, so two limits that say nearly the same thing make it more cautious there than it need be; until it finds a design that does, it looks for one. The other optimizers only learn which designs ranked lower. On the benchmark's engineering problems with their limits on outputs, Bayesian optimization comes close to its results when the same limits are known before evaluating, while the genetic optimizer and CMA-ES lose more; see [benchmarks/README.md](benchmarks/README.md#constraints-on-outputs). Constraints on outputs aren't supported with `noise=True` yet, since a noisy design can pass a limit by luck. `sensitivity()` accepts them and measures only the objective. [examples/welded_beam.py](examples/welded_beam.py) designs a welded beam whose stresses, buckling load and deflection come from an analysis of each design, and gets within about 1% of the best published design in 150 evaluations.
248
+
215
249
  ### Conditional parameters
216
250
 
217
251
  Some settings only exist when another takes certain values: a kernel's settings only for the model that has kernels, a third layer's size only with three layers or more. Write each condition as `test >> parameters`, read "then", and pass them to `SearchSpace`:
@@ -87,6 +87,8 @@ def good_enough_or_overnight(progress):
87
87
  return good_enough or progress.elapsed > 8 * 3600
88
88
  ```
89
89
 
90
+ With constraints on outputs (see "Constraints on outputs" under Constraints), the best so far can break one while nothing has satisfied them all; check `progress.feasible` too before stopping on its value.
91
+
90
92
  Pressing Ctrl+C stops the run too. Either way, `optimize()` stops the workers and returns the best result so far, with `stopped` set.
91
93
 
92
94
  ### Resuming a run
@@ -188,6 +190,38 @@ Constraints should be quick to check: hone checks them for every candidate it co
188
190
 
189
191
  Starting points must satisfy the constraints. If the constraints leave nothing to search, or a region too small to find in 100,000 random draws, the optimizer raises `InfeasibleSearchSpace` when it's created, before any evaluation. Each optimizer keeps to constraints in its own way: random search and Bayesian optimization only consider points that satisfy them, CMA-ES draws a candidate again while it breaks one, and the genetic optimizer moves such a child back toward its fitter parent until it is feasible, which tends to land it near the boundary, where constrained optima usually are. On the benchmark's constrained problems the choice between optimizers follows the same pattern as without constraints; see [benchmarks/README.md](benchmarks/README.md#constrained-problems). [examples/pressure_vessel.py](examples/pressure_vessel.py) designs a pressure vessel of least cost under three constraints and finds the best published design. [examples/maintenance_schedule.py](examples/maintenance_schedule.py) chooses a maintenance schedule for a production line, scored by a noisy simulation of a year, with a constraint on technician hours and a function constraint that depends on the chosen shift; it halves the expected yearly cost of a sensible schedule chosen by hand.
190
192
 
193
+ #### Constraints on outputs
194
+
195
+ Some limits can't be checked until a design has been evaluated: the peak stress a simulation reports, a temperature, a latency. Write them the same way, with `Output` standing for the reported value, and pass them in the same list:
196
+
197
+ ```python
198
+ from hone import BayesianOptimizer, Output, SearchSpace
199
+
200
+ stress = Output("stress")
201
+ search_space = SearchSpace(
202
+ [width, height],
203
+ constraints=[
204
+ width * height <= 40, # on the parameters: checked before evaluating
205
+ stress <= 250, # on an output: judged once the evaluation reports it
206
+ stress <= 50 * width, # outputs and parameters can mix
207
+ ],
208
+ )
209
+
210
+ def simulate(width, height):
211
+ ...
212
+ return {"objective": mass, "stress": peak_stress}
213
+
214
+ result = BayesianOptimizer(search_space).optimize(simulate)
215
+ result.feasible # whether best_params satisfies every limit on the outputs
216
+ result.best_outputs # {"stress": ...} at best_params
217
+ ```
218
+
219
+ With constraints on outputs, the objective returns a dict: its value under `"objective"`, and a number for each output the constraints use. With several objectives, the outputs go in the same dict as the objectives, and a name can be both, so `Output("cost") <= 20` limits an objective. A dict with missing or extra keys, or a value that isn't a number, raises `TypeError`, and NaN or infinity anywhere in it marks the evaluation as failed. `tell(trial, {...})` takes the same dict. Outputs work everywhere parameters do in an expression, including `test >> constraint`, as in `material["steel"] >> (stress <= 400)`. They can't appear in a test, on the left of `>>`, because which parameters the objective is passed can't depend on what it returns. A function constraint takes outputs by name too: `Constraint.function(f, outputs=["stress"])`.
220
+
221
+ A design that breaks a limit on an output has already been evaluated, so it can't be skipped; instead it is ranked by Deb's feasibility rule, with no penalty weight to tune. A design that satisfies every limit beats one that doesn't, those that do rank by their value, and those that don't rank by their total violation. Each violation is a share of its limit when the limit is a number, as in `stress <= 250`, so 10% over a stress limit counts the same as 10% over a deflection limit. A limit that varies with the design, such as `stress <= 50 * width`, a limit of zero and a function constraint count in their own units, so when several limits share a problem, write each with its number on one side, and have a function return a share, such as `stress / LIMIT - 1`. `best_params` is the best design that satisfies every limit. If none did, it is the one that came closest, and `feasible` is `False`. Each generation's statistics count the designs that broke a limit in `infeasible` and leave them out of the fitness figures. A threshold is reached only by a design that satisfies every limit. On a front, only such designs appear, and each point carries its `outputs`.
222
+
223
+ Bayesian optimization makes the most of these limits. It models each limit with a Gaussian process, learning from the designs that broke one, and multiplies its expected improvement by the probability that a candidate satisfies them all, treating the limits as independent, so two limits that say nearly the same thing make it more cautious there than it need be; until it finds a design that does, it looks for one. The other optimizers only learn which designs ranked lower. On the benchmark's engineering problems with their limits on outputs, Bayesian optimization comes close to its results when the same limits are known before evaluating, while the genetic optimizer and CMA-ES lose more; see [benchmarks/README.md](benchmarks/README.md#constraints-on-outputs). Constraints on outputs aren't supported with `noise=True` yet, since a noisy design can pass a limit by luck. `sensitivity()` accepts them and measures only the objective. [examples/welded_beam.py](examples/welded_beam.py) designs a welded beam whose stresses, buckling load and deflection come from an analysis of each design, and gets within about 1% of the best published design in 150 evaluations.
224
+
191
225
  ### Conditional parameters
192
226
 
193
227
  Some settings only exist when another takes certain values: a kernel's settings only for the model that has kernels, a third layer's size only with three layers or more. Write each condition as `test >> parameters`, read "then", and pass them to `SearchSpace`:
@@ -15,7 +15,7 @@ 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
21
  from hone.sensitivity_analysis import Interval, ParameterSensitivity, SensitivityReport, sensitivity
@@ -47,6 +47,7 @@ __all__ = [
47
47
  "NSGA2Config",
48
48
  "Optimizer",
49
49
  "OptimizerConfig",
50
+ "Output",
50
51
  "ParameterSensitivity",
51
52
  "ParetoGenerationStats",
52
53
  "ParetoPoint",
@@ -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()]
@@ -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)
@@ -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"