Metadata-Version: 2.4
Name: geatpy-rs
Version: 2.7.3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: numpy>=1.17.0
Requires-Dist: matplotlib>=3.0.0
Requires-Dist: scipy>=1.0.0
License-File: LICENSE
Summary: The Genetic and Evolutionary Algorithm Toolbox for Python with High-Performance Rust Core
Home-Page: https://www.yangyachao.com
Author: Geatpy Development Team
Author-email: yangyachao <yangyachao@live.cn>
Maintainer-email: yangyachao <yangyachao@live.cn>
License: LGPL-3.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://www.yangyachao.com
Project-URL: Issues, https://github.com/yangyachao/geatpy/issues
Project-URL: Repository, https://github.com/yangyachao/geatpy

# **Geatpy (Rust Core Edition)**
The High-Performance Genetic and Evolutionary Algorithm Toolbox for Python, Powered by Rust.

[![CI](https://github.com/yangyachao/geatpy/actions/workflows/ci.yml/badge.svg)](https://github.com/yangyachao/geatpy/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/yangyachao/geatpy?color=blue&logo=github)](https://github.com/yangyachao/geatpy/releases)
[![Python Version](https://img.shields.io/badge/python-3.8_~_3.15-blue.svg?logo=python&logoColor=white)](https://pypi.org/project/geatpy-rs/)
[![Rust](https://img.shields.io/badge/rust-PyO3_abi3-orange.svg?logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/license-LGPL--3.0-green.svg)](LICENSE)

---

## 📌 项目渊源与致敬 (Upstream Heritage & Fork Notice)

本项目是经典高性能进化算法工具箱 **[geatpy-dev/geatpy](https://github.com/geatpy-dev/geatpy)** 的现代化高性能 Rust 重构版本。

- **原官方项目主页**: [https://github.com/geatpy-dev/geatpy](https://github.com/geatpy-dev/geatpy)
- **官方文档与教程**: [http://www.geatpy.com](http://www.geatpy.com) / [Geatpy Documentation](https://github.com/geatpy-dev/geatpy/tree/master/docs)
- **开源致谢**: 衷心感谢原作者团队在进化计算领域的杰出贡献与算法设计奠基。

### 为什么发起这个重构版本？(Motivation)
原版 Geatpy 的内核只以预编译二进制分发，在现代开发与生产环境中面临三个痛点：
1. **高版本 Python 无法安装**: 原版只发布到 Python 3.10 的预编译轮子。在 Python 3.11 ~ 3.15 上 pip 找不到匹配的轮子，只能退回源码构建，而原版内核并不随源码公开，基本无法安装。
2. **ARM 平台覆盖不全**: 原版的 Apple Silicon 轮子只覆盖 Python 3.8 ~ 3.10，且没有 Linux ARM64 (aarch64) 轮子，在 ARM 云服务器、树莓派与 Docker 容器里装不上。
3. **二进制内核难排错**: 长度为 1 的染色体、一维输入等边界情况会直接段错误，整个 Python 进程退出；还有多处行为与其自身文档不符。

为此，**本项目用 Rust (PyO3 + abi3) 重写了全部 74 个内核算子**，Python 层（算法模板、`Problem`、`Population` 等）原样保留，
提供 Python 3.8 ~ 3.15 通用的全平台预编译 Wheel。

---

## ⚡ 核心改进与特性对比 (Key Improvements)

| 特性维度 | 原官方版本 (Geatpy) | 本版本 (Geatpy Rust Core Edition) |
| :--- | :--- | :--- |
| **底层核心实现** | 编译好的二进制扩展，内核源码未公开 | **纯 Rust 原生实现** (`crates/geatpy_core`)，源码公开 |
| **Python 版本支持** | 仅支持 Python 3.5 ~ 3.10 | **Python 3.8 ~ 3.15 全覆盖支持** |
| **ABI 兼容性** | 每个 Python 小版本单独构建 | **PyO3 `abi3` 单一构建兼容所有 Python 3.8+ 版本** |
| **跨平台预编译** | Windows x86/x64、Linux x86_64、macOS（Apple Silicon 仅 Python 3.8 ~ 3.10），无 Linux ARM64 | **全平台官方预编译 Wheel (Linux x86_64/ARM64, macOS Universal2, Windows x64)** |
| **代码与内存安全** | 边界输入可能触发段错误，导致 Python 进程退出 | **纯安全 Rust（无 `unsafe`），非法输入抛出 Python 异常而非段错误** |
| **多核并行与性能** | C OpenMP 并行 | 单线程实现（`Parallel` 参数为兼容保留，暂不生效）；36 个经典用例耗时为原版的 0.21~1.02 倍 |
| **API 兼容度** | 原版基准 | **沿用原有 Python API、数据结构与 42 个算法模板；内核行为已与官方 2.7.0 二进制逐项对照验证（见下文）** |

---

## ✅ 与官方 2.7.0 内核的一致性 (Parity)

Rust 内核以官方 geatpy 2.7.0 的 `_core` 二进制为行为基准，通过黑盒差分测试持续验证：

- **基准数据**：`scripts/parity/run_original_core.sh` 在 Docker (linux/amd64 + Python 3.6) 中运行官方二进制，
  生成 `tests/fixtures/core_parity_orig_2_7_0.json`；
- **确定性算子**（非支配排序、拥挤距离、编码解码、适应度分配、参考点、指标、NSGA-III/RVEA 环境选择等）逐值比对；
- **随机算子**（交叉、变异、选择）按统计特征比对；与官方一致，随机数取自 numpy 全局随机状态，
  `np.random.seed` / `ea.optimize(seed=...)` 可完整复现一次运行；
- **算法模板**（39 个单/多目标模板）比对最终解质量：`GEATPY_PARITY_TEMPLATES=1 pytest tests/test_core_parity.py`；
- **逐模块复核**（`tests/test_core_parity_review.py`）：对全部内核算子逐一核对，补齐了返回类型
  （全整数变量时返回 `int32`）、参数校验、`crtidp` 约束处理等细节，期望值均取自官方二进制的实际输出；
- **随机差分与交叉审查**（`tests/test_core_parity_review2.py`、`scripts/parity/fuzz/`）：约 1500 个随机形状、参数组合与
  边界值用例同时在官方二进制与 Rust 内核上运行，逐项比对数值、dtype、返回结构与报错，随机算子比对统计分布；
  并由另一模型（Antigravity）独立交叉审查。整数输出与官方一致为 `int32`，参数校验与报错信息与官方一致；
- **经典用例对比**（`scripts/parity/classic.py`）：Ackley、Rosenbrock、Rastrigin、att48 TSP、ZDT、DTLZ、BNH 等
  36 个问题与算法模板组合，覆盖最大化、混合整数、带约束、奇数种群、排列编码、多种群与多染色体（psy）模板，
  两边各运行 30 次比较最优值或 IGD/HV 的分布。除多种群 `soea_multi_SEGA_templet` 外均无显著差异；该模板的
  迁移用 `Replacement=2`，原版此处淘汰的是最优个体，本项目按文档淘汰最差个体，解明显更好（关闭迁移后两边一致）。

内核行为依据官方文档、docstring 与上述差分测试结果实现。
官方二进制中有几处与其自身文档不符的缺陷，本项目按文档实现，测试中单独说明：
`ndsortDED` 分层错误、`mergecv` 跨行累加、`tcheby`/`pbi` 在 `idealPoint=None` 时返回理想点、
`refselect` 候选矩阵行序错位、`migrate` 择劣替换（`Replacement=2`）实际淘汰的是最优个体、
`mutgau`/`mutuni` 的 `Middle=True` 以 `(ub-lb)/2` 而非区间中点为中心、
`crtip` 在边界为小数时会生成越界整数、`migrate` 随机替换（`Replacement=1`）总是淘汰最后一个个体且
完全网状结构（`Structure=0`）会从自身迁入、`pbi` 对恰在理想点上的个体返回 NaN、`crowdis` 在目标值含 inf 时
返回 NaN、`cdist` 对非连续数组（如 `A[::-1]`）读错数据；此外官方二进制在染色体长度为 1 或输入一维时会
段错误（`xovsp`/`xovsh` 等），Rust 内核正常处理。

---

## 📦 安装指南 (Installation)

### 方式一：通过 pip 一键安装 (PyPI 推荐)

```bash
pip install geatpy-rs
```

> 💡 **提示**：分发包名为 `geatpy-rs`，在 Python 代码中完全无需改动，继续沿用熟悉的 **`import geatpy as ea`** 即可无缝调用！

### 方式二：从 GitHub Releases 下载预编译 Wheel

前往 [Releases 页面](https://github.com/yangyachao/geatpy/releases) 下载对应系统的 Wheel 文件，或通过链接一键安装：

```bash
# Linux (x86_64)
pip install https://github.com/yangyachao/geatpy/releases/download/v2.7.3/geatpy_rs-2.7.3-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

# Linux (ARM64 / aarch64)
pip install https://github.com/yangyachao/geatpy/releases/download/v2.7.3/geatpy_rs-2.7.3-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

# macOS (Universal2 - 支持 Apple Silicon M1/M2/M3/M4 以及 Intel Mac)
pip install https://github.com/yangyachao/geatpy/releases/download/v2.7.3/geatpy_rs-2.7.3-cp38-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

# Windows (x86_64)
pip install https://github.com/yangyachao/geatpy/releases/download/v2.7.3/geatpy_rs-2.7.3-cp38-abi3-win_amd64.whl
```

### 方式三：从源码本地构建

克隆仓库后，仅需 Rust 工具链与 `maturin` 即可一键构建安装：

```bash
git clone https://github.com/yangyachao/geatpy.git
cd geatpy

# 使用内置跨平台构建脚本
python scripts/build.py --install

# 或使用 maturin 直接安装至当前环境
pip install maturin
maturin develop --release
```

详细本地编译、跨平台交叉编译与单元测试说明，请参阅 [BUILD.md](BUILD.md)。

---

## 🚀 快速上手 (Quick Start)

原有代码和案例库无需进行任何修改，直接沿用原有接口即可：

### 示例：使用 NSGA-III 求解经典 DTLZ1 三目标优化问题

```python
import numpy as np
import geatpy as ea

class DTLZ1(ea.Problem):
    def __init__(self, M=3):
        name = 'DTLZ1'
        maxormins = [1] * M
        Dim = M + 4
        varTypes = [0] * Dim
        lb = [0] * Dim
        ub = [1] * Dim
        lbin = [1] * Dim
        ubin = [1] * Dim
        ea.Problem.__init__(self, name, M, maxormins, Dim, varTypes, lb, ub, lbin, ubin)

    def aimFunc(self, pop):
        Vars = pop.Phen
        XM = Vars[:, (self.M - 1):]
        g = np.array([100 * (self.Dim - self.M + 1 + np.sum(((XM - 0.5)**2 - np.cos(20 * np.pi * (XM - 0.5))), 1))]).T
        ones_metrix = np.ones((Vars.shape[0], 1))
        pop.ObjV = 0.5 * np.fliplr(np.cumprod(np.hstack([ones_metrix, Vars[:, :self.M - 1]]), 1)) * \
                   np.hstack([ones_metrix, 1 - Vars[:, range(self.M - 2, -1, -1)]]) * np.tile(1 + g, (1, self.M))

if __name__ == '__main__':
    problem = DTLZ1(M=3)
    algorithm = ea.moea_NSGA3_templet(
        problem,
        ea.Population(Encoding='RI', NIND=100),
        MAXGEN=500,
        logTras=1
    )
    res = ea.optimize(algorithm, verbose=True, drawing=1, outputMsg=True, drawLog=True)
```

---

## 📊 架构设计与底层算子覆盖

Rust 内核位于 `crates/geatpy_core/`，导出 74 个算子，名称与原版一致：

- **编码与种群初始化 (`encoding.rs`)**: `crtfld`, `crtbp`, `crtip`, `crtrp`, `crtri`, `crtpp`, `crtpc`, `crtup`, `crtgp`, `bs2ri`, `bs2real`, `bs2int`, `ri2bs`, `boundfix`
- **选择与适应度 (`selection.rs`)**: `tour`, `etour`, `rws`, `sus`, `urs`, `rcs`, `rps`, `ecs`, `otos`, `dup`, `selecting`, `mselecting`, `ranking`, `scaling`, `powing`, `indexing`
- **交叉与重组 (`recombination.rs`)**: `xovsp`, `xovdp`, `xovud`, `xovsh`, `xovbd`, `xovexp`, `xovsec`, `xovpmx`, `xovox`, `recsbx`, `recdis`, `recint`, `reclin`, `recndx`, `recombin`
- **变异 (`mutation.rs`)**: `mutpolyn`, `mutgau`, `mutbga`, `mutuni`, `mutbin`, `mutde`, `mutinv`, `mutmove`, `mutswap`, `mutpp`, `mutate`
- **多目标、约束与迁移 (`multiobjective.rs`)**: `ndsortESS`, `ndsortTNS`, `ndsortDED`, `crowdis`, `cdist`, `mergecv`, `tcheby`, `pbi`, `crtidp`, `awGA`, `rwGA`, `refselect`, `refgselect`, `migrate`
- **性能指标 (`indicator.rs`)**: `GD`, `IGD`, `Spacing`, `HV`

---

## 📄 引用 (Citation) & 许可证 (License)

如果您在学术研究中使用了本项目，请按照原项目规范引用：

```bibtex
@misc{geatpy2020,
  author = {Jazzbin, J.},
  title = {Geatpy: The Genetic and Evolutionary Algorithm Toolbox with High Performance in Python},
  year = {2020},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/geatpy-dev/geatpy}}
}
```

本项目继承原项目协议，采用 **[GNU Lesser General Public License v3.0 (LGPL-3.0)](LICENSE)** 开源。

---

## 👤 维护者与版权 (Maintainer & Copyright)

- **Rust Core 发行版维护者**: yangyachao ([www.yangyachao.com](https://www.yangyachao.com))
- **联系邮箱**: [yangyachao@live.cn](mailto:yangyachao@live.cn)
- **代码仓库**: [https://github.com/yangyachao/geatpy](https://github.com/yangyachao/geatpy)

### 版权声明 (Copyright Notice)
- **Rust Core 重构实现与打包分发版权**: Copyright (C) 2026 yangyachao.
- **原版算法设计与 Python 架构版权**: Copyright (C) 2018-2021 Geatpy Development Team.
- 本项目基于 **[LGPL-3.0 License](LICENSE)** 协议开源。

