choccy 0.0.9__tar.gz

choccy-0.0.9/LICENSE

@@ -0,0 +1,127 @@
+                     木兰宽松许可证, 第2版
+
+   木兰宽松许可证， 第2版
+   2020年1月 http://license.coscl.org.cn/MulanPSL2
+
+
+   您对“软件”的复制、使用、修改及分发受木兰宽松许可证，第2版（“本许可证”）的如下条款的约束：
+
+   0. 定义
+
+      “软件”是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。
+
+      “贡献”是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。
+
+      “贡献者”是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。
+
+      “法人实体”是指提交贡献的机构及其“关联实体”。
+
+      “关联实体”是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。
+
+   1. 授予版权许可
+
+      每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可以复制、使用、修改、分发其“贡献”，不论修改与否。
+
+   2. 授予专利许可
+
+      每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定撤销除外）专利许可，供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软件”结合而将必然会侵犯的专利权利要求，不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“关联实体”直接或间接地，就“软件”或其中的“贡献”对任何人发起专利侵权诉讼（包括反诉或交叉诉讼）或其他专利维权行动，指控其侵犯专利权，则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权行动之日终止。
+
+   3. 无商标许可
+
+      “本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可，但您为满足第4条规定的声明义务而必须使用除外。
+
+   4. 分发限制
+
+      您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发，不论修改与否，但您必须向接收者提供“本许可证”的副本，并保留“软件”中的版权、商标、专利及免责声明。
+
+   5. 免责声明与责任限制
+
+      “软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下，“贡献者”或版权所有者不对任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任，不论因何种原因导致或者基于何种法律理论，即使其曾被建议有此种损失的可能性。
+
+   6. 语言
+      “本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致，以中文版为准。
+
+   条款结束
+
+   如何将木兰宽松许可证，第2版，应用到您的软件
+
+   如果您希望将木兰宽松许可证，第2版，应用到您的新软件，为了方便接收者查阅，建议您完成如下三步：
+
+      1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字；
+
+      2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中；
+
+      3， 请将如下声明文本放入每个源文件的头部注释中。
+
+   Copyright (c) 2024 LuChen Wang
+   CHOCCY is licensed under Mulan PSL v2.
+   You can use this software according to the terms and conditions of the Mulan PSL v2.
+   You may obtain a copy of Mulan PSL v2 at:
+            http://license.coscl.org.cn/MulanPSL2
+   THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+   See the Mulan PSL v2 for more details.
+
+
+                     Mulan Permissive Software License，Version 2
+
+   Mulan Permissive Software License，Version 2 (Mulan PSL v2)
+   January 2020 http://license.coscl.org.cn/MulanPSL2
+
+   Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions:
+
+   0. Definition
+
+      Software means the program and related documents which are licensed under this License and comprise all Contribution(s).
+
+      Contribution means the copyrightable work licensed by a particular Contributor under this License.
+
+      Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License.
+
+      Legal Entity means the entity making a Contribution and all its Affiliates.
+
+      Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity.
+
+   1. Grant of Copyright License
+
+      Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not.
+
+   2. Grant of Patent License
+
+      Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken.
+
+   3. No Trademark License
+
+      No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4.
+
+   4. Distribution Restriction
+
+      You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software.
+
+   5. Disclaimer of Warranty and Limitation of Liability
+
+      THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+   6. Language
+
+      THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL.
+
+   END OF THE TERMS AND CONDITIONS
+
+   How to Apply the Mulan Permissive Software License，Version 2 (Mulan PSL v2) to Your Software
+
+      To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps:
+
+      i Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner;
+
+      ii Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package;
+
+      iii Attach the statement to the appropriate annotated syntax at the beginning of each source file.
+
+
+   Copyright (c) 2024 LuChen Wang
+   choccy is licensed under Mulan PSL v2.
+   You can use this software according to the terms and conditions of the Mulan PSL v2.
+   You may obtain a copy of Mulan PSL v2 at:
+               http://license.coscl.org.cn/MulanPSL2
+   THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
+   See the Mulan PSL v2 for more details.

choccy-0.0.9/PKG-INFO

@@ -0,0 +1,452 @@
+Metadata-Version: 2.4
+Name: choccy
+Version: 0.0.9
+Summary: Chen's Heuristic Optimizer Constructed with Core numpY: 
+Author-email: LuChen Wang <wangluchen567@qq.com>
+License: MulanPSL-2.0
+Project-URL: Homepage, https://gitee.com/wang567/CHOCCY
+Project-URL: Issues, https://gitee.com/wang567/CHOCCY/issues
+Project-URL: Changelog, https://gitee.com/wang567/CHOCCY/releases
+Project-URL: Mirror (GitHub), https://github.com/wangluchen567/CHOCCY
+Project-URL: Mirror-Issues, https://github.com/wangluchen567/CHOCCY/issues
+Keywords: genetic-algorithm,evolutionary-algorithms,multi-objective-optimization,heuristic-algorithm,metaheuristic-algorithms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Mulan Permissive Software License v2 (MulanPSL-2.0)
+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
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: scipy>=1.8.0
+Requires-Dist: seaborn>=0.12
+Requires-Dist: tqdm>=4.65
+Requires-Dist: networkx>=3.0
+Requires-Dist: numba>=0.57.0; extra != "cpu-only" and extra != "no-numba"
+Requires-Dist: tbb>=2021.0; extra != "cpu-only" and extra != "no-tbb" and extra != "no-numba"
+Provides-Extra: cpu-only
+Provides-Extra: no-numba
+Provides-Extra: no-tbb
+Dynamic: license-file
+
+# 🍪 CHOCCY
+
+基于NumPy构建的启发式优化求解器<br>
+Chen's Heuristic Optimizer Constructed with Core numpY
+
+## 🔖 项目简介
+
+本项目是一个完全免费且开源的启发式优化求解器，致力于打造一个简单易用、绘图功能丰富、便于算法分析且扩展性强的优化框架。
+本项目提供了大量启发式/元启发式算法的实现细节，支持对`实数`、`整数`、`序列`、`(固定)标签`以及`混合`类型问题的优化，
+旨在为对优化领域感兴趣的伙伴们提供易于理解的算法学习资源和有力的研究支持💪。
+
+另外，本项目希望为学习、竞赛和科研等领域的伙伴提供高效易用的优化工具。
+无论是初学者还是资深研究者，都能借助它快速设计和优化问题，并获得满意结果。
+同时，不错的可视化功能可将结果转化为直观图表，方便用于论文撰写和报告制作，助力在学术与实践中取得优异成果🎉。
+
+本项目采用 **木兰宽松许可证第2版（Mulan PSL v2）** 开源，允许学习、竞赛、科研及**商业用途**在内的各种使用场景。
+
+> 📌 **使用说明**：使用本项目时，请保留原始版权声明，并在核心代码复用或引用时注明出处。
+
+## 🌟 主要特性
+
+- 🌍 支持多种`启发式`和`元启发式`优化算法，适用于广泛的问题类型求解
+- 🚀 支持对多种问题的优化，包括但不限于`实数`、`整数`、`序列`、`(固定)标签`问题
+- 🧩 支持对混合问题的优化，即问题的不同部分可以是不同类型的“混合”问题
+- 🛠️ 提供了丰富的性能评估指标和优化算子及函数，可扩展性强
+- 📉 支持对多种算法的实时优化比较，并提供丰富的可视化功能
+- 📊 支持多种算法对多类问题的优化和求解，并对结果进行比较和可视化
+- ⚡ 使用矩阵操作和`numba`的即时编译对核心部分进行优化，显著提高优化速度 
+
+## 🎯 实现算法
+
+- 🧬 遗传(进化)算法
+- 🔥 模拟退火算法
+- 🔗 差分进化算法
+- 🐜 蚁群优化算法
+- 🌟 粒子群优化算法
+- ⚖️ 多目标优化算法
+- 📉 梯度下降优化算法
+- 🔍 局部搜索相关算法
+- 🚚 路由优化相关算法
+- 📝 其他参见[实现清单](https://gitee.com/wang567/CHOCCY/blob/master/docs/IMPLES.md)
+
+## 📚 安装教程
+
+**详细的安装与使用教程请参见[使用指南](https://gitee.com/wang567/CHOCCY/blob/master/docs/GUIDE.md)** 🔥🔥🔥
+
+### 1. 使用 pip 安装（推荐）
+
+直接安装完整版本（包含 numba 加速）：
+
+```bash
+pip install choccy
+```
+
+如果遇到 numba 相关的报错，或希望安装无 numba 加速的版本：
+
+```bash
+pip install choccy[no-numba]
+```
+
+如果 tbb 加速不适配当前系统：
+
+```bash
+pip install choccy[no-tbb]
+```
+
+> 💡 **提示**：以上三种安装方式可根据实际情况选择其一。
+
+### 2. 从 whl 文件安装
+
+从 [Releases 页面](https://gitee.com/wang567/CHOCCY/releases) 下载对应版本的 `.whl` 文件，切换到文件所在目录后执行（以 0.1.0 版本为例）：
+
+```bash
+pip install choccy-0.1.0-py3-none-any.whl
+```
+
+### 3. 本地源码运行（适用于开发或调试）
+
+如果不希望安装，可以直接下载项目源码进行本地运行和测试。
+
+#### 3.1 使用 Conda 创建虚拟环境（推荐）
+
+建议使用 Anaconda 创建独立的 Python 环境，便于管理依赖包、避免版本冲突。
+
+- 从 [Anaconda 官网](https://www.anaconda.com/download/success) 下载并安装
+- 如需特定版本，可访问 [历史版本下载地址](https://repo.anaconda.com/archive/)
+
+创建并激活环境：
+
+```bash
+conda create --name choccy_env python=3.9
+conda activate choccy_env
+```
+
+> 📌 **注意**：本项目支持 Python 3.7 及以上版本，推荐使用 Python 3.9 以获得最佳兼容性。
+
+#### 3.2 安装必需依赖
+
+```bash
+pip install numpy scipy matplotlib seaborn tqdm networkx
+```
+
+#### 3.3 安装可选加速依赖（建议）
+
+为了获得更快的优化速度，建议安装 numba 和 tbb：
+
+```bash
+pip install numba tbb
+```
+
+#### 3.4 使用国内镜像源加速下载（可选）
+
+如果下载速度较慢，可尝试使用清华大学镜像源：
+
+```bash
+pip install numpy scipy matplotlib seaborn tqdm networkx numba tbb -i https://pypi.tuna.tsinghua.edu.cn/simple
+```
+
+## 📦 项目结构
+
+```
+CHOCCY/
+├── choccy/                          # 优化求解器核心库（pip 安装内容）
+│   ├── algorithms/                  # 算法模块
+│   │   ├── multi/                   # 多目标优化算法
+│   │   ├── single/                  # 单目标优化算法
+│   │   ├── algorithm.py             # 算法基类
+│   │   ├── comparator.py            # 单问题多算法比较器
+│   │   └── evaluator.py             # 多问题多算法评估器
+│   ├── problems/                    # 问题模块
+│   │   ├── multi/                   # 多目标优化问题
+│   │   ├── single/                  # 单目标优化问题
+│   │   └── problem.py               # 问题基类
+│   ├── solutions/                   # 解集模块
+│   │   └── solutions.py             # 解集基类
+│   ├── utilities/                   # 工具模块
+│   │   ├── commons/                 # 公共组件
+│   │   ├── handler/                 # 数据处理
+│   │   ├── logging/                 # 日志处理
+│   │   ├── metrics/                 # 性能指标计算
+│   │   ├── strategies/              # 策略函数集
+│   │   └── visualization/           # 可视化绘图
+│   ├── core.py                      # 核心接口
+│   └── types.py                     # 枚举类型定义
+│
+├── demos/                           # 演示程序（需克隆运行）
+├── docs/                            # 项目文档
+│   └── images/                      # 文档图片资源（动图/截图）
+├── examples/                        # 示例代码（需克隆运行）
+│   ├── multi/                       # 多目标优化示例
+│   ├── single/                      # 单目标优化示例
+│   ├── start.py                     # 快速开始示例
+│   └── vectorized.py                # 向量化计算示例
+├── tests/                           # 单元测试与集成测试
+│
+├── pyproject.toml                   # 项目配置（构建依赖、工具配置）
+└── README.md                        # 项目说明文档（用户入口）
+```
+
+> 📌 **目录说明**：
+> - `choccy/`：核心库，**会随 `pip install choccy` 一同安装**
+> - `examples/`、`demos/`、`tests/`：辅助资源，**仅存在于源码仓库中**（需 `git clone`）
+> - `docs/images/`：文档图片资源，用于 README 中的效果展示
+
+> 📚 **支持的算法与问题集**：完整的算法列表和测试问题清单，请参阅 [实现清单](https://gitee.com/wang567/CHOCCY/blob/master/docs/IMPLES.md)
+
+> **✨ PS: 项目中包含本人研究工作** <br>
+> Neural Network-Based Dimensionality Reduction for Large-Scale Binary Optimization with Millions of Variables (NNDREA), IEEE Transactions on Evolutionary Computation <br>
+> 原文下载地址：[IEEE xplore](https://ieeexplore.ieee.org/abstract/document/10530207) / [ResearchGate](https://www.researchgate.net/publication/380393707_Neural_Network-Based_Dimensionality_Reduction_for_Large-Scale_Binary_Optimization_with_Millions_of_Variables#:~:text=In%20this%20paper,%20we%20propose%20a%20dimensionality%20reduction%20method%20to) (免费下载)
+
+
+## 🚀 快速开始
+
+### 算法求解自定义问题
+
+#### 基础用法：单个计算
+
+对于简单的小规模问题，可以直接定义单个计算的目标函数：
+
+```python
+import numpy as np
+from choccy.algorithms.single import DE
+from choccy.problems import Problem, create_problem
+
+# 定义目标函数（接收单个解，返回目标值）
+def calc_sphere_obj(x):
+    return np.sum(x ** 2)
+
+# 创建问题实例
+problem = create_problem(
+    calc_obj=calc_sphere_obj,     # 目标函数（单个计算）
+    var_types=Problem.REAL,       # 决策变量类型：实数
+    n_vars=2,                     # 决策变量个数
+    n_objs=1,                     # 目标个数
+    l_bounds=-100,                # 变量下界
+    u_bounds=100                  # 变量上界
+)
+
+# 定义并初始化算法
+algorithm = DE(n_sols=50, max_iter=100, visual_mode='log')
+# 使用算法优化问题
+algorithm.optimize(problem)
+# 报告优化结果信息
+algorithm.report_result()
+```
+输出结果（日志部分已省略）：
+```
+[DE] Iter: 000/100 | Obj: 2.272870e+01 | Feas: 100.0 % | Time: 0.000 s
+[DE] Iter: 001/100 | Obj: 2.272870e+01 | Feas: 100.0 % | Time: 0.001 s
+...
+[DE] Iter: 099/100 | Obj: 1.295769e-20 | Feas: 100.0 % | Time: 0.033 s
+[DE] Iter: 100/100 | Obj: 1.295769e-20 | Feas: 100.0 % | Time: 0.033 s
+
+==================================================================
+OPTIMIZATION RESULT - DE
+==================================================================
+Iterations: 100
+Runtime: 0.032571 s
+Number of Bests: 1
+Best Objectives: 1.295769e-20
+Best Constraints: N/A
+Best Decision Variables:
+[1.02604155e-10 4.92958320e-11]
+==================================================================
+```
+
+#### 进阶用法：向量化计算（推荐）
+
+对于大规模或高维问题，建议使用向量化方式批量计算，能显著提升优化效率：
+
+```python
+import numpy as np
+from choccy.algorithms.single import DE
+from choccy.problems import Problem, create_problem
+
+# 定义目标函数（接收解矩阵，批量返回目标值向量）
+def calc_rastrigin_objs(xs):
+    # xs 形状为 (n_solutions, n_vars)
+    # 返回形状为 (n_solutions,) 或 (n_solutions, 1)
+    return np.sum(xs ** 2 - 10 * np.cos(2 * np.pi * xs) + 10, axis=1)
+
+# 创建问题实例
+problem = create_problem(
+    calc_objs_mat=calc_rastrigin_objs,   # 向量化目标函数（批量计算）
+    var_types=Problem.REAL,              # 决策变量类型：实数
+    n_vars=2,                            # 决策变量个数
+    n_objs=1,                            # 目标个数
+    l_bounds=-10,                        # 变量下界
+    u_bounds=10                          # 变量上界
+)
+# 定义并初始化算法
+algorithm = DE(n_sols=50, max_iter=100, visual_mode='log')
+# 使用算法优化问题
+algorithm.optimize(problem)
+# 报告优化结果信息
+algorithm.report_result()
+```
+输出结果（日志部分已省略）：
+```
+[DE] Iter: 000/100 | Obj: 1.729376e+01 | Feas: 100.0 % | Time: 0.000 s
+[DE] Iter: 001/100 | Obj: 1.354248e+01 | Feas: 100.0 % | Time: 0.001 s
+...
+[DE] Iter: 099/100 | Obj: 0.000000e+00 | Feas: 100.0 % | Time: 0.015 s
+[DE] Iter: 100/100 | Obj: 0.000000e+00 | Feas: 100.0 % | Time: 0.015 s
+
+==================================================================
+OPTIMIZATION RESULT - DE
+==================================================================
+Iterations: 100
+Runtime: 0.015571 s
+Number of Bests: 1
+Best Objectives: 0.000000e+00
+Best Constraints: N/A
+Best Decision Variables:
+[-4.32080858e-10  1.10147149e-09]
+==================================================================
+```
+> 💡 性能提示：对比两种方式的运行时间（0.033s vs 0.016s），向量化版本的性能优势明显。在处理大规模种群或高维问题时，推荐优先使用 calc_objs_mat 接口。
+
+> 🎨 可视化提示：如需在优化过程中实时绘制动态图像，也推荐使用 calc_objs_mat 接口，可获得更流畅的视觉效果。
+
+#### 可视化示例
+
+> 💡 **提示**：如果下方的动图无法正常显示，请点击 [此处](https://gitee.com/wang567/CHOCCY) 前往 Gitee 查看完整 README（动图可正常显示）。
+
+以下为使用向量化计算时的优化过程动图（不同参数组合）：
+
+- 左图：`n_vars=2`, `visual_mode='obj'`
+- 右图：`n_vars=1`, `visual_mode='h2d'`
+
+<img src="./docs/images/obj.gif" width="288" height="220"/>
+<img src="./docs/images/h2d1.gif" width="288" height="220"/>
+
+- 左图：`n_vars=2`, `visual_mode='h2d'`
+- 右图：`n_vars=2`, `visual_mode='h3d'`
+
+<img src="./docs/images/h2d.gif" width="288" height="220"/>
+<img src="./docs/images/h3d.gif" width="288" height="220"/>
+
+📌 **`visual_mode` 参数说明**：
+
+| 参数      | 含义          | 备注                              |
+|---------|-------------|---------------------------------|
+| `'obj'` | 目标空间绘制      | 单目标：收敛曲线；多目标：目标空间               |
+| `'h2d'` | 决策+目标空间混合绘制 | `n_vars=1`：二维曲线；`n_vars=2`：等高线图 |
+| `'h3d'` | 决策+目标空间混合绘制 | 三维曲面图，**要求 `n_vars=2`**         |
+
+
+## 🌈 效果展示
+
+### 单目标问题优化
+
+> 📌 **说明**：以下动图和图片展示的是项目示例的运行效果。示例代码位于 GitHub 仓库的 `examples/` 目录中，**不会随 `pip install choccy` 一同安装**。如需本地运行，请先克隆项目源码。
+
+### 单目标问题优化
+
+#### 特殊类型问题优化
+
+| 问题类型       | 对应脚本                                                    |
+|:-----------|:--------------------------------------------------------|
+| TSP（旅行商问题） | `examples/single/optimize/optimize_TSP.py`              |
+| 固定标签聚类问题   | `examples/single/optimize/optimize_FixedSizeCluster.py` |
+
+<img src="./docs/images/tsp.gif" width="288" height="230"/>
+<img src="./docs/images/cluster.gif" width="288" height="230"/>
+
+#### 多种算法实时对比（相同问题）
+
+| 问题类型            | 对应脚本                                        |
+|:----------------|:--------------------------------------------|
+| 实数问题（Ackley 函数） | `examples/single/compare/compare_Ackley.py` |
+| TSP 问题          | `examples/single/compare/compare_TSP.py`    |
+
+<img src="./docs/images/compare_ackley.gif" width="288" height="230"/>
+<img src="./docs/images/compare_tsp.gif" width="288" height="230"/>
+
+
+#### 多种算法结果对比（静态分析）
+
+| 图表类型 | 说明 |
+|:--------|:--------|
+| 小提琴图 | 展示目标值分布形态 |
+| 核密度估计图 | 展示目标值概率密度 |
+
+**对应脚本**：`examples/single/evaluate/evaluate_Ackley.py`
+
+<img src="./docs/images/violin.png" width="288" height="230"/>
+<img src="./docs/images/kde.png" width="288" height="230"/>
+
+> 📌 **注**：为了更清晰地展示对比效果，以上静态图中的迭代次数已缩减为 100 次。
+
+### 多目标问题优化
+
+#### 基准测试问题优化
+
+| 测试问题  | 说明                 | 对应脚本                                       |
+|:------|:-------------------|:-------------------------------------------|
+| ZDT3  | 双目标优化问题，具有不连续帕累托前沿 | `examples/multi/optimize/optimize_ZDT.py`  |
+| DTLZ2 | 多目标优化问题，具有凹球面形帕累托前沿  | `examples/multi/optimize/optimize_DTLZ.py` |
+
+
+<img src="./docs/images/zdt3.gif" width="288" height="230"/>
+<img src="./docs/images/dtlz2.gif" width="288" height="230"/>
+
+#### 多种算法实时对比（多目标背包问题）
+
+对比不同算法在 MOKP（多目标背包问题，1000 维）上的优化表现：
+
+**对应脚本**：`examples/multi/compare/compare_MOKP.py`
+
+<img src="./docs/images/compare_mokp.gif" width="288" height="230"/>
+<img src="./docs/images/mokp_hv.png" width="288" height="230"/>
+
+> 📌 **说明**：右侧图片展示的是 HV（Hypervolume，超体积）指标对比，用于衡量多目标算法的收敛性和多样性。
+
+### 更多示例
+
+完整的示例代码请参阅 Gitee/GitHub 仓库的 [examples/](https://gitee.com/wang567/CHOCCY/tree/master/examples) 目录。
+
+
+## 📄 数据集优化结果展示
+
+### TSP 数据集优化结果
+
+考虑到部分用户会使用本项目求解旅行商问题（TSP），以下给出 TSPLIB 数据集中部分中小规模实例的优化结果。
+
+| Instance | BKS   | GA    | SA    | ACO   | HGA-TSP | FI    | LS    | GFLS  | Gap(%) |
+|----------|-------|-------|-------|-------|---------|-------|-------|-------|--------|
+| gr17     | 2085  | 2085  | 2088  | 2085  | 2085    | 2096  | 2088  | 2085  | 0.00   |
+| gr24     | 1272  | 1272  | 1279  | 1272  | 1272    | 1361  | 1272  | 1272  | 0.00   |
+| eil51    | 426   | 429   | 443   | 438   | 432     | 451   | 458   | 426   | 0.00   |
+| eil76    | 538   | 594   | 583   | 565   | 562     | 607   | 600   | 538   | 0.00   |
+| berlin52 | 7542  | 7918  | 8034  | 7547  | 7542    | 8118  | 8368  | 7542  | 0.00   |
+| KroA100  | 21282 | 26063 | 22238 | 22455 | 21472   | 23373 | 23417 | 21282 | 0.00   |
+| KroB100  | 22141 | 26571 | 24078 | 23377 | 22391   | 23958 | 24474 | 22157 | 0.07   |
+| KroC100  | 20749 | 25934 | 21991 | 21597 | 22080   | 21817 | 22671 | 20749 | 0.00   |
+
+#### 实验设置
+
+- **种群大小**：`pop_size = 100`
+- **迭代次数**：`max_iter = 1000`（保证算法充分收敛）
+- **结果取值**：每次优化取多次运行中的**最小值**（由于随机初始化，结果可能略有波动）
+
+> 📌 **补充说明**：上表中 Gap (%) 列展示的是 **GFLS 算法**与 BKS（当前已知的最优解） 的差距。从结果可以看出，GFLS 在多个实例上均能达到或接近已知最优解。
+
+## 🤝 项目贡献
+
+**Maintainer: Luchen Wang**<br>
+
+## ✉️ 联系我们
+
+**邮箱: wangluchen567@qq.com**
+
+