labga 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.
- labga-0.1.0/.github/workflows/ci.yml +47 -0
- labga-0.1.0/.github/workflows/publish.yml +140 -0
- labga-0.1.0/.gitignore +12 -0
- labga-0.1.0/CHANGELOG.md +13 -0
- labga-0.1.0/LICENSE +21 -0
- labga-0.1.0/PKG-INFO +228 -0
- labga-0.1.0/README.md +200 -0
- labga-0.1.0/docs/design.md +350 -0
- labga-0.1.0/docs/implementation-plan.md +121 -0
- labga-0.1.0/docs/publishing.md +98 -0
- labga-0.1.0/docs/verification.md +41 -0
- labga-0.1.0/examples/binary_search.py +28 -0
- labga-0.1.0/examples/gpu_predictor.py +44 -0
- labga-0.1.0/examples/islands.py +30 -0
- labga-0.1.0/examples/parameter_fitting.py +30 -0
- labga-0.1.0/pyproject.toml +75 -0
- labga-0.1.0/scripts/check_release.py +98 -0
- labga-0.1.0/src/labga/__init__.py +28 -0
- labga-0.1.0/src/labga/_evaluation_worker.py +181 -0
- labga-0.1.0/src/labga/_resources.py +62 -0
- labga-0.1.0/src/labga/_types.py +26 -0
- labga-0.1.0/src/labga/_worker_pool.py +204 -0
- labga-0.1.0/src/labga/evaluation.py +272 -0
- labga-0.1.0/src/labga/genomes.py +411 -0
- labga-0.1.0/src/labga/islands.py +64 -0
- labga-0.1.0/src/labga/objective.py +169 -0
- labga-0.1.0/src/labga/operators.py +101 -0
- labga-0.1.0/src/labga/optimize.py +261 -0
- labga-0.1.0/src/labga/predictors.py +89 -0
- labga-0.1.0/src/labga/py.typed +0 -0
- labga-0.1.0/src/labga/results.py +68 -0
- labga-0.1.0/tests/test_evaluation.py +340 -0
- labga-0.1.0/tests/test_genomes.py +272 -0
- labga-0.1.0/tests/test_gpu.py +120 -0
- labga-0.1.0/tests/test_islands.py +153 -0
- labga-0.1.0/tests/test_objective.py +132 -0
- labga-0.1.0/tests/test_operators.py +116 -0
- labga-0.1.0/tests/test_optimize.py +241 -0
- labga-0.1.0/tests/test_predictors.py +78 -0
- labga-0.1.0/tests/test_release.py +161 -0
- labga-0.1.0/uv.lock +1827 -0
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
name: Tests
|
|
2
|
+
on:
|
|
3
|
+
push:
|
|
4
|
+
pull_request:
|
|
5
|
+
jobs:
|
|
6
|
+
cpu:
|
|
7
|
+
strategy:
|
|
8
|
+
fail-fast: false
|
|
9
|
+
matrix:
|
|
10
|
+
os: [ubuntu-latest, macos-latest, windows-latest]
|
|
11
|
+
python: ['3.11', '3.12', '3.13']
|
|
12
|
+
runs-on: ${{ matrix.os }}
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
- uses: astral-sh/setup-uv@v6
|
|
16
|
+
with:
|
|
17
|
+
python-version: ${{ matrix.python }}
|
|
18
|
+
enable-cache: true
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run --no-sync pytest
|
|
21
|
+
quality:
|
|
22
|
+
runs-on: ubuntu-latest
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@v4
|
|
25
|
+
- uses: astral-sh/setup-uv@v6
|
|
26
|
+
with:
|
|
27
|
+
python-version: '3.12'
|
|
28
|
+
- run: uv sync --locked --extra torch
|
|
29
|
+
- run: uv run --no-sync ruff check .
|
|
30
|
+
- run: uv run --no-sync ruff format --check .
|
|
31
|
+
- run: uv run --no-sync mypy
|
|
32
|
+
- run: uv run --no-sync pytest --cov=labga --cov-fail-under=80
|
|
33
|
+
- run: uv build
|
|
34
|
+
- uses: actions/upload-artifact@v4
|
|
35
|
+
with:
|
|
36
|
+
name: distributions
|
|
37
|
+
path: dist/*
|
|
38
|
+
minimum-dependencies:
|
|
39
|
+
runs-on: ubuntu-latest
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/checkout@v4
|
|
42
|
+
- uses: astral-sh/setup-uv@v6
|
|
43
|
+
with:
|
|
44
|
+
python-version: '3.11'
|
|
45
|
+
- run: uv venv
|
|
46
|
+
- run: uv pip install . "numpy==1.26.4" "threadpoolctl==3.2.0" pytest
|
|
47
|
+
- run: .venv/bin/python -m pytest
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
name: Package release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
workflow_dispatch:
|
|
9
|
+
inputs:
|
|
10
|
+
target:
|
|
11
|
+
description: Validate only, rehearse on TestPyPI, or publish to PyPI
|
|
12
|
+
type: choice
|
|
13
|
+
required: true
|
|
14
|
+
default: validate
|
|
15
|
+
options:
|
|
16
|
+
- validate
|
|
17
|
+
- testpypi
|
|
18
|
+
- pypi
|
|
19
|
+
release_tag:
|
|
20
|
+
description: Existing version tag (e.g. v0.1.0); required for either publishing target
|
|
21
|
+
type: string
|
|
22
|
+
required: false
|
|
23
|
+
default: ''
|
|
24
|
+
|
|
25
|
+
permissions:
|
|
26
|
+
contents: read
|
|
27
|
+
|
|
28
|
+
jobs:
|
|
29
|
+
build:
|
|
30
|
+
name: Validate and build distributions
|
|
31
|
+
runs-on: ubuntu-latest
|
|
32
|
+
steps:
|
|
33
|
+
- uses: actions/checkout@v4
|
|
34
|
+
with:
|
|
35
|
+
ref: ${{ github.sha }}
|
|
36
|
+
fetch-depth: 0
|
|
37
|
+
persist-credentials: false
|
|
38
|
+
- name: Select a release commit from main
|
|
39
|
+
env:
|
|
40
|
+
RELEASE_TAG: ${{ inputs.release_tag || '' }}
|
|
41
|
+
run: |
|
|
42
|
+
if [[ -n "$RELEASE_TAG" ]]; then
|
|
43
|
+
git check-ref-format "refs/tags/$RELEASE_TAG"
|
|
44
|
+
release_commit="$(git rev-parse --verify "refs/tags/$RELEASE_TAG^{commit}")"
|
|
45
|
+
git merge-base --is-ancestor "$release_commit" refs/remotes/origin/main
|
|
46
|
+
git checkout --detach "$release_commit"
|
|
47
|
+
fi
|
|
48
|
+
- uses: astral-sh/setup-uv@v6
|
|
49
|
+
with:
|
|
50
|
+
python-version: '3.12'
|
|
51
|
+
enable-cache: true
|
|
52
|
+
- name: Install core and development dependencies
|
|
53
|
+
run: uv sync --locked
|
|
54
|
+
- name: Validate release identity
|
|
55
|
+
env:
|
|
56
|
+
RELEASE_TARGET: ${{ inputs.target || 'validate' }}
|
|
57
|
+
RELEASE_TAG: ${{ inputs.release_tag || '' }}
|
|
58
|
+
WORKFLOW_EVENT: ${{ github.event_name }}
|
|
59
|
+
WORKFLOW_REF: ${{ github.ref }}
|
|
60
|
+
run: >-
|
|
61
|
+
uv run --no-sync python scripts/check_release.py
|
|
62
|
+
--target "$RELEASE_TARGET"
|
|
63
|
+
--release-tag "$RELEASE_TAG"
|
|
64
|
+
--event-name "$WORKFLOW_EVENT"
|
|
65
|
+
--workflow-ref "$WORKFLOW_REF"
|
|
66
|
+
- name: Test the core package
|
|
67
|
+
run: uv run --no-sync pytest -m 'not torch and not cuda'
|
|
68
|
+
- name: Build fresh distributions and check metadata
|
|
69
|
+
run: |
|
|
70
|
+
rm -rf dist
|
|
71
|
+
uv build --no-sources
|
|
72
|
+
uv run --no-sync twine check --strict dist/*
|
|
73
|
+
- name: Install and exercise the wheel outside the checkout
|
|
74
|
+
run: |
|
|
75
|
+
uv venv "$RUNNER_TEMP/labga-wheel-smoke"
|
|
76
|
+
smoke_python="$RUNNER_TEMP/labga-wheel-smoke/bin/python"
|
|
77
|
+
uv pip install --python "$smoke_python" dist/*.whl
|
|
78
|
+
cd "$RUNNER_TEMP"
|
|
79
|
+
"$smoke_python" -I - <<'PY'
|
|
80
|
+
import importlib.metadata
|
|
81
|
+
import importlib.util
|
|
82
|
+
import os
|
|
83
|
+
import tomllib
|
|
84
|
+
from pathlib import Path
|
|
85
|
+
|
|
86
|
+
import labga
|
|
87
|
+
|
|
88
|
+
checkout = Path(os.environ["GITHUB_WORKSPACE"]).resolve()
|
|
89
|
+
with (checkout / "pyproject.toml").open("rb") as metadata_file:
|
|
90
|
+
expected_version = tomllib.load(metadata_file)["project"]["version"]
|
|
91
|
+
assert importlib.metadata.version("labga") == labga.__version__ == expected_version
|
|
92
|
+
assert not Path(labga.__file__).resolve().is_relative_to(checkout)
|
|
93
|
+
assert importlib.util.find_spec("torch") is None
|
|
94
|
+
objective = labga.Objective(lambda candidate: candidate, [1, 1])
|
|
95
|
+
result = labga.optimize(
|
|
96
|
+
genome=labga.BinaryGenome(2),
|
|
97
|
+
objective=objective,
|
|
98
|
+
initial_population=[[1, 1], [0, 0]],
|
|
99
|
+
population_size=2,
|
|
100
|
+
generations=1,
|
|
101
|
+
workers=1,
|
|
102
|
+
seed=0,
|
|
103
|
+
)
|
|
104
|
+
assert result.best_loss == 0
|
|
105
|
+
assert result.best_solution.tolist() == [1, 1]
|
|
106
|
+
print(f"Installed wheel passed: labga {labga.__version__}")
|
|
107
|
+
PY
|
|
108
|
+
- uses: actions/upload-artifact@v4
|
|
109
|
+
with:
|
|
110
|
+
name: release-distributions
|
|
111
|
+
path: dist/*
|
|
112
|
+
if-no-files-found: error
|
|
113
|
+
retention-days: 7
|
|
114
|
+
|
|
115
|
+
publish:
|
|
116
|
+
name: Publish verified distributions
|
|
117
|
+
needs: build
|
|
118
|
+
if: >-
|
|
119
|
+
github.event_name == 'workflow_dispatch' &&
|
|
120
|
+
github.ref == 'refs/heads/main' &&
|
|
121
|
+
(inputs.target == 'testpypi' || inputs.target == 'pypi')
|
|
122
|
+
runs-on: ubuntu-latest
|
|
123
|
+
environment:
|
|
124
|
+
name: ${{ inputs.target }}
|
|
125
|
+
permissions:
|
|
126
|
+
contents: read
|
|
127
|
+
id-token: write
|
|
128
|
+
steps:
|
|
129
|
+
- uses: actions/download-artifact@v4
|
|
130
|
+
with:
|
|
131
|
+
name: release-distributions
|
|
132
|
+
path: dist
|
|
133
|
+
- name: Publish to TestPyPI with Trusted Publishing
|
|
134
|
+
if: inputs.target == 'testpypi'
|
|
135
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
136
|
+
with:
|
|
137
|
+
repository-url: https://test.pypi.org/legacy/
|
|
138
|
+
- name: Publish to PyPI with Trusted Publishing
|
|
139
|
+
if: inputs.target == 'pypi'
|
|
140
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
labga-0.1.0/.gitignore
ADDED
labga-0.1.0/CHANGELOG.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
- A single `optimize` API for a standard genetic algorithm and island populations with ring migration.
|
|
6
|
+
- Binary and bounded numeric genomes, configurable initialization, per-coordinate bounds, and initial populations.
|
|
7
|
+
- `Objective` groups a fixed predictor, target, preprocessing, and MSE, MAE, or a custom loss.
|
|
8
|
+
- CPU multiprocessing with one shared worker budget and spawn-compatible predictor factories.
|
|
9
|
+
- Optional PyTorch inference with one GPU owner, automatic batching, and typed CUDA out-of-memory fallback.
|
|
10
|
+
- Best solutions, predictions, generation history, migration markers, and execution metadata.
|
|
11
|
+
- Typed public API, validation, multiprocessing deadlines, and synthetic examples.
|
|
12
|
+
|
|
13
|
+
This release supports a single computer. Actual CUDA hardware and a real DKO model have not been validated in the initial development environment. See the README for supported interfaces and limitations.
|
labga-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Gal Levy
|
|
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.
|
labga-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,228 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: labga
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Accessible genetic algorithms with island populations and shared batched inference.
|
|
5
|
+
Project-URL: Repository, https://github.com/galevy88/labga
|
|
6
|
+
Project-URL: Documentation, https://github.com/galevy88/labga/blob/main/README.md
|
|
7
|
+
Project-URL: Changelog, https://github.com/galevy88/labga/blob/main/CHANGELOG.md
|
|
8
|
+
Project-URL: Issues, https://github.com/galevy88/labga/issues
|
|
9
|
+
Author: Gal Levy
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: genetic-algorithm,island-model,optimization,scientific-computing
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.11
|
|
23
|
+
Requires-Dist: numpy>=1.26.4
|
|
24
|
+
Requires-Dist: threadpoolctl>=3.2
|
|
25
|
+
Provides-Extra: torch
|
|
26
|
+
Requires-Dist: torch>=2.5; extra == 'torch'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# labga
|
|
30
|
+
|
|
31
|
+
**Define a solution, predict its outcome, and evolve it toward your target.**
|
|
32
|
+
|
|
33
|
+
labga provides ordinary genetic algorithms and island populations through one Python API. Bring a fixed predictor or simulator, a target vector, and a loss. Use binary interventions or continuous parameters. Evaluate on CPU workers or through one shared, batched GPU predictor.
|
|
34
|
+
|
|
35
|
+
This is an initial research-library release. The included examples are synthetic. A real DKO model and its validation are not bundled.
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install labga
|
|
41
|
+
# Optional PyTorch support:
|
|
42
|
+
pip install "labga[torch]"
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
To install the development version directly from GitHub:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
pip install "git+https://github.com/galevy88/labga.git"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Optional PyTorch support:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install "labga[torch] @ git+https://github.com/galevy88/labga.git"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Python 3.11 or later is required. Core use requires NumPy and threadpoolctl, not PyTorch. A suitable PyTorch/CUDA installation and GPU are needed for CUDA inference.
|
|
58
|
+
|
|
59
|
+
## A complete first example
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
import numpy as np
|
|
63
|
+
from labga import BinaryGenome, Objective, optimize
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def predict(genome):
|
|
67
|
+
return genome.astype(float)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
if __name__ == "__main__":
|
|
71
|
+
objective = Objective(
|
|
72
|
+
predictor=predict,
|
|
73
|
+
target=np.array([1, 0, 1, 1, 0, 1]),
|
|
74
|
+
loss="mse",
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
result = optimize(
|
|
78
|
+
genome=BinaryGenome(size=6, probability_of_one=0.3),
|
|
79
|
+
objective=objective,
|
|
80
|
+
population_size=80,
|
|
81
|
+
generations=30,
|
|
82
|
+
workers=1,
|
|
83
|
+
seed=42,
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
print(result.best_solution)
|
|
87
|
+
print(result.best_prediction)
|
|
88
|
+
print(result.best_loss)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`Objective` groups everything that defines a good solution. The GA changes the genome; the predictor remains fixed. MSE/MAE compare each predicted output to the same target. Every candidate gets its own score, even when inference is batched. For a scalar prediction, return a length-one vector.
|
|
92
|
+
|
|
93
|
+
The identity predictor above makes the example fully transparent. Replace it with an experimental simulator or an adapter around your own model.
|
|
94
|
+
|
|
95
|
+
## Search spaces
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from labga import BinaryGenome, Normal, NumericGenome
|
|
99
|
+
|
|
100
|
+
binary = BinaryGenome(size=48, probability_of_one=0.1)
|
|
101
|
+
numeric = NumericGenome(size=1000, bounds=(0.0, 1.0))
|
|
102
|
+
|
|
103
|
+
custom = NumericGenome(
|
|
104
|
+
size=1000,
|
|
105
|
+
bounds=(0.0, 1.0),
|
|
106
|
+
custom_bounds={0: (-2.0, 2.0), 17: (0.0, 100.0)},
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
concentrated = NumericGenome(
|
|
110
|
+
size=1000,
|
|
111
|
+
bounds=(0.0, 1.0),
|
|
112
|
+
initialization=Normal(mean=0.5, std=0.1),
|
|
113
|
+
)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
- Binary probability controls independent initialization, not an exact count of ones. Your adapter defines whether 1 means knockout, retention, or something else.
|
|
117
|
+
- Numeric initialization is uniform by default. Normal initialization is clipped to bounds and may accumulate values at the boundaries. Scalar or per-coordinate mean/std are accepted.
|
|
118
|
+
- Custom bounds can be a zero-based override dictionary or a complete `(size, 2)` array loaded from your metadata.
|
|
119
|
+
- Bounds remain enforced during evolution. `initial_population=` can supply a validated complete population instead of sampling one.
|
|
120
|
+
- Binary predictors receive int8 0/1 vectors; numeric predictors receive float64 vectors. Unsupported lossy numeric conversions are rejected.
|
|
121
|
+
- Genome length and prediction length may differ. Continuous numeric genomes are not automatically constrained to sum to one.
|
|
122
|
+
|
|
123
|
+
## Four populations, one evaluation budget
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
from labga import Migration
|
|
127
|
+
|
|
128
|
+
result = optimize(
|
|
129
|
+
genome=binary,
|
|
130
|
+
objective=Objective(predict, target=np.ones(48)),
|
|
131
|
+
population_size=1000,
|
|
132
|
+
generations=100,
|
|
133
|
+
distributed=True,
|
|
134
|
+
n_islands=4,
|
|
135
|
+
migration=Migration(interval=10, count=5),
|
|
136
|
+
workers="auto",
|
|
137
|
+
seed=42,
|
|
138
|
+
)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
This means **four populations of 250**, not four populations of 1,000. Islands have independent evolutionary random streams. Every ten generations, each copies five of its best solutions to its next neighbor in a ring, replacing poor non-protected solutions. Donors are selected from simultaneous snapshots; migration never cascades a new arrival through the entire ring in one event.
|
|
142
|
+
|
|
143
|
+
The island model runs on one computer in this release. Independent islands do not imply separate search basins or separate GPUs. All islands share a single evaluation budget. Standard GA also supports CPU multiprocessing.
|
|
144
|
+
|
|
145
|
+
Defaults are tournament selection, uniform crossover, binary bit-flip or bounded numeric mutation, and one elite per population. Use `Operators(...)` to adjust them.
|
|
146
|
+
|
|
147
|
+
## Your predictor
|
|
148
|
+
|
|
149
|
+
Supported interfaces:
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
callable(x) or predict(x): (D,) → (M,)
|
|
153
|
+
optional predict_batch(X): (B, D) → (B, M)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Each batch row must be independent and in the same order as the input. An optional `Objective(preprocess=...)` transforms each input vector before prediction. A custom `loss(prediction, target)` receives two NumPy vectors and returns one finite scalar; lower is better. The target is copied and must be finite and one-dimensional.
|
|
157
|
+
|
|
158
|
+
Use fixed, comparable evaluation conditions across candidates. Stochastic predictors should implement a reproducible protocol in the adapter. A run seed controls labga's evolution; it cannot make arbitrary model code or GPU kernels deterministic.
|
|
159
|
+
|
|
160
|
+
## Automatic batching and GPU inference
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
from labga import Objective, Predictor
|
|
164
|
+
from my_lab.dko_adapter import build_dko # Your importable adapter factory.
|
|
165
|
+
|
|
166
|
+
objective = Objective(
|
|
167
|
+
predictor=Predictor(factory=build_dko, device="cuda:0"),
|
|
168
|
+
target=desired_expression,
|
|
169
|
+
loss="mse",
|
|
170
|
+
)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`build_dko(*, device)` loads and returns your adapter. Serializable fixed configuration can be bound with `functools.partial`. A returned PyTorch `nn.Module` is automatically adapted to evaluation/inference mode. An existing wrapper can expose `predict` and optionally `predict_batch` instead.
|
|
174
|
+
|
|
175
|
+
One spawned process owns the CUDA model. CPU work prepares candidates; the GPU owner groups compatible requests into batches and returns predictions/scores in candidate order. Models are not copied into every CPU worker.
|
|
176
|
+
|
|
177
|
+
`batch_size="auto"` starts conservatively at 64 (or fewer available candidates). A typed CUDA out-of-memory error during automatic inference reduces the cap by half, down to one. Other errors are surfaced. An explicit `batch_size=128` is respected and is not silently reduced. Without batch support, the model is called per candidate. Actual batch size and fallback are reported in result metadata. This is a memory-conservative policy, not a benchmark-based throughput tuner.
|
|
178
|
+
|
|
179
|
+
Built-in MSE/MAE can be reduced on the GPU when predictions are tensors; custom losses use NumPy on CPU. Predictions needed for results are transferred back to CPU. No model training occurs.
|
|
180
|
+
|
|
181
|
+
CUDA code must be tested on a CUDA-equipped machine. The initial development host is macOS/Apple Silicon; CPU/PyTorch tests do not substitute for a successful CUDA hardware test.
|
|
182
|
+
|
|
183
|
+
## Multiprocessing and notebooks
|
|
184
|
+
|
|
185
|
+
`workers="auto"` detects available CPU capacity and caps workers by runnable work. It does not create one pool per island. With GPU inference and no expensive preprocessing, additional CPU workers are unnecessary. More CPU workers do not multiply the throughput of one GPU.
|
|
186
|
+
|
|
187
|
+
Use a main guard in scripts. Put predictor factories and preprocessing functions in an importable module for spawn-based multiprocessing. In notebooks, import that module; use `workers=1` for cell-local CPU callables. Heavy CPU models can also use `Predictor(factory=..., device="cpu")`, loading once per evaluation owner.
|
|
188
|
+
|
|
189
|
+
`evaluation_timeout=300.0` sets a deadline for worker readiness and each complete multiprocessing request exchange, including data transfer; adjust it for legitimately slow simulations. It cannot interrupt caller-side startup serialization, the OS process-start call, or a serial in-process callback. Use lightweight importable factories for heavy models. Invalid inputs, model exceptions, worker failure, and unavailable CUDA produce explicit errors. Evaluation failures preserve available completed-result diagnostics rather than silently assigning random penalties.
|
|
190
|
+
|
|
191
|
+
## Inspect the result
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
result.best_solution
|
|
195
|
+
result.best_prediction
|
|
196
|
+
result.best_loss
|
|
197
|
+
result.population.solutions
|
|
198
|
+
result.population.losses
|
|
199
|
+
result.population.island_ids
|
|
200
|
+
|
|
201
|
+
for generation in result.history:
|
|
202
|
+
print(generation.generation, generation.best_loss, generation.mean_loss)
|
|
203
|
+
|
|
204
|
+
print(result.metadata)
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
History includes initialization as generation zero, best-so-far scores, per-island summaries, and migration markers. Results own their arrays; labga does not write output files automatically. Elitism protects the best evaluated score, but no global-optimum guarantee is implied.
|
|
208
|
+
|
|
209
|
+
## Examples and development
|
|
210
|
+
|
|
211
|
+
- `examples/binary_search.py`: complete binary optimization.
|
|
212
|
+
- `examples/parameter_fitting.py`: fit two parameters to a synthetic time series.
|
|
213
|
+
- `examples/islands.py`: ring migration with CPU multiprocessing.
|
|
214
|
+
- `examples/gpu_predictor.py`: a synthetic PyTorch model; use `--device cpu` or `--device cuda:0`.
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
uv sync --extra torch
|
|
218
|
+
uv run --no-sync pytest
|
|
219
|
+
uv run --no-sync ruff check .
|
|
220
|
+
uv run --no-sync ruff format --check .
|
|
221
|
+
uv run --no-sync mypy
|
|
222
|
+
uv build --no-sources
|
|
223
|
+
uv run --no-sync twine check --strict dist/*
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
See the [design](https://github.com/galevy88/labga/blob/main/docs/design.md), [implementation plan](https://github.com/galevy88/labga/blob/main/docs/implementation-plan.md), and [publishing guide](https://github.com/galevy88/labga/blob/main/docs/publishing.md). The original [Git_HH project](https://github.com/galevy88/Git_HH) inspired this library's workflow; this is a separate implementation with a general prediction interface.
|
|
227
|
+
|
|
228
|
+
MIT license. Model weights, experimental data, and third-party predictors retain their own licenses and validation requirements.
|
labga-0.1.0/README.md
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# labga
|
|
2
|
+
|
|
3
|
+
**Define a solution, predict its outcome, and evolve it toward your target.**
|
|
4
|
+
|
|
5
|
+
labga provides ordinary genetic algorithms and island populations through one Python API. Bring a fixed predictor or simulator, a target vector, and a loss. Use binary interventions or continuous parameters. Evaluate on CPU workers or through one shared, batched GPU predictor.
|
|
6
|
+
|
|
7
|
+
This is an initial research-library release. The included examples are synthetic. A real DKO model and its validation are not bundled.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pip install labga
|
|
13
|
+
# Optional PyTorch support:
|
|
14
|
+
pip install "labga[torch]"
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
To install the development version directly from GitHub:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
pip install "git+https://github.com/galevy88/labga.git"
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Optional PyTorch support:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install "labga[torch] @ git+https://github.com/galevy88/labga.git"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Python 3.11 or later is required. Core use requires NumPy and threadpoolctl, not PyTorch. A suitable PyTorch/CUDA installation and GPU are needed for CUDA inference.
|
|
30
|
+
|
|
31
|
+
## A complete first example
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
import numpy as np
|
|
35
|
+
from labga import BinaryGenome, Objective, optimize
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def predict(genome):
|
|
39
|
+
return genome.astype(float)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
if __name__ == "__main__":
|
|
43
|
+
objective = Objective(
|
|
44
|
+
predictor=predict,
|
|
45
|
+
target=np.array([1, 0, 1, 1, 0, 1]),
|
|
46
|
+
loss="mse",
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
result = optimize(
|
|
50
|
+
genome=BinaryGenome(size=6, probability_of_one=0.3),
|
|
51
|
+
objective=objective,
|
|
52
|
+
population_size=80,
|
|
53
|
+
generations=30,
|
|
54
|
+
workers=1,
|
|
55
|
+
seed=42,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
print(result.best_solution)
|
|
59
|
+
print(result.best_prediction)
|
|
60
|
+
print(result.best_loss)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`Objective` groups everything that defines a good solution. The GA changes the genome; the predictor remains fixed. MSE/MAE compare each predicted output to the same target. Every candidate gets its own score, even when inference is batched. For a scalar prediction, return a length-one vector.
|
|
64
|
+
|
|
65
|
+
The identity predictor above makes the example fully transparent. Replace it with an experimental simulator or an adapter around your own model.
|
|
66
|
+
|
|
67
|
+
## Search spaces
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from labga import BinaryGenome, Normal, NumericGenome
|
|
71
|
+
|
|
72
|
+
binary = BinaryGenome(size=48, probability_of_one=0.1)
|
|
73
|
+
numeric = NumericGenome(size=1000, bounds=(0.0, 1.0))
|
|
74
|
+
|
|
75
|
+
custom = NumericGenome(
|
|
76
|
+
size=1000,
|
|
77
|
+
bounds=(0.0, 1.0),
|
|
78
|
+
custom_bounds={0: (-2.0, 2.0), 17: (0.0, 100.0)},
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
concentrated = NumericGenome(
|
|
82
|
+
size=1000,
|
|
83
|
+
bounds=(0.0, 1.0),
|
|
84
|
+
initialization=Normal(mean=0.5, std=0.1),
|
|
85
|
+
)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- Binary probability controls independent initialization, not an exact count of ones. Your adapter defines whether 1 means knockout, retention, or something else.
|
|
89
|
+
- Numeric initialization is uniform by default. Normal initialization is clipped to bounds and may accumulate values at the boundaries. Scalar or per-coordinate mean/std are accepted.
|
|
90
|
+
- Custom bounds can be a zero-based override dictionary or a complete `(size, 2)` array loaded from your metadata.
|
|
91
|
+
- Bounds remain enforced during evolution. `initial_population=` can supply a validated complete population instead of sampling one.
|
|
92
|
+
- Binary predictors receive int8 0/1 vectors; numeric predictors receive float64 vectors. Unsupported lossy numeric conversions are rejected.
|
|
93
|
+
- Genome length and prediction length may differ. Continuous numeric genomes are not automatically constrained to sum to one.
|
|
94
|
+
|
|
95
|
+
## Four populations, one evaluation budget
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from labga import Migration
|
|
99
|
+
|
|
100
|
+
result = optimize(
|
|
101
|
+
genome=binary,
|
|
102
|
+
objective=Objective(predict, target=np.ones(48)),
|
|
103
|
+
population_size=1000,
|
|
104
|
+
generations=100,
|
|
105
|
+
distributed=True,
|
|
106
|
+
n_islands=4,
|
|
107
|
+
migration=Migration(interval=10, count=5),
|
|
108
|
+
workers="auto",
|
|
109
|
+
seed=42,
|
|
110
|
+
)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
This means **four populations of 250**, not four populations of 1,000. Islands have independent evolutionary random streams. Every ten generations, each copies five of its best solutions to its next neighbor in a ring, replacing poor non-protected solutions. Donors are selected from simultaneous snapshots; migration never cascades a new arrival through the entire ring in one event.
|
|
114
|
+
|
|
115
|
+
The island model runs on one computer in this release. Independent islands do not imply separate search basins or separate GPUs. All islands share a single evaluation budget. Standard GA also supports CPU multiprocessing.
|
|
116
|
+
|
|
117
|
+
Defaults are tournament selection, uniform crossover, binary bit-flip or bounded numeric mutation, and one elite per population. Use `Operators(...)` to adjust them.
|
|
118
|
+
|
|
119
|
+
## Your predictor
|
|
120
|
+
|
|
121
|
+
Supported interfaces:
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
callable(x) or predict(x): (D,) → (M,)
|
|
125
|
+
optional predict_batch(X): (B, D) → (B, M)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Each batch row must be independent and in the same order as the input. An optional `Objective(preprocess=...)` transforms each input vector before prediction. A custom `loss(prediction, target)` receives two NumPy vectors and returns one finite scalar; lower is better. The target is copied and must be finite and one-dimensional.
|
|
129
|
+
|
|
130
|
+
Use fixed, comparable evaluation conditions across candidates. Stochastic predictors should implement a reproducible protocol in the adapter. A run seed controls labga's evolution; it cannot make arbitrary model code or GPU kernels deterministic.
|
|
131
|
+
|
|
132
|
+
## Automatic batching and GPU inference
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from labga import Objective, Predictor
|
|
136
|
+
from my_lab.dko_adapter import build_dko # Your importable adapter factory.
|
|
137
|
+
|
|
138
|
+
objective = Objective(
|
|
139
|
+
predictor=Predictor(factory=build_dko, device="cuda:0"),
|
|
140
|
+
target=desired_expression,
|
|
141
|
+
loss="mse",
|
|
142
|
+
)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`build_dko(*, device)` loads and returns your adapter. Serializable fixed configuration can be bound with `functools.partial`. A returned PyTorch `nn.Module` is automatically adapted to evaluation/inference mode. An existing wrapper can expose `predict` and optionally `predict_batch` instead.
|
|
146
|
+
|
|
147
|
+
One spawned process owns the CUDA model. CPU work prepares candidates; the GPU owner groups compatible requests into batches and returns predictions/scores in candidate order. Models are not copied into every CPU worker.
|
|
148
|
+
|
|
149
|
+
`batch_size="auto"` starts conservatively at 64 (or fewer available candidates). A typed CUDA out-of-memory error during automatic inference reduces the cap by half, down to one. Other errors are surfaced. An explicit `batch_size=128` is respected and is not silently reduced. Without batch support, the model is called per candidate. Actual batch size and fallback are reported in result metadata. This is a memory-conservative policy, not a benchmark-based throughput tuner.
|
|
150
|
+
|
|
151
|
+
Built-in MSE/MAE can be reduced on the GPU when predictions are tensors; custom losses use NumPy on CPU. Predictions needed for results are transferred back to CPU. No model training occurs.
|
|
152
|
+
|
|
153
|
+
CUDA code must be tested on a CUDA-equipped machine. The initial development host is macOS/Apple Silicon; CPU/PyTorch tests do not substitute for a successful CUDA hardware test.
|
|
154
|
+
|
|
155
|
+
## Multiprocessing and notebooks
|
|
156
|
+
|
|
157
|
+
`workers="auto"` detects available CPU capacity and caps workers by runnable work. It does not create one pool per island. With GPU inference and no expensive preprocessing, additional CPU workers are unnecessary. More CPU workers do not multiply the throughput of one GPU.
|
|
158
|
+
|
|
159
|
+
Use a main guard in scripts. Put predictor factories and preprocessing functions in an importable module for spawn-based multiprocessing. In notebooks, import that module; use `workers=1` for cell-local CPU callables. Heavy CPU models can also use `Predictor(factory=..., device="cpu")`, loading once per evaluation owner.
|
|
160
|
+
|
|
161
|
+
`evaluation_timeout=300.0` sets a deadline for worker readiness and each complete multiprocessing request exchange, including data transfer; adjust it for legitimately slow simulations. It cannot interrupt caller-side startup serialization, the OS process-start call, or a serial in-process callback. Use lightweight importable factories for heavy models. Invalid inputs, model exceptions, worker failure, and unavailable CUDA produce explicit errors. Evaluation failures preserve available completed-result diagnostics rather than silently assigning random penalties.
|
|
162
|
+
|
|
163
|
+
## Inspect the result
|
|
164
|
+
|
|
165
|
+
```python
|
|
166
|
+
result.best_solution
|
|
167
|
+
result.best_prediction
|
|
168
|
+
result.best_loss
|
|
169
|
+
result.population.solutions
|
|
170
|
+
result.population.losses
|
|
171
|
+
result.population.island_ids
|
|
172
|
+
|
|
173
|
+
for generation in result.history:
|
|
174
|
+
print(generation.generation, generation.best_loss, generation.mean_loss)
|
|
175
|
+
|
|
176
|
+
print(result.metadata)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
History includes initialization as generation zero, best-so-far scores, per-island summaries, and migration markers. Results own their arrays; labga does not write output files automatically. Elitism protects the best evaluated score, but no global-optimum guarantee is implied.
|
|
180
|
+
|
|
181
|
+
## Examples and development
|
|
182
|
+
|
|
183
|
+
- `examples/binary_search.py`: complete binary optimization.
|
|
184
|
+
- `examples/parameter_fitting.py`: fit two parameters to a synthetic time series.
|
|
185
|
+
- `examples/islands.py`: ring migration with CPU multiprocessing.
|
|
186
|
+
- `examples/gpu_predictor.py`: a synthetic PyTorch model; use `--device cpu` or `--device cuda:0`.
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
uv sync --extra torch
|
|
190
|
+
uv run --no-sync pytest
|
|
191
|
+
uv run --no-sync ruff check .
|
|
192
|
+
uv run --no-sync ruff format --check .
|
|
193
|
+
uv run --no-sync mypy
|
|
194
|
+
uv build --no-sources
|
|
195
|
+
uv run --no-sync twine check --strict dist/*
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
See the [design](https://github.com/galevy88/labga/blob/main/docs/design.md), [implementation plan](https://github.com/galevy88/labga/blob/main/docs/implementation-plan.md), and [publishing guide](https://github.com/galevy88/labga/blob/main/docs/publishing.md). The original [Git_HH project](https://github.com/galevy88/Git_HH) inspired this library's workflow; this is a separate implementation with a general prediction interface.
|
|
199
|
+
|
|
200
|
+
MIT license. Model weights, experimental data, and third-party predictors retain their own licenses and validation requirements.
|