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.
- meta_hpo-0.1.0/.gitignore +9 -0
- meta_hpo-0.1.0/CHANGELOG.md +18 -0
- meta_hpo-0.1.0/CONTRIBUTING.md +81 -0
- meta_hpo-0.1.0/LICENSE +21 -0
- meta_hpo-0.1.0/PKG-INFO +106 -0
- meta_hpo-0.1.0/README.md +85 -0
- meta_hpo-0.1.0/pyproject.toml +47 -0
- meta_hpo-0.1.0/src/metahpo/__init__.py +21 -0
- meta_hpo-0.1.0/src/metahpo/facade.py +50 -0
- meta_hpo-0.1.0/src/metahpo/operators.py +38 -0
- meta_hpo-0.1.0/src/metahpo/optimizers/__init__.py +4 -0
- meta_hpo-0.1.0/src/metahpo/optimizers/abc.py +145 -0
- meta_hpo-0.1.0/src/metahpo/optimizers/base.py +79 -0
- meta_hpo-0.1.0/src/metahpo/py.typed +0 -0
- meta_hpo-0.1.0/src/metahpo/space.py +249 -0
- meta_hpo-0.1.0/src/metahpo/study.py +57 -0
- meta_hpo-0.1.0/tests/conftest.py +308 -0
- meta_hpo-0.1.0/tests/test_abc.py +119 -0
- meta_hpo-0.1.0/tests/test_abc_acceptance.py +712 -0
- meta_hpo-0.1.0/tests/test_abc_boundaries.py +556 -0
- meta_hpo-0.1.0/tests/test_abc_coverage.py +955 -0
- meta_hpo-0.1.0/tests/test_abc_fuzz.py +222 -0
- meta_hpo-0.1.0/tests/test_abc_model.py +1086 -0
- meta_hpo-0.1.0/tests/test_abc_partition.py +414 -0
- meta_hpo-0.1.0/tests/test_abc_phases.py +509 -0
- meta_hpo-0.1.0/tests/test_abc_protocol.py +691 -0
- meta_hpo-0.1.0/tests/test_abc_spec.py +404 -0
- meta_hpo-0.1.0/tests/test_api_contract.py +550 -0
- meta_hpo-0.1.0/tests/test_base.py +162 -0
- meta_hpo-0.1.0/tests/test_base_coverage.py +76 -0
- meta_hpo-0.1.0/tests/test_base_rng.py +82 -0
- meta_hpo-0.1.0/tests/test_base_spec.py +209 -0
- meta_hpo-0.1.0/tests/test_base_specified.py +149 -0
- meta_hpo-0.1.0/tests/test_determinism.py +448 -0
- meta_hpo-0.1.0/tests/test_end_to_end.py +621 -0
- meta_hpo-0.1.0/tests/test_facade.py +268 -0
- meta_hpo-0.1.0/tests/test_facade_boundaries.py +223 -0
- meta_hpo-0.1.0/tests/test_facade_budget.py +61 -0
- meta_hpo-0.1.0/tests/test_facade_coverage.py +615 -0
- meta_hpo-0.1.0/tests/test_facade_direction.py +117 -0
- meta_hpo-0.1.0/tests/test_facade_doubles.py +1115 -0
- meta_hpo-0.1.0/tests/test_facade_fuzz.py +577 -0
- meta_hpo-0.1.0/tests/test_facade_grammar.py +41 -0
- meta_hpo-0.1.0/tests/test_facade_integration.py +768 -0
- meta_hpo-0.1.0/tests/test_facade_partition.py +183 -0
- meta_hpo-0.1.0/tests/test_facade_spec.py +267 -0
- meta_hpo-0.1.0/tests/test_fuzz.py +1586 -0
- meta_hpo-0.1.0/tests/test_fuzz_grammar.py +1037 -0
- meta_hpo-0.1.0/tests/test_operators.py +166 -0
- meta_hpo-0.1.0/tests/test_operators_boundaries.py +130 -0
- meta_hpo-0.1.0/tests/test_operators_coverage.py +336 -0
- meta_hpo-0.1.0/tests/test_operators_fuzz.py +229 -0
- meta_hpo-0.1.0/tests/test_operators_mutation.py +849 -0
- meta_hpo-0.1.0/tests/test_operators_partition.py +78 -0
- meta_hpo-0.1.0/tests/test_regression.py +1224 -0
- meta_hpo-0.1.0/tests/test_space.py +43 -0
- meta_hpo-0.1.0/tests/test_space_boundaries.py +558 -0
- meta_hpo-0.1.0/tests/test_space_coverage.py +744 -0
- meta_hpo-0.1.0/tests/test_space_errors.py +248 -0
- meta_hpo-0.1.0/tests/test_space_fuzz.py +602 -0
- meta_hpo-0.1.0/tests/test_space_grammar.py +87 -0
- meta_hpo-0.1.0/tests/test_space_move.py +213 -0
- meta_hpo-0.1.0/tests/test_space_partition.py +534 -0
- meta_hpo-0.1.0/tests/test_space_rows.py +99 -0
- meta_hpo-0.1.0/tests/test_space_sample.py +87 -0
- meta_hpo-0.1.0/tests/test_space_spec.py +255 -0
- meta_hpo-0.1.0/tests/test_space_specified.py +170 -0
- meta_hpo-0.1.0/tests/test_static.py +1063 -0
- meta_hpo-0.1.0/tests/test_study.py +186 -0
- meta_hpo-0.1.0/tests/test_study_coverage.py +210 -0
- meta_hpo-0.1.0/tests/test_study_partition.py +141 -0
- meta_hpo-0.1.0/tests/test_study_spec.py +118 -0
- meta_hpo-0.1.0/tests/test_study_specified.py +89 -0
- meta_hpo-0.1.0/tests/test_suite_layout.py +1760 -0
- meta_hpo-0.1.0/tests/test_traceability.py +1550 -0
|
@@ -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.
|
meta_hpo-0.1.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml)
|
|
25
|
+
[](https://pypi.org/project/meta-hpo/)
|
|
26
|
+
[](LICENSE)
|
|
27
|
+
[](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)
|
meta_hpo-0.1.0/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# meta-hpo
|
|
2
|
+
|
|
3
|
+
[](https://github.com/mr-ozdemir/meta-hpo/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/meta-hpo/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](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,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
|