Metadata-Version: 2.4
Name: eckity-dnc
Version: 0.1.1
Summary: Deep Neural Crossover operator for EC-KitY
Author: EC-KitY
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/EC-KitY/DNC
Project-URL: Repository, https://github.com/EC-KitY/DNC
Project-URL: Paper, https://doi.org/10.1145/3638529.3654020
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
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# Deep Neural Crossover for EC-KitY

`eckity-dnc` provides the Deep Neural Crossover (DNC) genetic operator for [EC-KitY](https://github.com/EC-KitY/EC-KitY).

DNC is described in **“Deep Neural Crossover: A Multi-Parent Operator That Leverages Gene Correlations”** ([paper](https://doi.org/10.1145/3638529.3654020)).

## Installation

```bash
pip install eckity-dnc
```

Installing `eckity-dnc` also installs its EC-KitY, PyTorch, NumPy, and SciPy dependencies.

## Usage

Import the public API from `eckity_dnc`:

```python
from eckity_dnc import (
    DeepNeuralCrossover,
    DeepNeuralCrossoverConfig,
    GAIntegerStringVectorCreator,
)
```

Create the vector creator and DNC operator:

```python
population_size = 100
individual_length = 160
number_of_gene_values = 161

individual_creator = GAIntegerStringVectorCreator(
    length=individual_length,
    bounds=(0, number_of_gene_values - 1),
)

dnc_config = DeepNeuralCrossoverConfig(
    embedding_dim=64,
    sequence_length=individual_length,
    num_embeddings=number_of_gene_values,
    running_mean_decay=0.95,
    batch_size=1024,
    learning_rate=1e-4,
    use_device="cpu",
    n_parents=2,
    epsilon_greedy=0.3,
)

dnc_operator = DeepNeuralCrossover(
    probability=0.8,
    population_size=population_size,
    dnc_config=dnc_config,
    individual_evaluator=your_eckity_evaluator,
    vector_creator=individual_creator,
)
```

Add `dnc_operator` to the EC-KitY subpopulation's `operators_sequence`. The supplied evaluator must inherit from EC-KitY's `SimpleIndividualEvaluator` and evaluate vectors created by `individual_creator`.

See [`dnc_runner_eckity.py`](dnc_runner_eckity.py) for a complete bin-packing example using tournament selection and mutation.

## Compatibility

- Python 3.9 or newer
- EC-KitY 0.4.x (tested with 0.4.1)
- PyTorch 2.7.1 or newer (tested with 2.7.1)
- NumPy 2.0.2 or newer (tested with 2.0.2)
- SciPy 1.13.0 or newer (tested with 1.13.0)

## Development

Install the package and development tools, then run the tests:

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

Release preparation and manual TestPyPI/PyPI commands are documented in [`RELEASING.md`](RELEASING.md).

## License

This project is licensed under the GNU General Public License v3.0. See [`LICENSE`](LICENSE).
