eckity-bert-ga 0.1.0__tar.gz

eckity_bert_ga-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, EC-KitY
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

eckity_bert_ga-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: eckity-bert-ga
+Version: 0.1.0
+Summary: BERT mutation operator for EC-KitY genetic algorithms
+Author: EC-KitY
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/EC-KitY/BERT-Mutation-for-GA
+Project-URL: Repository, https://github.com/EC-KitY/BERT-Mutation-for-GA
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: eckity~=0.4.1
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: torch>=2.7.1
+Requires-Dist: transformers>=4.50.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: gymnasium>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# BERT Mutation for Genetic Algorithms
+
+## Overview
+
+This repository implements the paper `BERT Mutation: Deep Transformer Model for Masked Uniform Mutation in Genetic Algorithms`.
+
+The paper proposes a domain-independent mutation operator for genetic algorithms that uses a BERT-style masked model to predict beneficial gene replacements from context. To make this work for fixed-length GA representations, it adds an elite-guided data augmentation mechanism that creates additional learning signal from strong historical solutions.
+
+In the paper, the method is evaluated on four domains: Frozen Lake, Artificial Ant, Graph Coloring, and Unweighted Set Cover. The reported results show faster convergence and better final fitness than standard mutation baselines and an adaptive operator-selection baseline, while maintaining meaningful population diversity.
+
+## Installation
+
+```bash
+pip install eckity-bert-ga
+```
+
+## Using the operator
+
+Import the public API from `eckity_bert_ga`:
+
+```python
+from eckity_bert_ga import (
+    BertMutation,
+    EckityCustomMutation,
+    GAIntegerStringVectorCreator,
+)
+```
+
+Create the BERT mutation model and wrap it as an EC-KitY operator:
+
+```python
+population_size = 100
+
+bert_mutation = BertMutation(
+    max_int_val=MAX_GENE_VALUE,
+    get_fitness_func=evaluate_vector,
+    context_size=INDIVIDUAL_LENGTH + 1,
+    mask_probability=0.1,
+)
+
+mutation_operator = EckityCustomMutation(
+    mutation_operator=bert_mutation,
+    population_size=population_size,
+    probability=0.4,
+)
+```
+
+Add `mutation_operator` to an EC-KitY subpopulation's `operators_sequence`. The BERT model is initialized locally from configuration and does not download pretrained model weights.
+
+### Compatibility
+
+- Python 3.9 or newer
+- EC-KitY 0.4.x
+- NumPy 2.0.2 or newer
+- SciPy 1.13.0 or newer
+- PyTorch 2.7.1 or newer
+- Transformers 4.50.0 or newer
+
+## Results from the paper
+
+### Fitness by generation
+
+The following figure presents representative best-individual fitness curves for BERT Mutation and the mutation baselines across the four evaluated domains.
+
+![Representative fitness curves across the evaluated domains](images/bert_ga.png "Convergence plots")
+
+*Best-individual fitness by generation, averaged over 10 runs. Black dots mark the runtime cutoffs.*
+
+### Statistical comparisons
+
+The following table presents the paired exact permutation-test results comparing BERT Mutation against each baseline in every evaluated domain.
+
+![Paired exact permutation-test results](images/p_values.png "Permutation-test results")
+
+*Holm-corrected p-values for comparisons between BERT Mutation and the baseline mutation operators.*
+
+## Benchmark instances
+
+*Benchmark instance sizes used in the experiments. The individual length $L$ denotes the genome length optimized by the GA.*
+
+| Domain | Instance | Problem size | Individual length $L$ |
+|---|---|---|---:|
+| **Artificial Ant** | | | |
+| Artificial Ant | `aux_map1` | $20 \times 20$, 91 food cells | 283 |
+| Artificial Ant | `aux_map2` | $20 \times 20$, 69 food cells | 286 |
+| Artificial Ant | `john_muir` | $32 \times 32$, 89 food cells | 200 |
+| Artificial Ant | `los_altos` | $100 \times 100$, 157 food cells | 800 |
+| Artificial Ant | `santafe` | $32 \times 32$, 89 food cells | 400 |
+| **Set Covering** | | | |
+| Set Covering | `scp41` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp51` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp52` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp53` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp54` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp56` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp57` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp64` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp65` | 200 rows, 1000 columns | 1000 |
+| **Frozen Lake** | | | |
+| Frozen Lake | `default` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand10x10` | $10 \times 10$ grid, 100 states | 100 |
+| Frozen Lake | `rand7x7` | $7 \times 7$ grid, 49 states | 49 |
+| Frozen Lake | `rand8x8` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand9x9` | $9 \times 9$ grid, 81 states | 81 |
+| **Graph Coloring** | | | |
+| Graph Coloring | `games120` | 120 vertices, 1276 edges | 120 |
+| Graph Coloring | `myciel7` | 191 vertices, 2360 edges | 191 |
+| Graph Coloring | `le450_5a` | 450 vertices, 5714 edges | 450 |
+| Graph Coloring | `mulsol.i.2` | 188 vertices, 3885 edges | 188 |
+| Graph Coloring | `zeroin.i.1` | 211 vertices, 4100 edges | 211 |
+| Graph Coloring | `zeroin.i.2` | 211 vertices, 3541 edges | 211 |
+
+## Getting started
+
+### Requirements
+
+- Python 3.9 or newer
+- A working PyTorch installation
+
+The code depends on:
+
+- `numpy`
+- `gymnasium`
+- `torch`
+- `transformers`
+- `eckity`
+
+### Installing for repository development
+
+From the repository root:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Running the experiments
+
+Artificial Ant:
+
+```bash
+python example_runner.py
+python -m dnm_paper.experiments.artificial_ant
+```
+
+Frozen Lake:
+
+```bash
+python example_runner_frozen_lake.py
+python -m dnm_paper.experiments.frozen_lake
+```
+
+Useful options:
+
+```bash
+python -m dnm_paper.experiments.artificial_ant --generations 100 --runs 3 --population-size 6
+python -m dnm_paper.experiments.artificial_ant --maps-dir artifical_ant_maps --output-dir experiments/artificial_ant/runs
+python -m dnm_paper.experiments.frozen_lake --generations 10 --runs 1 --population-size 100 --total-episodes 2000
+```
+
+By default, results are written under `experiments/artificial_ant/runs/<map_name>/bert_mutation/<run_id>/results.json`.
+Frozen Lake results are written under `experiments/frozen_lake/runs/<instance_name>/bert_mutation/<run_id>/results.json`.
+
+The experiment modules, benchmark maps, datasets, and result figures are repository resources and are not included in the `eckity-bert-ga` wheel.
+
+Release preparation and manual PyPI upload commands are documented in [`RELEASING.md`](RELEASING.md).
+
+## Project structure
+
+```text
+dnm_paper/
+  config.py                    Experiment configuration and default paths
+  individuals.py               Custom ECKITY individual creator
+  logging_utils.py             JSON statistics logger
+  experiments/
+    common.py                  Shared experiment helpers and mutation builder
+    artificial_ant.py          CLI entry point and experiment orchestration
+    frozen_lake.py             CLI entry point and experiment orchestration
+  mutation/
+    bert.py                    BERT-based mutation operator
+    eckity_adapter.py          Adapter that plugs the mutation operator into ECKITY
+  problems/
+    artificial_ant.py          Artificial ant map loader and evaluator
+    frozen_lake.py             Frozen Lake evaluator
+    frozen_lake_instances.py   Named Frozen Lake benchmark instances
+artifical_ant_maps/            Benchmark map files
+pyproject.toml                 Package metadata and dependencies
+```

eckity_bert_ga-0.1.0/README.md

@@ -0,0 +1,188 @@
+# BERT Mutation for Genetic Algorithms
+
+## Overview
+
+This repository implements the paper `BERT Mutation: Deep Transformer Model for Masked Uniform Mutation in Genetic Algorithms`.
+
+The paper proposes a domain-independent mutation operator for genetic algorithms that uses a BERT-style masked model to predict beneficial gene replacements from context. To make this work for fixed-length GA representations, it adds an elite-guided data augmentation mechanism that creates additional learning signal from strong historical solutions.
+
+In the paper, the method is evaluated on four domains: Frozen Lake, Artificial Ant, Graph Coloring, and Unweighted Set Cover. The reported results show faster convergence and better final fitness than standard mutation baselines and an adaptive operator-selection baseline, while maintaining meaningful population diversity.
+
+## Installation
+
+```bash
+pip install eckity-bert-ga
+```
+
+## Using the operator
+
+Import the public API from `eckity_bert_ga`:
+
+```python
+from eckity_bert_ga import (
+    BertMutation,
+    EckityCustomMutation,
+    GAIntegerStringVectorCreator,
+)
+```
+
+Create the BERT mutation model and wrap it as an EC-KitY operator:
+
+```python
+population_size = 100
+
+bert_mutation = BertMutation(
+    max_int_val=MAX_GENE_VALUE,
+    get_fitness_func=evaluate_vector,
+    context_size=INDIVIDUAL_LENGTH + 1,
+    mask_probability=0.1,
+)
+
+mutation_operator = EckityCustomMutation(
+    mutation_operator=bert_mutation,
+    population_size=population_size,
+    probability=0.4,
+)
+```
+
+Add `mutation_operator` to an EC-KitY subpopulation's `operators_sequence`. The BERT model is initialized locally from configuration and does not download pretrained model weights.
+
+### Compatibility
+
+- Python 3.9 or newer
+- EC-KitY 0.4.x
+- NumPy 2.0.2 or newer
+- SciPy 1.13.0 or newer
+- PyTorch 2.7.1 or newer
+- Transformers 4.50.0 or newer
+
+## Results from the paper
+
+### Fitness by generation
+
+The following figure presents representative best-individual fitness curves for BERT Mutation and the mutation baselines across the four evaluated domains.
+
+![Representative fitness curves across the evaluated domains](images/bert_ga.png "Convergence plots")
+
+*Best-individual fitness by generation, averaged over 10 runs. Black dots mark the runtime cutoffs.*
+
+### Statistical comparisons
+
+The following table presents the paired exact permutation-test results comparing BERT Mutation against each baseline in every evaluated domain.
+
+![Paired exact permutation-test results](images/p_values.png "Permutation-test results")
+
+*Holm-corrected p-values for comparisons between BERT Mutation and the baseline mutation operators.*
+
+## Benchmark instances
+
+*Benchmark instance sizes used in the experiments. The individual length $L$ denotes the genome length optimized by the GA.*
+
+| Domain | Instance | Problem size | Individual length $L$ |
+|---|---|---|---:|
+| **Artificial Ant** | | | |
+| Artificial Ant | `aux_map1` | $20 \times 20$, 91 food cells | 283 |
+| Artificial Ant | `aux_map2` | $20 \times 20$, 69 food cells | 286 |
+| Artificial Ant | `john_muir` | $32 \times 32$, 89 food cells | 200 |
+| Artificial Ant | `los_altos` | $100 \times 100$, 157 food cells | 800 |
+| Artificial Ant | `santafe` | $32 \times 32$, 89 food cells | 400 |
+| **Set Covering** | | | |
+| Set Covering | `scp41` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp51` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp52` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp53` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp54` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp56` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp57` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp64` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp65` | 200 rows, 1000 columns | 1000 |
+| **Frozen Lake** | | | |
+| Frozen Lake | `default` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand10x10` | $10 \times 10$ grid, 100 states | 100 |
+| Frozen Lake | `rand7x7` | $7 \times 7$ grid, 49 states | 49 |
+| Frozen Lake | `rand8x8` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand9x9` | $9 \times 9$ grid, 81 states | 81 |
+| **Graph Coloring** | | | |
+| Graph Coloring | `games120` | 120 vertices, 1276 edges | 120 |
+| Graph Coloring | `myciel7` | 191 vertices, 2360 edges | 191 |
+| Graph Coloring | `le450_5a` | 450 vertices, 5714 edges | 450 |
+| Graph Coloring | `mulsol.i.2` | 188 vertices, 3885 edges | 188 |
+| Graph Coloring | `zeroin.i.1` | 211 vertices, 4100 edges | 211 |
+| Graph Coloring | `zeroin.i.2` | 211 vertices, 3541 edges | 211 |
+
+## Getting started
+
+### Requirements
+
+- Python 3.9 or newer
+- A working PyTorch installation
+
+The code depends on:
+
+- `numpy`
+- `gymnasium`
+- `torch`
+- `transformers`
+- `eckity`
+
+### Installing for repository development
+
+From the repository root:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Running the experiments
+
+Artificial Ant:
+
+```bash
+python example_runner.py
+python -m dnm_paper.experiments.artificial_ant
+```
+
+Frozen Lake:
+
+```bash
+python example_runner_frozen_lake.py
+python -m dnm_paper.experiments.frozen_lake
+```
+
+Useful options:
+
+```bash
+python -m dnm_paper.experiments.artificial_ant --generations 100 --runs 3 --population-size 6
+python -m dnm_paper.experiments.artificial_ant --maps-dir artifical_ant_maps --output-dir experiments/artificial_ant/runs
+python -m dnm_paper.experiments.frozen_lake --generations 10 --runs 1 --population-size 100 --total-episodes 2000
+```
+
+By default, results are written under `experiments/artificial_ant/runs/<map_name>/bert_mutation/<run_id>/results.json`.
+Frozen Lake results are written under `experiments/frozen_lake/runs/<instance_name>/bert_mutation/<run_id>/results.json`.
+
+The experiment modules, benchmark maps, datasets, and result figures are repository resources and are not included in the `eckity-bert-ga` wheel.
+
+Release preparation and manual PyPI upload commands are documented in [`RELEASING.md`](RELEASING.md).
+
+## Project structure
+
+```text
+dnm_paper/
+  config.py                    Experiment configuration and default paths
+  individuals.py               Custom ECKITY individual creator
+  logging_utils.py             JSON statistics logger
+  experiments/
+    common.py                  Shared experiment helpers and mutation builder
+    artificial_ant.py          CLI entry point and experiment orchestration
+    frozen_lake.py             CLI entry point and experiment orchestration
+  mutation/
+    bert.py                    BERT-based mutation operator
+    eckity_adapter.py          Adapter that plugs the mutation operator into ECKITY
+  problems/
+    artificial_ant.py          Artificial ant map loader and evaluator
+    frozen_lake.py             Frozen Lake evaluator
+    frozen_lake_instances.py   Named Frozen Lake benchmark instances
+artifical_ant_maps/            Benchmark map files
+pyproject.toml                 Package metadata and dependencies
+```

eckity_bert_ga-0.1.0/dnm_paper/__init__.py

@@ -0,0 +1 @@
+"""Codebase for the DNM paper experiments."""

eckity_bert_ga-0.1.0/dnm_paper/config.py

@@ -0,0 +1,59 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_RESULTS_ROOT = PROJECT_ROOT / "experiments" / "artificial_ant" / "runs"
+DEFAULT_MAPS_DIR = PROJECT_ROOT / "artifical_ant_maps"
+DEFAULT_FROZEN_LAKE_RESULTS_ROOT = PROJECT_ROOT / "experiments" / "frozen_lake" / "runs"
+
+
+@dataclass(frozen=True)
+class MutationModelConfig:
+    batch_size: int = 64
+    learning_rate: float = 1e-3
+    epsilon_greedy: float = 0.05
+    mask_probability: float = 0.1
+    word_embedding_dim: int = 60
+    internal_size: int = 128
+    n_layers: int = 3
+    n_attention_heads: int = 3
+    normalize_batches: bool = False
+    best_ind_sample_size: int = 100
+    full_trajectory_query: bool = False
+    higher_is_better: bool = True
+
+
+@dataclass(frozen=True)
+class EvolutionConfig:
+    generations: int = 1000
+    population_size: int = 100
+    mutation_probability: float = 0.4
+    crossover_probability: float = 0.75
+    crossover_n_points: int = 2
+    tournament_size: int = 4
+    runs: int = 1
+    output_root: Path = DEFAULT_RESULTS_ROOT
+    maps_dir: Path = DEFAULT_MAPS_DIR
+    instances_to_run: dict[str, int] = field(
+        default_factory=lambda: {
+            "aux_map1.txt": 283,
+            "aux_map2.txt": 286,
+            "john_muir_trail.txt": 200,
+            "los_altos.txt": 800,
+            "santafe_trail.txt": 400,
+        }
+    )
+
+
+@dataclass(frozen=True)
+class FrozenLakeConfig:
+    generations: int = 100
+    population_size: int = 100
+    mutation_probability: float = 0.4
+    crossover_probability: float = 0.75
+    crossover_n_points: int = 2
+    tournament_size: int = 4
+    runs: int = 1
+    total_episodes: int = 2000
+    output_root: Path = DEFAULT_FROZEN_LAKE_RESULTS_ROOT

eckity_bert_ga-0.1.0/dnm_paper/individuals.py

@@ -0,0 +1,22 @@
+from eckity.creators import GAVectorCreator
+from eckity.genetic_encodings.ga import IntVector
+
+
+class GAIntegerStringVectorCreator(GAVectorCreator):
+    def __init__(self, length=1, bounds=(0, 1), gene_creator=None, events=None):
+        super().__init__(
+            length=length,
+            bounds=bounds,
+            gene_creator=gene_creator,
+            vector_type=IntVector,
+            events=events,
+        )
+
+    def individual_from_vector(self, vector):
+        individual = self.type(
+            length=self.length,
+            bounds=self.bounds,
+            fitness=self.fitness_type(higher_is_better=True),
+        )
+        individual.set_vector(vector)
+        return individual

eckity_bert_ga-0.1.0/dnm_paper/logging_utils.py

@@ -0,0 +1,59 @@
+import json
+import logging
+import time
+
+import numpy as np
+from eckity.statistics.statistics import Statistics
+
+
+logger = logging.getLogger(__name__)
+
+
+class FileLogger(Statistics):
+    """Persist per-generation summary statistics to JSON."""
+
+    def __init__(self, format_string=None, output_path=None, save_every_n_generations=50):
+        if format_string is None:
+            format_string = "best fitness {}\nworst fitness {}\naverage fitness {}\n"
+        self.output_path = output_path or "./experiment/results.json"
+        self.generation_stats = {
+            "mean": [],
+            "max": [],
+            "min": [],
+            "std": [],
+            "time": [],
+        }
+        super().__init__(format_string)
+        self.time_from_last_generation = time.time()
+        self.save_every_n_generations = save_every_n_generations
+
+    def write_statistics(self, sender, data_dict):
+        logger.info("generation #%s", data_dict["generation_num"])
+        for index, sub_population in enumerate(data_dict["population"].sub_populations):
+            logger.info("subpopulation #%s", index)
+            best_individual = sub_population.get_best_individual()
+            all_fitness_values = np.array(
+                [individual.get_pure_fitness() for individual in sub_population.individuals]
+            )
+
+            self.generation_stats["mean"].append(float(np.mean(all_fitness_values)))
+            self.generation_stats["max"].append(float(np.max(all_fitness_values)))
+            self.generation_stats["min"].append(float(np.min(all_fitness_values)))
+            self.generation_stats["std"].append(float(np.std(all_fitness_values)))
+            self.generation_stats["time"].append(time.time() - self.time_from_last_generation)
+            self.time_from_last_generation = time.time()
+
+            logger.info(
+                self.format_string.format(
+                    best_individual.get_pure_fitness(),
+                    sub_population.get_worst_individual().get_pure_fitness(),
+                    sub_population.get_average_fitness(),
+                )
+            )
+
+        if data_dict["generation_num"] % self.save_every_n_generations == 0:
+            self.save_expr()
+
+    def save_expr(self):
+        with open(self.output_path, "w", encoding="utf-8") as output_file:
+            json.dump(self.generation_stats, output_file)

eckity_bert_ga-0.1.0/dnm_paper/mutation/__init__.py

@@ -0,0 +1,4 @@
+from dnm_paper.mutation.bert import BertMutation
+from dnm_paper.mutation.eckity_adapter import EckityCustomMutation
+
+__all__ = ["BertMutation", "EckityCustomMutation"]

eckity_bert_ga-0.1.0/dnm_paper/mutation/bert.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+import torch
+from numpy.typing import NDArray
+from torch import Tensor
+from torch.optim import Adam
+from transformers import BertConfig, BertForMaskedLM
+
+
+GenomeArray = NDArray[np.integer[Any]]
+MaskArray = NDArray[np.bool_]
+FitnessDict = dict[tuple[int, ...], float]
+
+
+class BertMutation:
+    def __init__(
+        self,
+        max_int_val: int,
+        get_fitness_func: Callable[[GenomeArray], float],
+        batch_size: int = 64,
+        learning_rate: float = 1e-3,
+        adam_decay: float = 0,
+        epsilon_greedy: float = 0.01,
+        word_embedding_dim: int = 64,
+        context_size: int = 1024,
+        n_layers: int = 4,
+        n_attention_heads: int = 4,
+        internal_size: int = 64,
+        clip_grad_norm: float | None = 1.0,
+        full_trajectory_query: bool = False,
+        higher_is_better: bool = True,
+        mask_probability: float = 0.1,
+        normalize_batches: bool = False,
+        entropy_coefficient: float = 0.0,
+        scale_fitness_function: Callable[[Tensor], Tensor] | None = None,
+        fitness_dict: FitnessDict | None = None,
+        best_ind_scale_factor: float = 2.0,
+        best_ind_sample_size: int = 10,
+    ) -> None:
+        assert 0 <= mask_probability <= 1, "Mask probability must be between 0 and 1"
+        assert n_layers > 0, "Number of layers must be greater than 0"
+        assert n_attention_heads > 0, "Number of attention heads must be greater than 0"
+        assert internal_size > 0, "Internal size must be greater than 0"
+        assert word_embedding_dim > 0, "Word embedding dimension must be greater than 0"
+        assert context_size > 0, "Context size must be greater than 0"
+        assert batch_size > 0, "Batch size must be greater than 0"
+        assert learning_rate > 0, "Learning rate must be greater than 0"
+        assert max_int_val >= 1, "Max integer value must be at least 1"
+
+        self.vocab_size = max_int_val + 2
+        self.max_int_val = max_int_val
+        self.mask_id = max_int_val + 1
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        print(f"Using device: {self.device}")
+
+        bert_config = BertConfig(
+            vocab_size=self.vocab_size,
+            hidden_size=word_embedding_dim,
+            num_hidden_layers=n_layers,
+            num_attention_heads=n_attention_heads,
+            intermediate_size=internal_size,
+            max_position_embeddings=context_size,
+            pad_token_id=self.mask_id,
+        )
+        self.model = BertForMaskedLM(bert_config).to(self.device)
+        self.fitness_dict = fitness_dict
+        self.batch_size = batch_size
+        self.get_fitness_func = get_fitness_func
+        self.epsilon_greedy = epsilon_greedy
+        self.clip_grad_norm = clip_grad_norm
+        self.full_trajectory_query = full_trajectory_query
+        self.higher_is_better = higher_is_better
+        self.mask_probability = mask_probability
+        self.normalize_batches = normalize_batches
+        self.entropy_coefficient = entropy_coefficient
+        self.scale_fitness_function = scale_fitness_function
+        self.best_ind_scale_factor = best_ind_scale_factor
+        self.best_ind_sample_size = best_ind_sample_size
+        self.optimizer = Adam(self.model.parameters(), lr=learning_rate, weight_decay=adam_decay)
+        self.trajectory_log_probabilities: list[Tensor] = []
+        self.rewards: list[Tensor] = []
+        self.entropy_list: list[Tensor] = []
+
+    def mutate(self, individual_to_mutate: GenomeArray, mask: MaskArray) -> GenomeArray:
+        unmasked_tokens = np.copy(individual_to_mutate)
+        masked_individual = np.copy(unmasked_tokens)
+        masked_individual[mask] = self.mask_id
+
+        token_ids = torch.tensor(np.array([masked_individual]), dtype=torch.long, device=self.device)
+        logits = self.model(token_ids, attention_mask=torch.ones_like(token_ids, device=self.device)).logits
+        mask_indices = torch.where(token_ids == self.mask_id)[1]
+
+        suggested_mutation, trajectory_action_probabilities, dist_entropy = self.masked_trajectory_generation(
+            logits, mask_indices
+        )
+
+        for genome_index, suggested_value in zip(np.where(mask)[0], suggested_mutation):
+            unmasked_tokens[genome_index] = suggested_value
+
+        reward = self.get_fitness_func(unmasked_tokens)
+        self.log_trajectory_to_memory(dist_entropy, reward, trajectory_action_probabilities)
+
+        if self.fitness_dict is not None and self.fitness_dict:
+            self.peek_to_best_individual(logits)
+
+        self.run_epoch()
+        return unmasked_tokens
+
+    def log_trajectory_to_memory(
+        self,
+        dist_entropy: Tensor,
+        reward: float,
+        trajectory_action_probabilities: Tensor,
+    ) -> None:
+        trajectory_probability = torch.log(trajectory_action_probabilities).sum().unsqueeze(0).unsqueeze(0)
+        self.rewards.append(torch.full_like(trajectory_probability, reward))
+        self.trajectory_log_probabilities.append(trajectory_probability)
+        self.entropy_list.append(dist_entropy.unsqueeze(0).unsqueeze(0))
+
+    def get_mutation(self, individuals_to_mutate: Sequence[GenomeArray]) -> list[GenomeArray]:
+        mutated_individuals: list[GenomeArray] = []
+        individual_masks = self._sample_masks(individuals_to_mutate)
+        for individual_to_mutate, mask in zip(individuals_to_mutate, individual_masks):
+            mutated_individuals.append(self.mutate(individual_to_mutate, mask))
+        return mutated_individuals
+
+    def _sample_masks(self, individuals: Sequence[GenomeArray]) -> MaskArray:
+        n_individuals = len(individuals)
+        individual_length = len(individuals[0])
+        return np.random.choice(
+            [True, False],
+            size=(n_individuals, individual_length),
+            p=[self.mask_probability, 1 - self.mask_probability],
+        )
+
+    def masked_trajectory_generation(
+        self,
+        logits: Tensor,
+        mask_indices: Tensor,
+    ) -> tuple[NDArray[np.int64], Tensor, Tensor]:
+        n_masks = len(mask_indices)
+        operator_probabilities = torch.softmax(logits[0, mask_indices][:, :-1], dim=-1).to(self.device)
+        sampled_distribution = torch.distributions.Categorical(operator_probabilities)
+        sampled_operator_indices = sampled_distribution.sample().to(self.device)
+        dist_entropy = sampled_distribution.entropy().mean()
+
+        epsilon_greedy_probas = torch.rand(n_masks, device=self.device)
+        epsilon_greedy_masks = torch.where(epsilon_greedy_probas < self.epsilon_greedy)[0]
+        sampled_operator_indices[epsilon_greedy_masks] = torch.randint(
+            0, self.vocab_size - 1, (epsilon_greedy_masks.shape[0],), device=self.device
+        )
+        trajectory_action_probabilities = torch.gather(
+            operator_probabilities, dim=1, index=sampled_operator_indices.unsqueeze(-1)
+        )
+        suggested_mutation = sampled_operator_indices.detach().cpu().numpy()
+        return suggested_mutation, trajectory_action_probabilities, dist_entropy
+
+    def peek_to_best_individual(self, logits: Tensor) -> None:
+        top_k_individuals = sorted(
+            self.fitness_dict.items(),
+            key=lambda item: item[1],
+            reverse=self.higher_is_better,
+        )[: self.best_ind_sample_size]
+        best_individual = top_k_individuals[np.random.randint(0, len(top_k_individuals))][0]
+        best_individual_fitness = self.fitness_dict[tuple(best_individual)]
+
+        best_individual = torch.tensor(best_individual, dtype=torch.long, device=self.device).unsqueeze(0)
+        operator_probabilities = torch.softmax(logits[0][:, :-1], dim=-1).to(self.device)
+        dist_entropy = torch.distributions.Categorical(operator_probabilities).entropy().mean()
+        trajectory_action_probabilities = torch.gather(operator_probabilities, dim=1, index=best_individual.T)
+        self.log_trajectory_to_memory(
+            dist_entropy,
+            best_individual_fitness * self.best_ind_scale_factor,
+            trajectory_action_probabilities,
+        )
+
+    def run_epoch(self, numerical_stability: float = 1e-10) -> None:
+        if self.get_batch_size() < self.batch_size:
+            return
+
+        all_traj_proba = torch.cat(self.trajectory_log_probabilities, dim=0).to(self.device)
+        all_rewards = torch.cat(self.rewards, dim=0).to(self.device)
+        all_entropy = torch.cat(self.entropy_list, dim=0).to(self.device)
+
+        if self.scale_fitness_function is not None:
+            all_rewards = self.scale_fitness_function(all_rewards)
+
+        self.trajectory_log_probabilities.clear()
+        self.rewards.clear()
+        self.entropy_list.clear()
+        self.optimizer.zero_grad()
+
+        if self.normalize_batches:
+            advantages = (all_rewards - torch.mean(all_rewards)) / (torch.std(all_rewards) + numerical_stability)
+        else:
+            advantages = all_rewards
+
+        loss = -torch.mean(all_traj_proba * advantages) - self.entropy_coefficient * torch.mean(all_entropy)
+        loss.backward()
+        loss_value = loss.item()
+
+        if self.clip_grad_norm is not None:
+            torch.nn.utils.clip_grad_norm_(self.model.parameters(), self.clip_grad_norm)
+
+        self.optimizer.step()
+        print(f"loss: {loss_value}, reward: {torch.mean(all_rewards)}")
+
+    def get_batch_size(self) -> int:
+        return sum(len(reward) for reward in self.rewards)

eckity_bert_ga-0.1.0/dnm_paper/mutation/eckity_adapter.py

@@ -0,0 +1,31 @@
+import numpy as np
+from eckity.genetic_operators import GeneticOperator
+
+
+class EckityCustomMutation(GeneticOperator):
+    """Wrap a mutation model so it can be applied through ECKITY."""
+
+    def __init__(self, mutation_operator, population_size, probability=1.0, events=None):
+        super().__init__(probability=1.0, arity=population_size, events=events)
+        self.mutation_operator = mutation_operator
+        self.mutation_probability = probability
+
+    def apply(self, individuals):
+        mutation_masks = np.random.rand(len(individuals)) < self.mutation_probability
+        individuals_matrix = np.array([individual.vector for individual in individuals])[mutation_masks]
+
+        if len(individuals_matrix) == 0:
+            return individuals
+
+        mutated_individuals = self.mutation_operator.get_mutation(individuals_matrix)
+        eckity_mutated_individuals = [
+            individual for index, individual in enumerate(individuals) if mutation_masks[index]
+        ]
+        assert len(mutated_individuals) == len(
+            eckity_mutated_individuals
+        ), "Mutated individuals length mismatch"
+
+        for index, individual in enumerate(eckity_mutated_individuals):
+            individual.set_vector(list(mutated_individuals[index]))
+
+        return individuals

eckity_bert_ga-0.1.0/eckity_bert_ga/__init__.py

@@ -0,0 +1,10 @@
+"""BERT mutation operator for EC-KitY genetic algorithms."""
+
+from dnm_paper.individuals import GAIntegerStringVectorCreator
+from dnm_paper.mutation import BertMutation, EckityCustomMutation
+
+__all__ = [
+    "BertMutation",
+    "EckityCustomMutation",
+    "GAIntegerStringVectorCreator",
+]

eckity_bert_ga-0.1.0/eckity_bert_ga.egg-info/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: eckity-bert-ga
+Version: 0.1.0
+Summary: BERT mutation operator for EC-KitY genetic algorithms
+Author: EC-KitY
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/EC-KitY/BERT-Mutation-for-GA
+Project-URL: Repository, https://github.com/EC-KitY/BERT-Mutation-for-GA
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: eckity~=0.4.1
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: scipy>=1.13.0
+Requires-Dist: torch>=2.7.1
+Requires-Dist: transformers>=4.50.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: gymnasium>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# BERT Mutation for Genetic Algorithms
+
+## Overview
+
+This repository implements the paper `BERT Mutation: Deep Transformer Model for Masked Uniform Mutation in Genetic Algorithms`.
+
+The paper proposes a domain-independent mutation operator for genetic algorithms that uses a BERT-style masked model to predict beneficial gene replacements from context. To make this work for fixed-length GA representations, it adds an elite-guided data augmentation mechanism that creates additional learning signal from strong historical solutions.
+
+In the paper, the method is evaluated on four domains: Frozen Lake, Artificial Ant, Graph Coloring, and Unweighted Set Cover. The reported results show faster convergence and better final fitness than standard mutation baselines and an adaptive operator-selection baseline, while maintaining meaningful population diversity.
+
+## Installation
+
+```bash
+pip install eckity-bert-ga
+```
+
+## Using the operator
+
+Import the public API from `eckity_bert_ga`:
+
+```python
+from eckity_bert_ga import (
+    BertMutation,
+    EckityCustomMutation,
+    GAIntegerStringVectorCreator,
+)
+```
+
+Create the BERT mutation model and wrap it as an EC-KitY operator:
+
+```python
+population_size = 100
+
+bert_mutation = BertMutation(
+    max_int_val=MAX_GENE_VALUE,
+    get_fitness_func=evaluate_vector,
+    context_size=INDIVIDUAL_LENGTH + 1,
+    mask_probability=0.1,
+)
+
+mutation_operator = EckityCustomMutation(
+    mutation_operator=bert_mutation,
+    population_size=population_size,
+    probability=0.4,
+)
+```
+
+Add `mutation_operator` to an EC-KitY subpopulation's `operators_sequence`. The BERT model is initialized locally from configuration and does not download pretrained model weights.
+
+### Compatibility
+
+- Python 3.9 or newer
+- EC-KitY 0.4.x
+- NumPy 2.0.2 or newer
+- SciPy 1.13.0 or newer
+- PyTorch 2.7.1 or newer
+- Transformers 4.50.0 or newer
+
+## Results from the paper
+
+### Fitness by generation
+
+The following figure presents representative best-individual fitness curves for BERT Mutation and the mutation baselines across the four evaluated domains.
+
+![Representative fitness curves across the evaluated domains](images/bert_ga.png "Convergence plots")
+
+*Best-individual fitness by generation, averaged over 10 runs. Black dots mark the runtime cutoffs.*
+
+### Statistical comparisons
+
+The following table presents the paired exact permutation-test results comparing BERT Mutation against each baseline in every evaluated domain.
+
+![Paired exact permutation-test results](images/p_values.png "Permutation-test results")
+
+*Holm-corrected p-values for comparisons between BERT Mutation and the baseline mutation operators.*
+
+## Benchmark instances
+
+*Benchmark instance sizes used in the experiments. The individual length $L$ denotes the genome length optimized by the GA.*
+
+| Domain | Instance | Problem size | Individual length $L$ |
+|---|---|---|---:|
+| **Artificial Ant** | | | |
+| Artificial Ant | `aux_map1` | $20 \times 20$, 91 food cells | 283 |
+| Artificial Ant | `aux_map2` | $20 \times 20$, 69 food cells | 286 |
+| Artificial Ant | `john_muir` | $32 \times 32$, 89 food cells | 200 |
+| Artificial Ant | `los_altos` | $100 \times 100$, 157 food cells | 800 |
+| Artificial Ant | `santafe` | $32 \times 32$, 89 food cells | 400 |
+| **Set Covering** | | | |
+| Set Covering | `scp41` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp51` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp52` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp53` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp54` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp56` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp57` | 200 rows, 2000 columns | 2000 |
+| Set Covering | `scp64` | 200 rows, 1000 columns | 1000 |
+| Set Covering | `scp65` | 200 rows, 1000 columns | 1000 |
+| **Frozen Lake** | | | |
+| Frozen Lake | `default` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand10x10` | $10 \times 10$ grid, 100 states | 100 |
+| Frozen Lake | `rand7x7` | $7 \times 7$ grid, 49 states | 49 |
+| Frozen Lake | `rand8x8` | $8 \times 8$ grid, 64 states | 64 |
+| Frozen Lake | `rand9x9` | $9 \times 9$ grid, 81 states | 81 |
+| **Graph Coloring** | | | |
+| Graph Coloring | `games120` | 120 vertices, 1276 edges | 120 |
+| Graph Coloring | `myciel7` | 191 vertices, 2360 edges | 191 |
+| Graph Coloring | `le450_5a` | 450 vertices, 5714 edges | 450 |
+| Graph Coloring | `mulsol.i.2` | 188 vertices, 3885 edges | 188 |
+| Graph Coloring | `zeroin.i.1` | 211 vertices, 4100 edges | 211 |
+| Graph Coloring | `zeroin.i.2` | 211 vertices, 3541 edges | 211 |
+
+## Getting started
+
+### Requirements
+
+- Python 3.9 or newer
+- A working PyTorch installation
+
+The code depends on:
+
+- `numpy`
+- `gymnasium`
+- `torch`
+- `transformers`
+- `eckity`
+
+### Installing for repository development
+
+From the repository root:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Running the experiments
+
+Artificial Ant:
+
+```bash
+python example_runner.py
+python -m dnm_paper.experiments.artificial_ant
+```
+
+Frozen Lake:
+
+```bash
+python example_runner_frozen_lake.py
+python -m dnm_paper.experiments.frozen_lake
+```
+
+Useful options:
+
+```bash
+python -m dnm_paper.experiments.artificial_ant --generations 100 --runs 3 --population-size 6
+python -m dnm_paper.experiments.artificial_ant --maps-dir artifical_ant_maps --output-dir experiments/artificial_ant/runs
+python -m dnm_paper.experiments.frozen_lake --generations 10 --runs 1 --population-size 100 --total-episodes 2000
+```
+
+By default, results are written under `experiments/artificial_ant/runs/<map_name>/bert_mutation/<run_id>/results.json`.
+Frozen Lake results are written under `experiments/frozen_lake/runs/<instance_name>/bert_mutation/<run_id>/results.json`.
+
+The experiment modules, benchmark maps, datasets, and result figures are repository resources and are not included in the `eckity-bert-ga` wheel.
+
+Release preparation and manual PyPI upload commands are documented in [`RELEASING.md`](RELEASING.md).
+
+## Project structure
+
+```text
+dnm_paper/
+  config.py                    Experiment configuration and default paths
+  individuals.py               Custom ECKITY individual creator
+  logging_utils.py             JSON statistics logger
+  experiments/
+    common.py                  Shared experiment helpers and mutation builder
+    artificial_ant.py          CLI entry point and experiment orchestration
+    frozen_lake.py             CLI entry point and experiment orchestration
+  mutation/
+    bert.py                    BERT-based mutation operator
+    eckity_adapter.py          Adapter that plugs the mutation operator into ECKITY
+  problems/
+    artificial_ant.py          Artificial ant map loader and evaluator
+    frozen_lake.py             Frozen Lake evaluator
+    frozen_lake_instances.py   Named Frozen Lake benchmark instances
+artifical_ant_maps/            Benchmark map files
+pyproject.toml                 Package metadata and dependencies
+```

eckity_bert_ga-0.1.0/eckity_bert_ga.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+dnm_paper/__init__.py
+dnm_paper/config.py
+dnm_paper/individuals.py
+dnm_paper/logging_utils.py
+dnm_paper/mutation/__init__.py
+dnm_paper/mutation/bert.py
+dnm_paper/mutation/eckity_adapter.py
+eckity_bert_ga/__init__.py
+eckity_bert_ga.egg-info/PKG-INFO
+eckity_bert_ga.egg-info/SOURCES.txt
+eckity_bert_ga.egg-info/dependency_links.txt
+eckity_bert_ga.egg-info/requires.txt
+eckity_bert_ga.egg-info/top_level.txt
+tests/test_package.py

eckity_bert_ga-0.1.0/eckity_bert_ga.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

eckity_bert_ga-0.1.0/eckity_bert_ga.egg-info/requires.txt

@@ -0,0 +1,11 @@
+eckity~=0.4.1
+numpy>=2.0.2
+scipy>=1.13.0
+torch>=2.7.1
+transformers>=4.50.0
+
+[dev]
+build>=1.2
+gymnasium>=1.0
+pytest>=8.0
+twine>=5.0

eckity_bert_ga-0.1.0/eckity_bert_ga.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dnm_paper
+eckity_bert_ga

eckity_bert_ga-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eckity-bert-ga"
+version = "0.1.0"
+description = "BERT mutation operator for EC-KitY genetic algorithms"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [{ name = "EC-KitY" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "eckity~=0.4.1",
+    "numpy>=2.0.2",
+    "scipy>=1.13.0",
+    "torch>=2.7.1",
+    "transformers>=4.50.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "gymnasium>=1.0",
+    "pytest>=8.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/EC-KitY/BERT-Mutation-for-GA"
+Repository = "https://github.com/EC-KitY/BERT-Mutation-for-GA"
+
+[tool.setuptools]
+packages = ["eckity_bert_ga", "dnm_paper", "dnm_paper.mutation"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

eckity_bert_ga-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

eckity_bert_ga-0.1.0/tests/test_package.py

@@ -0,0 +1,84 @@
+import unittest
+
+import numpy as np
+from eckity.algorithms.simple_evolution import SimpleEvolution
+from eckity.breeders.simple_breeder import SimpleBreeder
+from eckity.evaluators.simple_individual_evaluator import SimpleIndividualEvaluator
+from eckity.genetic_operators.selections.tournament_selection import TournamentSelection
+from eckity.subpopulation import Subpopulation
+
+from dnm_paper.individuals import GAIntegerStringVectorCreator as OriginalCreator
+from dnm_paper.mutation import BertMutation as OriginalBertMutation
+from dnm_paper.mutation import EckityCustomMutation as OriginalEckityCustomMutation
+from eckity_bert_ga import BertMutation, EckityCustomMutation, GAIntegerStringVectorCreator
+
+
+class SumEvaluator(SimpleIndividualEvaluator):
+    def evaluate_individual(self, individual):
+        return float(np.sum(individual.vector))
+
+
+def create_mutation(evaluator, population_size):
+    model = BertMutation(
+        max_int_val=3,
+        get_fitness_func=lambda vector: float(np.sum(vector)),
+        batch_size=1024,
+        epsilon_greedy=0.0,
+        word_embedding_dim=8,
+        context_size=8,
+        n_layers=1,
+        n_attention_heads=2,
+        internal_size=8,
+        mask_probability=1.0,
+    )
+    adapter = EckityCustomMutation(
+        mutation_operator=model,
+        population_size=population_size,
+        probability=1.0,
+    )
+    return model, adapter
+
+
+class PackageTests(unittest.TestCase):
+    def test_public_api_reexports_existing_classes(self):
+        self.assertIs(BertMutation, OriginalBertMutation)
+        self.assertIs(EckityCustomMutation, OriginalEckityCustomMutation)
+        self.assertIs(GAIntegerStringVectorCreator, OriginalCreator)
+
+    def test_mutation_output_shape_and_bounds(self):
+        model, _ = create_mutation(SumEvaluator(), population_size=2)
+        genomes = [np.array([0, 1, 2, 3]), np.array([3, 2, 1, 0])]
+
+        mutated = model.get_mutation(genomes)
+
+        self.assertEqual(len(mutated), len(genomes))
+        for genome in mutated:
+            self.assertEqual(genome.shape, genomes[0].shape)
+            self.assertTrue(np.all(genome >= 0))
+            self.assertTrue(np.all(genome <= 3))
+
+    def test_two_generation_eckity_evolution(self):
+        population_size = 4
+        creator = GAIntegerStringVectorCreator(length=4, bounds=(0, 3))
+        evaluator = SumEvaluator()
+        model, adapter = create_mutation(evaluator, population_size)
+        algorithm = SimpleEvolution(
+            Subpopulation(
+                creators=creator,
+                population_size=population_size,
+                evaluator=evaluator,
+                higher_is_better=True,
+                operators_sequence=[adapter],
+                selection_methods=[
+                    (TournamentSelection(tournament_size=2, higher_is_better=True), 1)
+                ],
+            ),
+            breeder=SimpleBreeder(),
+            max_workers=1,
+            max_generation=2,
+            random_seed=4242,
+        )
+
+        algorithm.evolve()
+
+        self.assertGreater(len(model.rewards), 0)