hone-python 0.10.0__tar.gz → 0.12.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 (46) hide show
  1. {hone_python-0.10.0 → hone_python-0.12.0}/PKG-INFO +113 -3
  2. {hone_python-0.10.0 → hone_python-0.12.0}/README.md +112 -2
  3. {hone_python-0.10.0 → hone_python-0.12.0}/hone/__init__.py +25 -5
  4. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/__init__.py +2 -0
  5. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/__main__.py +33 -0
  6. hone_python-0.12.0/hone/benchmarks/conditional.py +109 -0
  7. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/ml.py +69 -3
  8. hone_python-0.12.0/hone/benchmarks/multi.py +447 -0
  9. {hone_python-0.10.0 → hone_python-0.12.0}/hone/config/__init__.py +1 -0
  10. {hone_python-0.10.0 → hone_python-0.12.0}/hone/config/genetic_optimizer_config.py +3 -2
  11. hone_python-0.12.0/hone/config/multi_objective_config.py +86 -0
  12. {hone_python-0.10.0 → hone_python-0.12.0}/hone/objective_function/objective_function.py +25 -0
  13. hone_python-0.12.0/hone/optimizers/__init__.py +8 -0
  14. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/_gp.py +5 -0
  15. hone_python-0.12.0/hone/optimizers/base.py +247 -0
  16. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/bayesian.py +97 -48
  17. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/choice.py +34 -1
  18. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/cmaes.py +3 -1
  19. hone_python-0.10.0/hone/optimizers/base.py → hone_python-0.12.0/hone/optimizers/core.py +132 -198
  20. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/genetic/__init__.py +1 -0
  21. hone_python-0.10.0/hone/optimizers/genetic/optimizer.py → hone_python-0.12.0/hone/optimizers/genetic/breeding.py +79 -99
  22. hone_python-0.12.0/hone/optimizers/genetic/nsga2.py +115 -0
  23. hone_python-0.12.0/hone/optimizers/genetic/optimizer.py +106 -0
  24. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/genetic/variation.py +10 -3
  25. hone_python-0.12.0/hone/optimizers/multi.py +230 -0
  26. hone_python-0.12.0/hone/optimizers/multi_bayesian.py +153 -0
  27. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/random_search.py +1 -0
  28. {hone_python-0.10.0 → hone_python-0.12.0}/hone/parameters/__init__.py +1 -0
  29. hone_python-0.12.0/hone/parameters/conditions.py +147 -0
  30. {hone_python-0.10.0 → hone_python-0.12.0}/hone/parameters/constraints.py +22 -4
  31. {hone_python-0.10.0 → hone_python-0.12.0}/hone/parameters/parameters.py +204 -43
  32. hone_python-0.12.0/hone/pareto.py +265 -0
  33. {hone_python-0.10.0 → hone_python-0.12.0}/hone/result.py +12 -5
  34. {hone_python-0.10.0 → hone_python-0.12.0}/pyproject.toml +1 -1
  35. hone_python-0.10.0/hone/optimizers/__init__.py +0 -6
  36. {hone_python-0.10.0 → hone_python-0.12.0}/LICENSE +0 -0
  37. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/constrained.py +0 -0
  38. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/problems.py +0 -0
  39. {hone_python-0.10.0 → hone_python-0.12.0}/hone/benchmarks/runner.py +0 -0
  40. {hone_python-0.10.0 → hone_python-0.12.0}/hone/config/bayesian_config.py +0 -0
  41. {hone_python-0.10.0 → hone_python-0.12.0}/hone/config/cmaes_config.py +0 -0
  42. {hone_python-0.10.0 → hone_python-0.12.0}/hone/config/optimizer_config.py +0 -0
  43. {hone_python-0.10.0 → hone_python-0.12.0}/hone/objective_function/__init__.py +0 -0
  44. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/_pool.py +0 -0
  45. {hone_python-0.10.0 → hone_python-0.12.0}/hone/optimizers/genetic/selection.py +0 -0
  46. {hone_python-0.10.0 → hone_python-0.12.0}/hone/py.typed +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hone-python
3
- Version: 0.10.0
3
+ Version: 0.12.0
4
4
  Summary: A python-based optimization engine/library.
5
5
  License-Expression: BSD-3-Clause
6
6
  License-File: LICENSE
@@ -207,6 +207,49 @@ Constraints should be quick to check: hone checks them for every candidate it co
207
207
 
208
208
  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.
209
209
 
210
+ ### Conditional parameters
211
+
212
+ 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`:
213
+
214
+ ```python
215
+ from hone import ChoiceParameter, RangeParameter, SearchSpace
216
+
217
+ model = ChoiceParameter("model", ["svm", "forest"])
218
+ kernel = ChoiceParameter("kernel", ["linear", "rbf"])
219
+ C = RangeParameter("C", 1e-3, 1e3, log=True)
220
+ gamma = RangeParameter("gamma", 1e-5, 1, log=True)
221
+ trees = RangeParameter("trees", 10, 500, integer=True)
222
+
223
+ search_space = SearchSpace(
224
+ [model, kernel, C, gamma, trees],
225
+ conditions=[
226
+ model["svm"] >> [kernel, C],
227
+ kernel["rbf"] >> gamma, # only with an svm too, since kernel is
228
+ model["forest"] >> trees,
229
+ ],
230
+ )
231
+
232
+ def train(model, kernel=None, C=None, gamma=None, trees=None):
233
+ ...
234
+ ```
235
+
236
+ The left of `>>` is a test: a choice parameter indexed by the values that switch the parameters on, such as `model["svm"]` or `optimizer["sgd", "nesterov"]`, or a comparison of range parameters in brackets, such as `(layers >= 3) >> units_3`. The brackets are needed, since Python reads `layers >= 3 >> units_3` as `layers >= (3 >> units_3)`; hone raises an error saying so. The right is a parameter or a list of them, and each parameter can have one condition. Conditions nest: a parameter whose test uses a parameter that is switched off is off too.
237
+
238
+ A parameter that is switched off isn't part of the point. The objective isn't passed it, so give it a default, which hone checks before the run starts; results, progress and `best_params` leave it out; and a starting point must leave it out too. Two points that differ only in a parameter switched off are the same point, so they are averaged together with `noise=True` and the genetic optimizer doesn't count one as new.
239
+
240
+ A constraint applies only while every parameter it uses is switched on, and `test >> constraint` makes a constraint apply only while the test holds:
241
+
242
+ ```python
243
+ depth = RangeParameter("depth", 2, 20, integer=True)
244
+ search_space = SearchSpace(
245
+ [model, trees, depth],
246
+ constraints=[model["forest"] >> (trees * depth <= 2000)],
247
+ conditions=[model["forest"] >> [trees, depth]],
248
+ )
249
+ ```
250
+
251
+ Every optimizer supports conditions; CMA-ES only conditions on range parameters, since it doesn't search choices. Bayesian optimization gains the most: a parameter switched off looks the same to its model whatever value it holds, so values that don't matter add no noise. On the benchmark's conditional problems its error is ×0.0004 that of searching every parameter all the time, at 10 evaluations per dimension. With conditions the genetic optimizer breeds each branch within its own niche by default (`niche_share` of 0.5, below), so a wide, easy branch doesn't crowd out a narrow, better one; see [benchmarks/README.md](benchmarks/README.md#conditional-problems). [examples/choose_a_model.py](examples/choose_a_model.py) chooses a classifier, among an SVM with three kernels, a random forest and logistic regression, together with its settings.
252
+
210
253
  ### Configuration
211
254
 
212
255
  `GeneticOptimizerConfig` validates its values when created. It can also be loaded from a JSON or YAML file:
@@ -219,7 +262,7 @@ Set `seed` to make a run repeatable. `max_evaluations` sets a budget: the run st
219
262
 
220
263
  Parents are chosen by tournament: `tournament_size` (default 4) individuals are drawn and the fittest wins.
221
264
 
222
- When a choice parameter's best option is found late, the genetic optimizer can settle on another one: once most of the population uses one option, a child with a different option inherits numbers tuned for the wrong one and loses. `niche_share=0.5` breeds half of each generation's children within niches of parents that share their choices, so every option keeps tuning its own numbers. On material-selection-10d with 1,000 evaluations per dimension it found the right material in 10 of 10 runs, against 6 of 10 without. It costs some progress on small budgets, so it's off by default.
265
+ When a choice parameter's best option is found late, the genetic optimizer can settle on another one: once most of the population uses one option, a child with a different option inherits numbers tuned for the wrong one and loses. `niche_share=0.5` breeds half of each generation's children within niches of parents that share their choices, so every option keeps tuning its own numbers. On material-selection-10d with 1,000 evaluations per dimension it found the right material in 10 of 10 runs, against 6 of 10 without. It costs some progress on small budgets, so it's off by default, except in a search space with conditions: there each branch is a niche, and 0.5 is the default, since a branch with a better optimum is often harder to find.
223
266
 
224
267
  Each value of a new individual mutates with probability `mutation_rate`: by default 1 over the number of variables, and at least 0.1, so in two variables half of them mutate. A range value moves by a random step whose typical size is a fraction of the width of its range. A choice switches to another option, and a fixed value never changes.
225
268
 
@@ -295,6 +338,45 @@ Other settings, such as `seed`, `maximize`, `noise` or `threshold`, are passed o
295
338
 
296
339
  All four take the same arguments and support `optimize()`, `ask()` and `tell()`. A new optimizer subclasses `Optimizer` and implements `_next_population`, which returns each generation's individuals; the base class handles handing out candidates, recording results and failures, tracking the best result, stopping and the `Result`.
297
340
 
341
+ ### Several objectives
342
+
343
+ When a design is judged on more than one thing, such as accuracy and cost, or mass and stiffness, a weighted sum forces you to price one against the other before seeing what the trade-off looks like, and some trade-offs no weighting can reach. Name each objective and its direction instead, and have the objective function return a dict of them. The run returns the **front**: every design found for which no other is at least as good on every objective and better on one. You choose from it afterwards.
344
+
345
+ ```python
346
+ from hone import NSGA2, NSGA2Config
347
+
348
+ config = NSGA2Config(objectives={"accuracy": "maximize", "cost": "minimize"}, max_evaluations=2000, seed=0)
349
+
350
+ def train(**params):
351
+ ...
352
+ return {"accuracy": accuracy, "cost": cost}
353
+
354
+ result = NSGA2(search_space, config).optimize(train)
355
+ choice = result.front.best("accuracy", where={"cost": 20}) # the most accurate design costing at most 20
356
+ print(choice.params, choice.values)
357
+ ```
358
+
359
+ `optimize()` returns a `ParetoResult`, whose `front` holds `ParetoPoint`s, each with its `params` and `values`. To choose from it:
360
+
361
+ | Method | Returns |
362
+ | --- | --- |
363
+ | `front.best(objective, where={...})` | The best point on one objective, with the others at most (or, for those maximized, at least) the limits given |
364
+ | `front.closest(weights)` | The point nearest the ideal, by augmented Chebyshev distance on objectives scaled from the front's best value of each to its worst. Unlike a weighted sum it can pick any point, including one in a dent in the front. Weights default to equal |
365
+ | `front.ideal`, `front.nadir` | The best and the worst value of each objective on the front |
366
+ | `front.hypervolume(reference)` | The region the front dominates, up to a reference point: one number that grows as the front gets closer and wider |
367
+
368
+ | Optimizer | Config | Approach |
369
+ | --- | --- | --- |
370
+ | `MultiObjectiveBayesian` | `MultiObjectiveBayesianConfig` | Each candidate draws random weights for the objectives and goes where a Gaussian process expects the most improvement in their weighted combination. The first choice for 200 evaluations or fewer. `method="parego"`, the default, models the combination; `method="models"` models each objective, which did better on three objectives at 20 evaluations per dimension and costs a few times more computation per candidate. Supports range and choice parameters |
371
+ | `NSGA2` | `NSGA2Config` | A genetic algorithm that ranks the population by fronts and spreads it along them. The choice for larger budgets; breeds as the genetic optimizer does, so it handles every kind of parameter |
372
+ | `MultiObjectiveRandomSearch` | `MultiObjectiveConfig` | Evaluates random points; useful as a baseline |
373
+
374
+ `choose_pareto_optimizer(search_space, objectives, max_evaluations)` picks `MultiObjectiveBayesian` up to 200 evaluations, unless a choice parameter has `choose_n`, and `NSGA2` otherwise, as the benchmark suggests; other settings are passed on to the chosen optimizer's config. On it, Bayesian optimization's median front beats NSGA2's on 12 of the 13 problem and budget pairs both run on and don't tie.
375
+
376
+ Everything else works as with one objective: constraints, conditions, workers and time limits, failed evaluations, checkpoints, `ask()` and `tell(trial, {...})`, starting points, `save()`, `load()` and `rebuild_optimizer()`. With `noise=True`, each point on the front is an average, with its number of evaluations and the `standard_error` of each objective. `print_progress` prints the size of the front and its hypervolume. A dict with missing or extra keys, or a value that isn't a number, raises `TypeError`; `maximize`, `threshold` and `final_evaluations` don't apply.
377
+
378
+ [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.
379
+
298
380
  ### Benchmarks
299
381
 
300
382
  `hone.benchmarks` runs optimizers on test problems with known optima and reports how close each one gets:
@@ -303,6 +385,7 @@ All four take the same arguments and support `optimize()`, `ask()` and `tell()`.
303
385
  python -m hone.benchmarks # full suite: 36 problems, 10 seeds each, five budgets
304
386
  python -m hone.benchmarks --quick # 6 problems, 5 seeds, three budgets; takes seconds
305
387
  python -m hone.benchmarks --budgets 10 20 # only the budgets you name, in evaluations per dimension
388
+ python -m hone.benchmarks --multi # several objectives: 7 problems, scored by hypervolume gap
306
389
  ```
307
390
 
308
391
  The suite has five standard continuous functions (sphere, ellipsoid, Rosenbrock, Rastrigin and Ackley) in 2, 5 and 10 dimensions, rotated versions of four of them in which the variables interact, and integer, mixed and categorical problems: 36 in all. Each function is shifted so its optimum is away from the centre of the search space. Every optimizer gets exactly the same number of evaluations. Each problem runs at five budgets, 10, 20, 50, 100 and 1,000 evaluations per dimension, because the best optimizer for a slow simulation that allows a few dozen runs is often not the best one for a cheap function evaluated thousands of times. Latest results are in [benchmarks/results.md](benchmarks/results.md).
@@ -351,11 +434,38 @@ Requires Python 3.12 or later and [Poetry](https://python-poetry.org/) 2.
351
434
  | --- | --- |
352
435
  | `make test` | Install the dependencies and run the tests with coverage |
353
436
  | `make lint` | Run ruff, then mypy to check types |
354
- | `make docker-test` | Build the Docker image and run the tests inside it |
437
+ | `make docker-test` | Build the Docker image and run the tests inside it (see [Running in Docker](#running-in-docker)) |
355
438
  | `make benchmark` | Run the full benchmark suite and update `benchmarks/results.md` |
356
439
  | `make benchmark-noisy` | Run the noisy problems and update `benchmarks/noisy-results.md` |
357
440
  | `make benchmark-ml` | Run the machine learning tuning problems and update `benchmarks/ml-results.md` |
358
441
  | `make benchmark-constrained` | Run the constrained problems and update `benchmarks/constrained-results.md` |
442
+ | `make benchmark-conditional` | Run the conditional problems and update `benchmarks/conditional-results.md` |
443
+ | `make benchmark-multi` | Run the multi-objective problems and update `benchmarks/multi-results.md` |
444
+
445
+ ### Running in Docker
446
+
447
+ With [Docker](https://docs.docker.com/get-docker/) installed you can run hone without Python or Poetry on your machine. The image holds hone with its development dependencies, the tests, the examples and the saved benchmark summaries, on Python 3.14.
448
+
449
+ ```sh
450
+ make docker-build # build the image, tagged hone
451
+ make docker-test # run the tests in it
452
+ make docker-shell # a shell in it, with hone installed
453
+ docker run --rm hone python examples/pressure_vessel.py
454
+ ```
455
+
456
+ To run a script of your own, mount its folder and run it from there:
457
+
458
+ ```sh
459
+ docker run --rm -v "$PWD:/work" -w /work hone python my_search.py
460
+ ```
461
+
462
+ To run a benchmark and keep its results, mount the `benchmarks` folder so the files it writes land in your copy:
463
+
464
+ ```sh
465
+ docker run --rm -v "$PWD/benchmarks:/src/benchmarks" hone python -m hone.benchmarks --quick --markdown benchmarks/quick-results.md
466
+ ```
467
+
468
+ Rebuild the image after changing hone's code; changing only the code reuses the cached dependency layer, so it takes seconds.
359
469
 
360
470
  To release, raise `version` in `pyproject.toml` and add a section for it to `CHANGELOG.md`. Once the change is on `main` and its checks pass, CI tags the version, publishes a GitHub release with that section as its notes and the built package attached, and uploads the same package to PyPI as `hone-python`.
361
471
 
@@ -186,6 +186,49 @@ Constraints should be quick to check: hone checks them for every candidate it co
186
186
 
187
187
  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.
188
188
 
189
+ ### Conditional parameters
190
+
191
+ 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`:
192
+
193
+ ```python
194
+ from hone import ChoiceParameter, RangeParameter, SearchSpace
195
+
196
+ model = ChoiceParameter("model", ["svm", "forest"])
197
+ kernel = ChoiceParameter("kernel", ["linear", "rbf"])
198
+ C = RangeParameter("C", 1e-3, 1e3, log=True)
199
+ gamma = RangeParameter("gamma", 1e-5, 1, log=True)
200
+ trees = RangeParameter("trees", 10, 500, integer=True)
201
+
202
+ search_space = SearchSpace(
203
+ [model, kernel, C, gamma, trees],
204
+ conditions=[
205
+ model["svm"] >> [kernel, C],
206
+ kernel["rbf"] >> gamma, # only with an svm too, since kernel is
207
+ model["forest"] >> trees,
208
+ ],
209
+ )
210
+
211
+ def train(model, kernel=None, C=None, gamma=None, trees=None):
212
+ ...
213
+ ```
214
+
215
+ The left of `>>` is a test: a choice parameter indexed by the values that switch the parameters on, such as `model["svm"]` or `optimizer["sgd", "nesterov"]`, or a comparison of range parameters in brackets, such as `(layers >= 3) >> units_3`. The brackets are needed, since Python reads `layers >= 3 >> units_3` as `layers >= (3 >> units_3)`; hone raises an error saying so. The right is a parameter or a list of them, and each parameter can have one condition. Conditions nest: a parameter whose test uses a parameter that is switched off is off too.
216
+
217
+ A parameter that is switched off isn't part of the point. The objective isn't passed it, so give it a default, which hone checks before the run starts; results, progress and `best_params` leave it out; and a starting point must leave it out too. Two points that differ only in a parameter switched off are the same point, so they are averaged together with `noise=True` and the genetic optimizer doesn't count one as new.
218
+
219
+ A constraint applies only while every parameter it uses is switched on, and `test >> constraint` makes a constraint apply only while the test holds:
220
+
221
+ ```python
222
+ depth = RangeParameter("depth", 2, 20, integer=True)
223
+ search_space = SearchSpace(
224
+ [model, trees, depth],
225
+ constraints=[model["forest"] >> (trees * depth <= 2000)],
226
+ conditions=[model["forest"] >> [trees, depth]],
227
+ )
228
+ ```
229
+
230
+ Every optimizer supports conditions; CMA-ES only conditions on range parameters, since it doesn't search choices. Bayesian optimization gains the most: a parameter switched off looks the same to its model whatever value it holds, so values that don't matter add no noise. On the benchmark's conditional problems its error is ×0.0004 that of searching every parameter all the time, at 10 evaluations per dimension. With conditions the genetic optimizer breeds each branch within its own niche by default (`niche_share` of 0.5, below), so a wide, easy branch doesn't crowd out a narrow, better one; see [benchmarks/README.md](benchmarks/README.md#conditional-problems). [examples/choose_a_model.py](examples/choose_a_model.py) chooses a classifier, among an SVM with three kernels, a random forest and logistic regression, together with its settings.
231
+
189
232
  ### Configuration
190
233
 
191
234
  `GeneticOptimizerConfig` validates its values when created. It can also be loaded from a JSON or YAML file:
@@ -198,7 +241,7 @@ Set `seed` to make a run repeatable. `max_evaluations` sets a budget: the run st
198
241
 
199
242
  Parents are chosen by tournament: `tournament_size` (default 4) individuals are drawn and the fittest wins.
200
243
 
201
- When a choice parameter's best option is found late, the genetic optimizer can settle on another one: once most of the population uses one option, a child with a different option inherits numbers tuned for the wrong one and loses. `niche_share=0.5` breeds half of each generation's children within niches of parents that share their choices, so every option keeps tuning its own numbers. On material-selection-10d with 1,000 evaluations per dimension it found the right material in 10 of 10 runs, against 6 of 10 without. It costs some progress on small budgets, so it's off by default.
244
+ When a choice parameter's best option is found late, the genetic optimizer can settle on another one: once most of the population uses one option, a child with a different option inherits numbers tuned for the wrong one and loses. `niche_share=0.5` breeds half of each generation's children within niches of parents that share their choices, so every option keeps tuning its own numbers. On material-selection-10d with 1,000 evaluations per dimension it found the right material in 10 of 10 runs, against 6 of 10 without. It costs some progress on small budgets, so it's off by default, except in a search space with conditions: there each branch is a niche, and 0.5 is the default, since a branch with a better optimum is often harder to find.
202
245
 
203
246
  Each value of a new individual mutates with probability `mutation_rate`: by default 1 over the number of variables, and at least 0.1, so in two variables half of them mutate. A range value moves by a random step whose typical size is a fraction of the width of its range. A choice switches to another option, and a fixed value never changes.
204
247
 
@@ -274,6 +317,45 @@ Other settings, such as `seed`, `maximize`, `noise` or `threshold`, are passed o
274
317
 
275
318
  All four take the same arguments and support `optimize()`, `ask()` and `tell()`. A new optimizer subclasses `Optimizer` and implements `_next_population`, which returns each generation's individuals; the base class handles handing out candidates, recording results and failures, tracking the best result, stopping and the `Result`.
276
319
 
320
+ ### Several objectives
321
+
322
+ When a design is judged on more than one thing, such as accuracy and cost, or mass and stiffness, a weighted sum forces you to price one against the other before seeing what the trade-off looks like, and some trade-offs no weighting can reach. Name each objective and its direction instead, and have the objective function return a dict of them. The run returns the **front**: every design found for which no other is at least as good on every objective and better on one. You choose from it afterwards.
323
+
324
+ ```python
325
+ from hone import NSGA2, NSGA2Config
326
+
327
+ config = NSGA2Config(objectives={"accuracy": "maximize", "cost": "minimize"}, max_evaluations=2000, seed=0)
328
+
329
+ def train(**params):
330
+ ...
331
+ return {"accuracy": accuracy, "cost": cost}
332
+
333
+ result = NSGA2(search_space, config).optimize(train)
334
+ choice = result.front.best("accuracy", where={"cost": 20}) # the most accurate design costing at most 20
335
+ print(choice.params, choice.values)
336
+ ```
337
+
338
+ `optimize()` returns a `ParetoResult`, whose `front` holds `ParetoPoint`s, each with its `params` and `values`. To choose from it:
339
+
340
+ | Method | Returns |
341
+ | --- | --- |
342
+ | `front.best(objective, where={...})` | The best point on one objective, with the others at most (or, for those maximized, at least) the limits given |
343
+ | `front.closest(weights)` | The point nearest the ideal, by augmented Chebyshev distance on objectives scaled from the front's best value of each to its worst. Unlike a weighted sum it can pick any point, including one in a dent in the front. Weights default to equal |
344
+ | `front.ideal`, `front.nadir` | The best and the worst value of each objective on the front |
345
+ | `front.hypervolume(reference)` | The region the front dominates, up to a reference point: one number that grows as the front gets closer and wider |
346
+
347
+ | Optimizer | Config | Approach |
348
+ | --- | --- | --- |
349
+ | `MultiObjectiveBayesian` | `MultiObjectiveBayesianConfig` | Each candidate draws random weights for the objectives and goes where a Gaussian process expects the most improvement in their weighted combination. The first choice for 200 evaluations or fewer. `method="parego"`, the default, models the combination; `method="models"` models each objective, which did better on three objectives at 20 evaluations per dimension and costs a few times more computation per candidate. Supports range and choice parameters |
350
+ | `NSGA2` | `NSGA2Config` | A genetic algorithm that ranks the population by fronts and spreads it along them. The choice for larger budgets; breeds as the genetic optimizer does, so it handles every kind of parameter |
351
+ | `MultiObjectiveRandomSearch` | `MultiObjectiveConfig` | Evaluates random points; useful as a baseline |
352
+
353
+ `choose_pareto_optimizer(search_space, objectives, max_evaluations)` picks `MultiObjectiveBayesian` up to 200 evaluations, unless a choice parameter has `choose_n`, and `NSGA2` otherwise, as the benchmark suggests; other settings are passed on to the chosen optimizer's config. On it, Bayesian optimization's median front beats NSGA2's on 12 of the 13 problem and budget pairs both run on and don't tie.
354
+
355
+ Everything else works as with one objective: constraints, conditions, workers and time limits, failed evaluations, checkpoints, `ask()` and `tell(trial, {...})`, starting points, `save()`, `load()` and `rebuild_optimizer()`. With `noise=True`, each point on the front is an average, with its number of evaluations and the `standard_error` of each objective. `print_progress` prints the size of the front and its hypervolume. A dict with missing or extra keys, or a value that isn't a number, raises `TypeError`; `maximize`, `threshold` and `final_evaluations` don't apply.
356
+
357
+ [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.
358
+
277
359
  ### Benchmarks
278
360
 
279
361
  `hone.benchmarks` runs optimizers on test problems with known optima and reports how close each one gets:
@@ -282,6 +364,7 @@ All four take the same arguments and support `optimize()`, `ask()` and `tell()`.
282
364
  python -m hone.benchmarks # full suite: 36 problems, 10 seeds each, five budgets
283
365
  python -m hone.benchmarks --quick # 6 problems, 5 seeds, three budgets; takes seconds
284
366
  python -m hone.benchmarks --budgets 10 20 # only the budgets you name, in evaluations per dimension
367
+ python -m hone.benchmarks --multi # several objectives: 7 problems, scored by hypervolume gap
285
368
  ```
286
369
 
287
370
  The suite has five standard continuous functions (sphere, ellipsoid, Rosenbrock, Rastrigin and Ackley) in 2, 5 and 10 dimensions, rotated versions of four of them in which the variables interact, and integer, mixed and categorical problems: 36 in all. Each function is shifted so its optimum is away from the centre of the search space. Every optimizer gets exactly the same number of evaluations. Each problem runs at five budgets, 10, 20, 50, 100 and 1,000 evaluations per dimension, because the best optimizer for a slow simulation that allows a few dozen runs is often not the best one for a cheap function evaluated thousands of times. Latest results are in [benchmarks/results.md](benchmarks/results.md).
@@ -330,11 +413,38 @@ Requires Python 3.12 or later and [Poetry](https://python-poetry.org/) 2.
330
413
  | --- | --- |
331
414
  | `make test` | Install the dependencies and run the tests with coverage |
332
415
  | `make lint` | Run ruff, then mypy to check types |
333
- | `make docker-test` | Build the Docker image and run the tests inside it |
416
+ | `make docker-test` | Build the Docker image and run the tests inside it (see [Running in Docker](#running-in-docker)) |
334
417
  | `make benchmark` | Run the full benchmark suite and update `benchmarks/results.md` |
335
418
  | `make benchmark-noisy` | Run the noisy problems and update `benchmarks/noisy-results.md` |
336
419
  | `make benchmark-ml` | Run the machine learning tuning problems and update `benchmarks/ml-results.md` |
337
420
  | `make benchmark-constrained` | Run the constrained problems and update `benchmarks/constrained-results.md` |
421
+ | `make benchmark-conditional` | Run the conditional problems and update `benchmarks/conditional-results.md` |
422
+ | `make benchmark-multi` | Run the multi-objective problems and update `benchmarks/multi-results.md` |
423
+
424
+ ### Running in Docker
425
+
426
+ With [Docker](https://docs.docker.com/get-docker/) installed you can run hone without Python or Poetry on your machine. The image holds hone with its development dependencies, the tests, the examples and the saved benchmark summaries, on Python 3.14.
427
+
428
+ ```sh
429
+ make docker-build # build the image, tagged hone
430
+ make docker-test # run the tests in it
431
+ make docker-shell # a shell in it, with hone installed
432
+ docker run --rm hone python examples/pressure_vessel.py
433
+ ```
434
+
435
+ To run a script of your own, mount its folder and run it from there:
436
+
437
+ ```sh
438
+ docker run --rm -v "$PWD:/work" -w /work hone python my_search.py
439
+ ```
440
+
441
+ To run a benchmark and keep its results, mount the `benchmarks` folder so the files it writes land in your copy:
442
+
443
+ ```sh
444
+ docker run --rm -v "$PWD/benchmarks:/src/benchmarks" hone python -m hone.benchmarks --quick --markdown benchmarks/quick-results.md
445
+ ```
446
+
447
+ Rebuild the image after changing hone's code; changing only the code reuses the cached dependency layer, so it takes seconds.
338
448
 
339
449
  To release, raise `version` in `pyproject.toml` and add a section for it to `CHANGELOG.md`. Once the change is on `main` and its checks pass, CI tags the version, publishes a GitHub release with that section as its notes and the built package attached, and uploads the same package to PyPI as `hone-python`.
340
450
 
@@ -1,33 +1,55 @@
1
- from hone.config import BayesianConfig, CMAESConfig, GeneticOptimizerConfig, OptimizerConfig, SelectionMethod
1
+ from hone.config import BayesianConfig, CMAESConfig, GeneticOptimizerConfig, MultiObjectiveBayesianConfig, MultiObjectiveConfig, NSGA2Config, OptimizerConfig, SelectionMethod
2
2
  from hone.optimizers import (
3
3
  CMAES,
4
4
  BayesianOptimizer,
5
5
  EvaluationFailed,
6
6
  GeneticOptimizer,
7
+ MultiObjectiveBayesian,
8
+ MultiObjectiveOptimizer,
9
+ MultiObjectiveRandomSearch,
10
+ NSGA2,
7
11
  Optimizer,
8
12
  RandomSearch,
9
13
  Trial,
10
14
  UnsupportedSearchSpace,
11
15
  choose_optimizer,
16
+ choose_pareto_optimizer,
12
17
  )
13
- from hone.parameters import ChoiceParameter, Constraint, FixedParameter, InfeasibleSearchSpace, RangeParameter, SearchSpace
18
+ from hone.parameters import ChoiceParameter, Condition, Constraint, FixedParameter, InfeasibleSearchSpace, RangeParameter, SearchSpace
19
+ from hone.pareto import Front, ParetoGenerationStats, ParetoPoint, ParetoProgress, ParetoResult
14
20
  from hone.result import GenerationStats, Progress, Result, RunInfo, print_progress
15
21
 
16
22
  __all__ = [
17
23
  "BayesianConfig",
18
24
  "BayesianOptimizer",
25
+ "ChoiceParameter",
26
+ "choose_optimizer",
27
+ "choose_pareto_optimizer",
19
28
  "CMAES",
20
29
  "CMAESConfig",
21
- "ChoiceParameter",
30
+ "Condition",
22
31
  "Constraint",
23
32
  "EvaluationFailed",
24
33
  "FixedParameter",
34
+ "Front",
25
35
  "GenerationStats",
26
36
  "GeneticOptimizer",
27
37
  "GeneticOptimizerConfig",
28
38
  "InfeasibleSearchSpace",
39
+ "MultiObjectiveBayesian",
40
+ "MultiObjectiveBayesianConfig",
41
+ "MultiObjectiveConfig",
42
+ "MultiObjectiveOptimizer",
43
+ "MultiObjectiveRandomSearch",
44
+ "NSGA2",
45
+ "NSGA2Config",
29
46
  "Optimizer",
30
47
  "OptimizerConfig",
48
+ "ParetoGenerationStats",
49
+ "ParetoPoint",
50
+ "ParetoProgress",
51
+ "ParetoResult",
52
+ "print_progress",
31
53
  "Progress",
32
54
  "RandomSearch",
33
55
  "RangeParameter",
@@ -37,6 +59,4 @@ __all__ = [
37
59
  "SelectionMethod",
38
60
  "Trial",
39
61
  "UnsupportedSearchSpace",
40
- "choose_optimizer",
41
- "print_progress",
42
62
  ]
@@ -1,6 +1,8 @@
1
1
  """Benchmark problems and a runner for comparing optimizers. Run `python -m hone.benchmarks --help`."""
2
+ from .conditional import conditional_problems
2
3
  from .constrained import constrained_problems
3
4
  from .ml import ml_problems
5
+ from .multi import MultiProblem, multi_problems, run_multi_benchmark, summarize_multi
4
6
  from .problems import Problem, noisy_problems, quick_problems, standard_problems
5
7
  from .runner import (
6
8
  BUDGETS,
@@ -6,6 +6,8 @@ from collections.abc import Sequence
6
6
  from importlib.metadata import version
7
7
 
8
8
  from . import ml
9
+ from .conditional import conditional_problems
10
+ from .multi import multi_markdown, multi_problems, run_multi_benchmark, summarize_multi
9
11
  from .constrained import constrained_problems
10
12
  from .problems import noisy_problems, quick_problems, standard_problems
11
13
  from .runner import BUDGETS, load_summaries, regressions, run_benchmark, save_summaries, summarize, to_markdown
@@ -28,6 +30,12 @@ def main(argv: list[str] | None = None) -> int:
28
30
  suite.add_argument("--ml", action="store_true", help="run the machine learning tuning problems instead (needs scikit-learn)")
29
31
  suite.add_argument("--noisy", action="store_true", help="run the problems with noise added to every evaluation instead")
30
32
  suite.add_argument("--constrained", action="store_true", help="run the problems with constraints instead")
33
+ suite.add_argument(
34
+ "--multi", action="store_true", help="run the problems with several objectives instead, scored by hypervolume"
35
+ )
36
+ suite.add_argument(
37
+ "--conditional", action="store_true", help="run the problems with conditional parameters, and their flat versions, instead"
38
+ )
31
39
  parser.add_argument("--seeds", type=int, help="number of seeds per problem (default 10, or 5 with --quick)")
32
40
  parser.add_argument(
33
41
  "--budgets",
@@ -44,6 +52,8 @@ def main(argv: list[str] | None = None) -> int:
44
52
  parser.add_argument("--baseline", help="compare against summaries saved with --save; exit 1 on a regression")
45
53
  args = parser.parse_args(argv)
46
54
 
55
+ if args.multi:
56
+ return _multi(args)
47
57
  default_budgets: Sequence[int]
48
58
  if args.quick:
49
59
  problems, default_budgets = quick_problems(), QUICK_BUDGETS
@@ -53,6 +63,8 @@ def main(argv: list[str] | None = None) -> int:
53
63
  problems, default_budgets = noisy_problems(), NOISY_BUDGETS
54
64
  elif args.constrained:
55
65
  problems, default_budgets = constrained_problems(), BUDGETS
66
+ elif args.conditional:
67
+ problems, default_budgets = conditional_problems(), BUDGETS
56
68
  else:
57
69
  problems, default_budgets = standard_problems(), BUDGETS
58
70
  seeds = args.seeds or (5 if args.quick else 10)
@@ -84,5 +96,26 @@ def main(argv: list[str] | None = None) -> int:
84
96
  return 0
85
97
 
86
98
 
99
+ def _multi(args: argparse.Namespace) -> int:
100
+ """The multi-objective suite: its own runs, scored by hypervolume gap."""
101
+ problems = multi_problems()
102
+ seeds = args.seeds or 10
103
+ budgets = sorted(set(args.budgets or BUDGETS))
104
+ start = time.perf_counter()
105
+ summaries = summarize_multi(run_multi_benchmark(problems, seeds=range(seeds), budgets_per_dimension=budgets, jobs=args.jobs))
106
+ elapsed = time.perf_counter() - start
107
+ table = multi_markdown(summaries)
108
+ print(table)
109
+ setup = f"{len(problems)} problems, {seeds} seeds, budgets of {_join(budgets)} evaluations per dimension"
110
+ print(f"{setup}, in {elapsed:.0f}s")
111
+ if args.markdown:
112
+ with open(args.markdown, "w") as f:
113
+ f.write(f"# Multi-objective benchmark results\n\nGenerated by `python -m hone.benchmarks --multi` with hone {version('hone-python')}: {setup}.\n\n{table}")
114
+ if args.save:
115
+ with open(args.save, "w") as f:
116
+ f.write("[\n" + ",\n".join(s.model_dump_json() for s in summaries) + "\n]\n")
117
+ return 0
118
+
119
+
87
120
  if __name__ == "__main__":
88
121
  sys.exit(main())
@@ -0,0 +1,109 @@
1
+ """Conditional test problems, each in two versions: with conditions, and with every parameter switched on.
2
+
3
+ - branches-3x2d and branches-3x5d: a choice of three branches, each a function of its own
4
+ numbers. The best branch is a steep, narrow bowl reaching 0; the decoys are a wide, shallow
5
+ bowl whose floor is 1 and a shallow Rastrigin grid whose floor is 0.5. Random points score
6
+ better in the decoys, so an optimizer has to look past them.
7
+ - nested-9: a choice of model; one model has a choice of kernel, and one kernel has numbers of
8
+ its own, so the best point is two conditions deep. The other model is a wide, shallow decoy
9
+ whose floor is 0.25.
10
+ - layers-7: a layer count from 1 to 5 whose larger values switch on more numbers, as a
11
+ network's units per layer would be. Three layers is best. Its conditions test a range, so
12
+ CMA-ES can search it.
13
+
14
+ The "-flat" version of each has the same parameters, function and optimum, with no conditions:
15
+ every parameter is always on and the function ignores those it doesn't use, which was the way
16
+ to search such a space before conditions. Comparing the two shows what conditions are worth.
17
+ """
18
+ from typing import Any, Callable
19
+
20
+ import numpy as np
21
+
22
+ from hone.parameters import ChoiceParameter, Condition, Parameter, RangeParameter, SearchSpace
23
+
24
+ from .problems import BOUND, Problem, _shift, rastrigin, sphere
25
+
26
+
27
+ def _problem(name: str, function: Callable[..., float], parameters: list[Parameter], conditions: list[Condition]) -> list[Problem]:
28
+ function.__name__ = name.replace("-", "_")
29
+ return [
30
+ Problem(
31
+ name=name,
32
+ function=function,
33
+ search_space=SearchSpace(parameters, conditions=conditions),
34
+ optimum=0.0,
35
+ tags=frozenset({"conditional"}),
36
+ ),
37
+ Problem(
38
+ name=f"{name}-flat",
39
+ function=function,
40
+ search_space=SearchSpace(parameters),
41
+ optimum=0.0,
42
+ tags=frozenset({"conditional", "flat"}),
43
+ ),
44
+ ]
45
+
46
+
47
+ def _numbers(prefix: str, count: int) -> list[RangeParameter]:
48
+ return [RangeParameter(f"{prefix}{i}", -BOUND, BOUND) for i in range(count)]
49
+
50
+
51
+ def _vector(params: dict[str, Any], numbers: list[RangeParameter]) -> np.ndarray:
52
+ return np.array([params[p.name] for p in numbers], dtype=float)
53
+
54
+
55
+ def branches(dimensions: int) -> list[Problem]:
56
+ name = f"branches-3x{dimensions}d"
57
+ branch = ChoiceParameter("branch", ["narrow", "wide", "grid"])
58
+ numbers = {b: _numbers(f"{b}_", dimensions) for b in branch.choices}
59
+ shifts = {b: _shift(f"{name}/{b}", dimensions) for b in branch.choices}
60
+ # (function, scale, floor) for each branch
61
+ bases = {"narrow": (sphere, 4.0, 0.0), "wide": (sphere, 0.05, 1.0), "grid": (rastrigin, 0.1, 0.5)}
62
+
63
+ def function(branch: str, **params: Any) -> float:
64
+ base, scale, floor = bases[branch]
65
+ return floor + scale * float(base(_vector(params, numbers[branch]) - shifts[branch]))
66
+
67
+ parameters: list[Parameter] = [branch, *(p for b in branch.choices for p in numbers[b])]
68
+ return _problem(name, function, parameters, [branch[b] >> numbers[b] for b in branch.choices])
69
+
70
+
71
+ def nested() -> list[Problem]:
72
+ name = "nested-9"
73
+ model = ChoiceParameter("model", ["kernel_machine", "forest"])
74
+ kernel = ChoiceParameter("kernel", ["linear", "rbf"])
75
+ shared, width, forest = _numbers("s", 2), _numbers("g", 2), _numbers("f", 3)
76
+ centres = {key: _shift(f"{name}/{key}", len(group)) for key, group in [("s", shared), ("g", width), ("f", forest)]}
77
+
78
+ def function(model: str, kernel: str | None = None, **params: Any) -> float:
79
+ if model == "forest":
80
+ return 0.25 + 0.05 * float(sphere(_vector(params, forest) - centres["f"]))
81
+ value = float(sphere(_vector(params, shared) - centres["s"]))
82
+ if kernel == "linear":
83
+ return 0.5 + value
84
+ return value + 4 * float(sphere(_vector(params, width) - centres["g"]))
85
+
86
+ parameters: list[Parameter] = [model, kernel, *shared, *width, *forest]
87
+ conditions = [model["kernel_machine"] >> [kernel, *shared], kernel["rbf"] >> width, model["forest"] >> forest]
88
+ return _problem(name, function, parameters, conditions)
89
+
90
+
91
+ def layers() -> list[Problem]:
92
+ name = "layers-7"
93
+ count = RangeParameter("layers", 1, 5, integer=True)
94
+ rate = RangeParameter("rate", -BOUND, BOUND)
95
+ units = _numbers("units_", 5)
96
+ centre = _shift(f"{name}/units", 5)
97
+ best_rate = float(_shift(f"{name}/rate", 1)[0])
98
+
99
+ def function(layers: int, rate: float, **params: Any) -> float:
100
+ used = units[:layers]
101
+ return 0.5 * abs(layers - 3) + float(sphere(_vector(params, used) - centre[:layers])) + (rate - best_rate) ** 2
102
+
103
+ parameters: list[Parameter] = [count, rate, *units]
104
+ return _problem(name, function, parameters, [(count >= i + 1) >> units[i] for i in range(1, 5)])
105
+
106
+
107
+ def conditional_problems() -> list[Problem]:
108
+ """Each conditional problem, followed by its flat version."""
109
+ return [*branches(2), *branches(5), *nested(), *layers()]