meta-hpo 0.1.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 (75) hide show
  1. meta_hpo-0.1.0/.gitignore +9 -0
  2. meta_hpo-0.1.0/CHANGELOG.md +18 -0
  3. meta_hpo-0.1.0/CONTRIBUTING.md +81 -0
  4. meta_hpo-0.1.0/LICENSE +21 -0
  5. meta_hpo-0.1.0/PKG-INFO +106 -0
  6. meta_hpo-0.1.0/README.md +85 -0
  7. meta_hpo-0.1.0/pyproject.toml +47 -0
  8. meta_hpo-0.1.0/src/metahpo/__init__.py +21 -0
  9. meta_hpo-0.1.0/src/metahpo/facade.py +50 -0
  10. meta_hpo-0.1.0/src/metahpo/operators.py +38 -0
  11. meta_hpo-0.1.0/src/metahpo/optimizers/__init__.py +4 -0
  12. meta_hpo-0.1.0/src/metahpo/optimizers/abc.py +145 -0
  13. meta_hpo-0.1.0/src/metahpo/optimizers/base.py +79 -0
  14. meta_hpo-0.1.0/src/metahpo/py.typed +0 -0
  15. meta_hpo-0.1.0/src/metahpo/space.py +249 -0
  16. meta_hpo-0.1.0/src/metahpo/study.py +57 -0
  17. meta_hpo-0.1.0/tests/conftest.py +308 -0
  18. meta_hpo-0.1.0/tests/test_abc.py +119 -0
  19. meta_hpo-0.1.0/tests/test_abc_acceptance.py +712 -0
  20. meta_hpo-0.1.0/tests/test_abc_boundaries.py +556 -0
  21. meta_hpo-0.1.0/tests/test_abc_coverage.py +955 -0
  22. meta_hpo-0.1.0/tests/test_abc_fuzz.py +222 -0
  23. meta_hpo-0.1.0/tests/test_abc_model.py +1086 -0
  24. meta_hpo-0.1.0/tests/test_abc_partition.py +414 -0
  25. meta_hpo-0.1.0/tests/test_abc_phases.py +509 -0
  26. meta_hpo-0.1.0/tests/test_abc_protocol.py +691 -0
  27. meta_hpo-0.1.0/tests/test_abc_spec.py +404 -0
  28. meta_hpo-0.1.0/tests/test_api_contract.py +550 -0
  29. meta_hpo-0.1.0/tests/test_base.py +162 -0
  30. meta_hpo-0.1.0/tests/test_base_coverage.py +76 -0
  31. meta_hpo-0.1.0/tests/test_base_rng.py +82 -0
  32. meta_hpo-0.1.0/tests/test_base_spec.py +209 -0
  33. meta_hpo-0.1.0/tests/test_base_specified.py +149 -0
  34. meta_hpo-0.1.0/tests/test_determinism.py +448 -0
  35. meta_hpo-0.1.0/tests/test_end_to_end.py +621 -0
  36. meta_hpo-0.1.0/tests/test_facade.py +268 -0
  37. meta_hpo-0.1.0/tests/test_facade_boundaries.py +223 -0
  38. meta_hpo-0.1.0/tests/test_facade_budget.py +61 -0
  39. meta_hpo-0.1.0/tests/test_facade_coverage.py +615 -0
  40. meta_hpo-0.1.0/tests/test_facade_direction.py +117 -0
  41. meta_hpo-0.1.0/tests/test_facade_doubles.py +1115 -0
  42. meta_hpo-0.1.0/tests/test_facade_fuzz.py +577 -0
  43. meta_hpo-0.1.0/tests/test_facade_grammar.py +41 -0
  44. meta_hpo-0.1.0/tests/test_facade_integration.py +768 -0
  45. meta_hpo-0.1.0/tests/test_facade_partition.py +183 -0
  46. meta_hpo-0.1.0/tests/test_facade_spec.py +267 -0
  47. meta_hpo-0.1.0/tests/test_fuzz.py +1586 -0
  48. meta_hpo-0.1.0/tests/test_fuzz_grammar.py +1037 -0
  49. meta_hpo-0.1.0/tests/test_operators.py +166 -0
  50. meta_hpo-0.1.0/tests/test_operators_boundaries.py +130 -0
  51. meta_hpo-0.1.0/tests/test_operators_coverage.py +336 -0
  52. meta_hpo-0.1.0/tests/test_operators_fuzz.py +229 -0
  53. meta_hpo-0.1.0/tests/test_operators_mutation.py +849 -0
  54. meta_hpo-0.1.0/tests/test_operators_partition.py +78 -0
  55. meta_hpo-0.1.0/tests/test_regression.py +1224 -0
  56. meta_hpo-0.1.0/tests/test_space.py +43 -0
  57. meta_hpo-0.1.0/tests/test_space_boundaries.py +558 -0
  58. meta_hpo-0.1.0/tests/test_space_coverage.py +744 -0
  59. meta_hpo-0.1.0/tests/test_space_errors.py +248 -0
  60. meta_hpo-0.1.0/tests/test_space_fuzz.py +602 -0
  61. meta_hpo-0.1.0/tests/test_space_grammar.py +87 -0
  62. meta_hpo-0.1.0/tests/test_space_move.py +213 -0
  63. meta_hpo-0.1.0/tests/test_space_partition.py +534 -0
  64. meta_hpo-0.1.0/tests/test_space_rows.py +99 -0
  65. meta_hpo-0.1.0/tests/test_space_sample.py +87 -0
  66. meta_hpo-0.1.0/tests/test_space_spec.py +255 -0
  67. meta_hpo-0.1.0/tests/test_space_specified.py +170 -0
  68. meta_hpo-0.1.0/tests/test_static.py +1063 -0
  69. meta_hpo-0.1.0/tests/test_study.py +186 -0
  70. meta_hpo-0.1.0/tests/test_study_coverage.py +210 -0
  71. meta_hpo-0.1.0/tests/test_study_partition.py +141 -0
  72. meta_hpo-0.1.0/tests/test_study_spec.py +118 -0
  73. meta_hpo-0.1.0/tests/test_study_specified.py +89 -0
  74. meta_hpo-0.1.0/tests/test_suite_layout.py +1760 -0
  75. meta_hpo-0.1.0/tests/test_traceability.py +1550 -0
@@ -0,0 +1,9 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .pytest_cache/
4
+ .mypy_cache/
5
+ .ruff_cache/
6
+ build/
7
+ dist/
8
+ *.egg-info/
9
+ .venv/
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
+ and the project uses [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-10-31
10
+
11
+ ### Added
12
+
13
+ - `Space` with `Float`, `Int` and `Categorical` parameters, decoded from the unit cube in vectorised numpy.
14
+ - `ABCOptimizer`: Artificial Bee Colony behind an ask/tell interface, following the phase order of the
15
+ original implementation.
16
+ - `optimize()` for one-call optimisation, returning a `Study` with every trial and the best one.
17
+ - Caching of repeated parameter sets, so a configuration is never trained twice.
18
+ - NaN and infinite scores are treated as the worst value for the chosen direction.
@@ -0,0 +1,81 @@
1
+ # Contributing to meta-hpo
2
+
3
+ Thank you for helping. This guide covers setting up, checking your work and opening a pull request.
4
+
5
+ ## Setup
6
+
7
+ ```console
8
+ git clone https://github.com/mr-ozdemir/meta-hpo.git
9
+ cd meta-hpo
10
+ python -m venv .venv
11
+ source .venv/bin/activate
12
+ pip install -e ".[dev]"
13
+ ```
14
+
15
+ On Windows, activate the environment with `.venv\Scripts\activate`.
16
+
17
+ ## Checks
18
+
19
+ Every commit must pass these locally; CI runs the same commands:
20
+
21
+ ```console
22
+ ruff check .
23
+ ruff format --check .
24
+ mypy
25
+ pytest
26
+ ```
27
+
28
+ ## Style
29
+
30
+ - Formatting and linting are done by Ruff; types are checked by mypy in strict mode.
31
+ - No `#` comment lines in Python, YAML or TOML files. Explanations belong in docstrings or in the text.
32
+ - Line endings are LF; `.gitattributes` takes care of it.
33
+ - Inner loops work on numpy arrays; single values use plain Python, because a numpy call on one number
34
+ costs more than the arithmetic itself. The exception is a single-value path that must agree bit for bit
35
+ with its array path, such as the log decode of `Space.move`.
36
+
37
+ ## Tests
38
+
39
+ - Every change in behaviour comes with a test.
40
+ - Tests are deterministic: pass a `seed` to anything random.
41
+ - A new optimizer needs at least a convergence test on a benchmark function, a same-seed-same-result test
42
+ and a test of its ask/tell protocol.
43
+ - Each test file must also pass on its own, and the suite must pass in reverse order:
44
+ `METAHPO_TEST_REVERSE=1 pytest`.
45
+ - Coverage is measured with `coverage run -m pytest` and `coverage report -m --branch`; every statement and
46
+ branch of `src/metahpo` outside abstract methods is covered.
47
+ - `docs/test-izlenebilirlik.md` maps each test-writing rule to the tests that satisfy it; update it when a
48
+ test is added for a new rule.
49
+
50
+ ## Branches and pull requests
51
+
52
+ - `master` holds released code and `develop` collects finished work.
53
+ Neither receives direct pushes, and force pushes are never used.
54
+ - Work happens on a personal branch, kept up to date with `git merge --ff-only origin/develop`.
55
+ - Open the pull request against `develop` and ask the other maintainer for review.
56
+ Describe what changed, which tests were added, and the related decisions.
57
+ - Pull requests are merged with a merge commit only, by a maintainer other than the author.
58
+ - One topic per pull request.
59
+
60
+ ## Commits
61
+
62
+ - Short, English, imperative subject line: "Add log scale to Int", "Speed up neighbour moves".
63
+ - No `Co-authored-by` lines and no tool names in the message.
64
+
65
+ ## Changelog
66
+
67
+ User-facing changes get a line under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), in the section
68
+ that fits: Added, Changed, Deprecated, Removed, Fixed or Security.
69
+
70
+ ## Releases
71
+
72
+ - Releases are made from `master` by the repository owner.
73
+ - The version in `pyproject.toml` and `metahpo.__version__` is set, and `## [Unreleased]` in the changelog
74
+ gets a dated version heading, through the usual pull requests.
75
+ - Pushing a tag `vX.Y.Z` on `master` runs the release workflow: it checks that the tag matches the package
76
+ version, builds the sdist and wheel, and publishes them to PyPI with trusted publishing, without tokens.
77
+
78
+ ## Reporting bugs
79
+
80
+ Open an issue with a minimal script that reproduces the problem, the expected result, and your Python,
81
+ numpy and meta-hpo versions.
meta_hpo-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Muhammet Ozdemir
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,106 @@
1
+ Metadata-Version: 2.5
2
+ Name: meta-hpo
3
+ Version: 0.1.0
4
+ Summary: Metaheuristic hyperparameter optimization: a fast numpy core with an ask/tell interface.
5
+ Project-URL: Repository, https://github.com/mr-ozdemir/meta-hpo
6
+ Author-email: Muhammet Ozdemir <mr.ozdemir34@gmail.com>
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: artificial bee colony,automl,hyperparameter optimization,metaheuristics
10
+ Classifier: Development Status :: 2 - Pre-Alpha
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
14
+ Requires-Python: >=3.10
15
+ Requires-Dist: numpy>=1.23
16
+ Provides-Extra: dev
17
+ Requires-Dist: mypy>=1.8; extra == 'dev'
18
+ Requires-Dist: pytest>=7; extra == 'dev'
19
+ Requires-Dist: ruff>=0.5; extra == 'dev'
20
+ Description-Content-Type: text/markdown
21
+
22
+ # meta-hpo
23
+
24
+ [![CI](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml/badge.svg)](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml)
25
+ [![PyPI](https://img.shields.io/pypi/v/meta-hpo.svg)](https://pypi.org/project/meta-hpo/)
26
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
27
+ [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
28
+
29
+ Metaheuristic hyperparameter optimization for Python, with a small numpy core.
30
+
31
+ You describe a search space and a function that trains your model and returns a score.
32
+ meta-hpo searches for the parameters that maximise or minimise that score.
33
+ The first optimizer is the Artificial Bee Colony (ABC); more metaheuristics will follow behind the same interface.
34
+
35
+ ## Installation
36
+
37
+ ```console
38
+ pip install meta-hpo
39
+ ```
40
+
41
+ meta-hpo needs Python 3.10+ and numpy.
42
+
43
+ ## Quick start
44
+
45
+ ```python
46
+ import metahpo as mh
47
+
48
+ space = mh.Space(
49
+ {
50
+ "lr": mh.Float(1e-4, 1e-2, log=True),
51
+ "kernel": mh.Categorical([3, 5, 7]),
52
+ "units": mh.Int(16, 256),
53
+ "dropout": mh.Float(0.0, 0.5),
54
+ }
55
+ )
56
+
57
+
58
+ def train(params):
59
+ model = build_model(params["kernel"], params["units"], params["dropout"])
60
+ return fit_and_score(model, lr=params["lr"])
61
+
62
+
63
+ study = mh.optimize(train, space, direction="max", max_evals=300, seed=1)
64
+ print(study.best_params, study.best_score)
65
+ ```
66
+
67
+ `train` can do anything: a Keras or PyTorch training run, cross-validation, an F1 score.
68
+ Its training budget is entirely yours; meta-hpo only counts evaluations.
69
+
70
+ ## Ask and tell
71
+
72
+ For full control over where and how candidates are evaluated:
73
+
74
+ ```python
75
+ opt = mh.ABCOptimizer(space, direction="max", colony_size=10, limit=15, seed=1)
76
+
77
+ for _ in range(300):
78
+ candidates = opt.ask()
79
+ opt.tell(candidates, [train(c.params) for c in candidates])
80
+
81
+ print(opt.best_params, opt.best_score)
82
+ ```
83
+
84
+ ## Search space
85
+
86
+ | Parameter | Values | Example |
87
+ |---|---|---|
88
+ | `Float(low, high, log=False)` | real numbers in `[low, high]` | `Float(1e-4, 1e-2, log=True)` |
89
+ | `Int(low, high, log=False)` | integers `low..high`, inclusive | `Int(16, 256)` |
90
+ | `Categorical(choices)` | one of `choices` | `Categorical(["relu", "tanh"])` |
91
+
92
+ Optimizers search the unit cube `[0, 1]^d`; the space maps each point to typed parameters.
93
+
94
+ ## Behaviour
95
+
96
+ - A score of NaN or infinity counts as the worst possible value for the chosen direction.
97
+ - With `cache=True` (the default), a repeated parameter set reuses its earlier score instead of training again.
98
+ - The same `seed` reproduces the same search.
99
+
100
+ ## Contributing
101
+
102
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
103
+
104
+ ## License
105
+
106
+ [MIT](LICENSE)
@@ -0,0 +1,85 @@
1
+ # meta-hpo
2
+
3
+ [![CI](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml/badge.svg)](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/meta-hpo.svg)](https://pypi.org/project/meta-hpo/)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+ [![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
7
+
8
+ Metaheuristic hyperparameter optimization for Python, with a small numpy core.
9
+
10
+ You describe a search space and a function that trains your model and returns a score.
11
+ meta-hpo searches for the parameters that maximise or minimise that score.
12
+ The first optimizer is the Artificial Bee Colony (ABC); more metaheuristics will follow behind the same interface.
13
+
14
+ ## Installation
15
+
16
+ ```console
17
+ pip install meta-hpo
18
+ ```
19
+
20
+ meta-hpo needs Python 3.10+ and numpy.
21
+
22
+ ## Quick start
23
+
24
+ ```python
25
+ import metahpo as mh
26
+
27
+ space = mh.Space(
28
+ {
29
+ "lr": mh.Float(1e-4, 1e-2, log=True),
30
+ "kernel": mh.Categorical([3, 5, 7]),
31
+ "units": mh.Int(16, 256),
32
+ "dropout": mh.Float(0.0, 0.5),
33
+ }
34
+ )
35
+
36
+
37
+ def train(params):
38
+ model = build_model(params["kernel"], params["units"], params["dropout"])
39
+ return fit_and_score(model, lr=params["lr"])
40
+
41
+
42
+ study = mh.optimize(train, space, direction="max", max_evals=300, seed=1)
43
+ print(study.best_params, study.best_score)
44
+ ```
45
+
46
+ `train` can do anything: a Keras or PyTorch training run, cross-validation, an F1 score.
47
+ Its training budget is entirely yours; meta-hpo only counts evaluations.
48
+
49
+ ## Ask and tell
50
+
51
+ For full control over where and how candidates are evaluated:
52
+
53
+ ```python
54
+ opt = mh.ABCOptimizer(space, direction="max", colony_size=10, limit=15, seed=1)
55
+
56
+ for _ in range(300):
57
+ candidates = opt.ask()
58
+ opt.tell(candidates, [train(c.params) for c in candidates])
59
+
60
+ print(opt.best_params, opt.best_score)
61
+ ```
62
+
63
+ ## Search space
64
+
65
+ | Parameter | Values | Example |
66
+ |---|---|---|
67
+ | `Float(low, high, log=False)` | real numbers in `[low, high]` | `Float(1e-4, 1e-2, log=True)` |
68
+ | `Int(low, high, log=False)` | integers `low..high`, inclusive | `Int(16, 256)` |
69
+ | `Categorical(choices)` | one of `choices` | `Categorical(["relu", "tanh"])` |
70
+
71
+ Optimizers search the unit cube `[0, 1]^d`; the space maps each point to typed parameters.
72
+
73
+ ## Behaviour
74
+
75
+ - A score of NaN or infinity counts as the worst possible value for the chosen direction.
76
+ - With `cache=True` (the default), a repeated parameter set reuses its earlier score instead of training again.
77
+ - The same `seed` reproduces the same search.
78
+
79
+ ## Contributing
80
+
81
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).
82
+
83
+ ## License
84
+
85
+ [MIT](LICENSE)
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.21"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "meta-hpo"
7
+ version = "0.1.0"
8
+ description = "Metaheuristic hyperparameter optimization: a fast numpy core with an ask/tell interface."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ authors = [{ name = "Muhammet Ozdemir", email = "mr.ozdemir34@gmail.com" }]
13
+ keywords = ["hyperparameter optimization", "metaheuristics", "artificial bee colony", "automl"]
14
+ classifiers = [
15
+ "Development Status :: 2 - Pre-Alpha",
16
+ "Intended Audience :: Science/Research",
17
+ "Programming Language :: Python :: 3",
18
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
19
+ ]
20
+ dependencies = ["numpy>=1.23"]
21
+
22
+ [project.optional-dependencies]
23
+ dev = ["pytest>=7", "ruff>=0.5", "mypy>=1.8"]
24
+
25
+ [project.urls]
26
+ Repository = "https://github.com/mr-ozdemir/meta-hpo"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["src/metahpo"]
30
+
31
+ [tool.ruff]
32
+ line-length = 110
33
+ target-version = "py310"
34
+
35
+ [tool.ruff.lint]
36
+ select = ["E", "F", "W", "I", "B", "UP", "NPY"]
37
+
38
+ [tool.mypy]
39
+ files = ["src/metahpo"]
40
+ python_version = "3.10"
41
+ strict = true
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
45
+
46
+ [tool.hatch.build.targets.sdist]
47
+ include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "CONTRIBUTING.md", "pyproject.toml"]
@@ -0,0 +1,21 @@
1
+ """meta-hpo: metaheuristic hyperparameter optimization."""
2
+
3
+ from metahpo.facade import optimize
4
+ from metahpo.optimizers import ABCOptimizer, Candidate, Optimizer
5
+ from metahpo.space import Categorical, Float, Int, Space
6
+ from metahpo.study import Study, Trial
7
+
8
+ __version__ = "0.1.0"
9
+
10
+ __all__ = [
11
+ "ABCOptimizer",
12
+ "Candidate",
13
+ "Categorical",
14
+ "Float",
15
+ "Int",
16
+ "Optimizer",
17
+ "Space",
18
+ "Study",
19
+ "Trial",
20
+ "optimize",
21
+ ]
@@ -0,0 +1,50 @@
1
+ """One-call optimisation: `optimize(function, space, direction=...)`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Callable
6
+ from typing import Any
7
+
8
+ from metahpo.optimizers.abc import ABCOptimizer
9
+ from metahpo.optimizers.base import Direction, Optimizer
10
+ from metahpo.space import Space
11
+ from metahpo.study import Study, Trial
12
+
13
+ Objective = Callable[[dict[str, Any]], float]
14
+
15
+
16
+ def optimize(
17
+ function: Objective,
18
+ space: Space,
19
+ direction: Direction = "min",
20
+ max_evals: int = 500,
21
+ optimizer: Optimizer | None = None,
22
+ seed: int | None = None,
23
+ cache: bool = True,
24
+ ) -> Study:
25
+ """Search `space` for the parameters that minimise or maximise `function(params) -> score`.
26
+
27
+ `function` receives a dict of parameter values and returns a score (accuracy, F1, loss, ...); what it
28
+ does inside, including its own training budget, is entirely up to the user. `max_evals` counts the
29
+ optimizer's evaluations; with `cache=True` a repeated parameter set reuses the earlier score instead of
30
+ calling `function` again. The default optimizer is ABCOptimizer.
31
+ """
32
+ if max_evals < 1:
33
+ raise ValueError("max_evals must be at least 1")
34
+ opt = optimizer or ABCOptimizer(space, direction=direction, seed=seed)
35
+ if opt.direction != direction or opt.space is not space:
36
+ raise ValueError("the optimizer must use the same space and direction as optimize()")
37
+ study = Study(direction)
38
+ seen: dict[tuple[Any, ...], float] = {}
39
+ while len(study.trials) < max_evals:
40
+ cands = opt.ask()[: max_evals - len(study.trials)]
41
+ scores = []
42
+ for cand in cands:
43
+ cached = cache and cand.key in seen
44
+ score = seen[cand.key] if cached else float(function(cand.params))
45
+ if cache:
46
+ seen.setdefault(cand.key, score)
47
+ scores.append(score)
48
+ study.trials.append(Trial(len(study.trials), cand.params, score, cached, cand.x))
49
+ opt.tell(cands, scores)
50
+ return study
@@ -0,0 +1,38 @@
1
+ """ABC building blocks as plain numpy functions on arrays (Karaboga & Basturk, 2007)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+
7
+ import numpy as np
8
+ from numpy.typing import NDArray
9
+
10
+ FloatArray = NDArray[np.float64]
11
+
12
+
13
+ def neighbour_value(x_ij: float, x_kj: float, phi: float) -> float:
14
+ """v_ij = x_ij + phi * (x_ij - x_kj), phi in [-1, 1], clipped to [0, 1] like the original ABC."""
15
+ v = x_ij + phi * (x_ij - x_kj)
16
+ return 0.0 if v < 0.0 else 1.0 if v > 1.0 else v
17
+
18
+
19
+ def fitness(f: FloatArray) -> FloatArray:
20
+ """Fitness of minimisation values: 1 / (1 + f) for f >= 0, 1 + |f| otherwise; +inf gives 0."""
21
+ f = np.asarray(f, dtype=np.float64)
22
+ with np.errstate(divide="ignore", over="ignore"):
23
+ return np.where(f >= 0, 1.0 / (1.0 + np.maximum(f, 0.0)), 1.0 + np.abs(f))
24
+
25
+
26
+ def fitness_scalar(f: float) -> float:
27
+ """`fitness` for one value without numpy overhead."""
28
+ if f >= 0:
29
+ return 0.0 if f == math.inf else 1.0 / (1.0 + f)
30
+ return 1.0 + abs(f)
31
+
32
+
33
+ def onlooker_probabilities(fit: FloatArray) -> FloatArray:
34
+ """p_i = 0.9 * fit_i / max(fit) + 0.1; all-zero fitness gives equal probabilities."""
35
+ top = float(np.max(fit))
36
+ if top <= 0.0:
37
+ return np.ones_like(fit)
38
+ return 0.9 * (fit / top) + 0.1
@@ -0,0 +1,4 @@
1
+ from metahpo.optimizers.abc import ABCOptimizer
2
+ from metahpo.optimizers.base import Candidate, Optimizer
3
+
4
+ __all__ = ["ABCOptimizer", "Candidate", "Optimizer"]
@@ -0,0 +1,145 @@
1
+ """Artificial Bee Colony (Karaboga & Basturk, 2007) behind the ask/tell interface.
2
+
3
+ The phases run in the same order and with the same rules as the original hyp_optimizer implementation:
4
+ employed bees one food source after another, onlookers chosen by roulette sweep (p = 0.9 * fit / max + 0.1)
5
+ with each improvement visible to the next onlooker, and at most one scout per cycle. Only the initial
6
+ population is handed out as a batch, because its evaluations are independent.
7
+
8
+ A neighbour differs from its food source in one coordinate, so only that coordinate is decoded again;
9
+ the rest of the decoded parameters are copied from the source.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from collections.abc import Sequence
15
+ from typing import Any
16
+
17
+ import numpy as np
18
+
19
+ from metahpo import operators
20
+ from metahpo.optimizers.base import Candidate, Direction, Optimizer
21
+ from metahpo.space import Space
22
+
23
+
24
+ class ABCOptimizer(Optimizer):
25
+ def __init__(
26
+ self,
27
+ space: Space,
28
+ direction: Direction = "min",
29
+ colony_size: int = 10,
30
+ limit: int = 15,
31
+ seed: int | None = None,
32
+ ) -> None:
33
+ super().__init__(space, direction, seed)
34
+ if colony_size < 4:
35
+ raise ValueError("colony_size must be at least 4 (two food sources)")
36
+ if limit < 1:
37
+ raise ValueError("limit must be at least 1")
38
+ self.food_number = sn = colony_size // 2
39
+ self.limit = limit
40
+ self.foods = np.zeros((sn, space.dim))
41
+ self.f = [float("inf")] * sn
42
+ self.fit = [0.0] * sn
43
+ self.trial = [0] * sn
44
+ self.prob = [1.0] * sn
45
+ self._keys: list[tuple[Any, ...]] = [()] * sn
46
+ self._params: list[dict[str, Any]] = [{}] * sn
47
+ self.phase = "init"
48
+ self.cycle = 0
49
+ self._employed_i = 0
50
+ self._onlooker_i = 0
51
+ self._onlooker_t = 0
52
+ self._initialised = [False] * sn
53
+ self._pending: dict[int, tuple[str, int]] = {}
54
+
55
+ def ask(self) -> list[Candidate]:
56
+ if self.phase == "init":
57
+ waiting = {i for kind, i in self._pending.values() if kind == "init"}
58
+ todo = [i for i, done in enumerate(self._initialised) if not done and i not in waiting]
59
+ if not todo:
60
+ raise RuntimeError("tell the pending initial candidates before asking again")
61
+ return self._issue(self._candidates(self.space.sample(self.rng, len(todo))), "init", todo)
62
+ if self._pending:
63
+ raise RuntimeError("tell the pending candidate before asking again")
64
+ if self.phase == "scout":
65
+ worst = max(range(self.food_number), key=self.trial.__getitem__)
66
+ if self.trial[worst] >= self.limit:
67
+ return self._issue(self._candidates(self.space.sample(self.rng, 1)), "scout", [worst])
68
+ self._end_cycle()
69
+ if self.phase == "employed":
70
+ return self._issue([self._neighbour(self._employed_i)], "employed", [self._employed_i])
71
+ while self._uniform() >= self.prob[self._onlooker_i]:
72
+ self._onlooker_i = (self._onlooker_i + 1) % self.food_number
73
+ return self._issue([self._neighbour(self._onlooker_i)], "onlooker", [self._onlooker_i])
74
+
75
+ def tell(self, candidates: Sequence[Candidate], scores: Sequence[float]) -> None:
76
+ if len(candidates) != len(scores):
77
+ raise ValueError("candidates and scores must have the same length")
78
+ for cand, score in zip(candidates, scores, strict=True):
79
+ if cand.id not in self._pending:
80
+ raise ValueError(f"candidate {cand.id} was not asked for or was already told")
81
+ kind, i = self._pending.pop(cand.id)
82
+ f = self._internal(float(score))
83
+ if f < self.best_f or self.best_x is None:
84
+ self.best_f, self.best_x = f, cand.x.copy()
85
+ if kind == "init":
86
+ self._replace(i, cand, f)
87
+ self._initialised[i] = True
88
+ if all(self._initialised):
89
+ self.phase = "employed"
90
+ elif kind == "scout":
91
+ self._replace(i, cand, f)
92
+ self._end_cycle()
93
+ else:
94
+ if operators.fitness_scalar(f) > self.fit[i]:
95
+ self._replace(i, cand, f)
96
+ else:
97
+ self.trial[i] += 1
98
+ self._advance(kind)
99
+
100
+ def _neighbour(self, i: int) -> Candidate:
101
+ """Moves one random coordinate j of food i towards or away from a random other food k."""
102
+ sn, d = self.food_number, self.space.dim
103
+ j = min(int(self._uniform() * d), d - 1)
104
+ k = min(int(self._uniform() * (sn - 1)), sn - 2)
105
+ k += k >= i
106
+ phi = 2.0 * self._uniform() - 1.0
107
+ v = operators.neighbour_value(float(self.foods[i, j]), float(self.foods[k, j]), phi)
108
+ x = self.foods[i].copy()
109
+ x[j] = v
110
+ key, params = self.space.move(self._keys[i], self._params[i], j, v)
111
+ cand = Candidate(self._next_id, x, params, key)
112
+ self._next_id += 1
113
+ return cand
114
+
115
+ def _issue(self, cands: list[Candidate], kind: str, foods: list[int]) -> list[Candidate]:
116
+ for cand, i in zip(cands, foods, strict=True):
117
+ self._pending[cand.id] = (kind, i)
118
+ return cands
119
+
120
+ def _replace(self, i: int, cand: Candidate, f: float) -> None:
121
+ self.foods[i] = cand.x
122
+ self._keys[i] = cand.key
123
+ self._params[i] = dict(cand.params)
124
+ self.f[i] = f
125
+ self.fit[i] = operators.fitness_scalar(f)
126
+ self.trial[i] = 0
127
+
128
+ def _advance(self, kind: str) -> None:
129
+ if kind == "employed":
130
+ self._employed_i += 1
131
+ if self._employed_i == self.food_number:
132
+ self.prob = operators.onlooker_probabilities(np.array(self.fit)).tolist()
133
+ self.phase = "onlooker"
134
+ self._onlooker_i = 0
135
+ self._onlooker_t = 0
136
+ else:
137
+ self._onlooker_t += 1
138
+ self._onlooker_i = (self._onlooker_i + 1) % self.food_number
139
+ if self._onlooker_t == self.food_number:
140
+ self.phase = "scout"
141
+
142
+ def _end_cycle(self) -> None:
143
+ self.cycle += 1
144
+ self.phase = "employed"
145
+ self._employed_i = 0