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.
Files changed (41) hide show
  1. labga-0.1.0/.github/workflows/ci.yml +47 -0
  2. labga-0.1.0/.github/workflows/publish.yml +140 -0
  3. labga-0.1.0/.gitignore +12 -0
  4. labga-0.1.0/CHANGELOG.md +13 -0
  5. labga-0.1.0/LICENSE +21 -0
  6. labga-0.1.0/PKG-INFO +228 -0
  7. labga-0.1.0/README.md +200 -0
  8. labga-0.1.0/docs/design.md +350 -0
  9. labga-0.1.0/docs/implementation-plan.md +121 -0
  10. labga-0.1.0/docs/publishing.md +98 -0
  11. labga-0.1.0/docs/verification.md +41 -0
  12. labga-0.1.0/examples/binary_search.py +28 -0
  13. labga-0.1.0/examples/gpu_predictor.py +44 -0
  14. labga-0.1.0/examples/islands.py +30 -0
  15. labga-0.1.0/examples/parameter_fitting.py +30 -0
  16. labga-0.1.0/pyproject.toml +75 -0
  17. labga-0.1.0/scripts/check_release.py +98 -0
  18. labga-0.1.0/src/labga/__init__.py +28 -0
  19. labga-0.1.0/src/labga/_evaluation_worker.py +181 -0
  20. labga-0.1.0/src/labga/_resources.py +62 -0
  21. labga-0.1.0/src/labga/_types.py +26 -0
  22. labga-0.1.0/src/labga/_worker_pool.py +204 -0
  23. labga-0.1.0/src/labga/evaluation.py +272 -0
  24. labga-0.1.0/src/labga/genomes.py +411 -0
  25. labga-0.1.0/src/labga/islands.py +64 -0
  26. labga-0.1.0/src/labga/objective.py +169 -0
  27. labga-0.1.0/src/labga/operators.py +101 -0
  28. labga-0.1.0/src/labga/optimize.py +261 -0
  29. labga-0.1.0/src/labga/predictors.py +89 -0
  30. labga-0.1.0/src/labga/py.typed +0 -0
  31. labga-0.1.0/src/labga/results.py +68 -0
  32. labga-0.1.0/tests/test_evaluation.py +340 -0
  33. labga-0.1.0/tests/test_genomes.py +272 -0
  34. labga-0.1.0/tests/test_gpu.py +120 -0
  35. labga-0.1.0/tests/test_islands.py +153 -0
  36. labga-0.1.0/tests/test_objective.py +132 -0
  37. labga-0.1.0/tests/test_operators.py +116 -0
  38. labga-0.1.0/tests/test_optimize.py +241 -0
  39. labga-0.1.0/tests/test_predictors.py +78 -0
  40. labga-0.1.0/tests/test_release.py +161 -0
  41. 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
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ .coverage*
8
+ htmlcov/
9
+ dist/
10
+ *.egg-info/
11
+ .DS_Store
12
+ .superpowers/
@@ -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.