Skip to content

Commit c91e0e3

Browse files
yangyongkang2000yangyongkang2000
committed
Improvement
1 parent 1131a4a commit c91e0e3

File tree

125 files changed

+11136
-92
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

125 files changed

+11136
-92
lines changed

‎README.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,8 @@ The SEvoBench framework brings the following highlights:
1616
### Future Work
1717
SEvoBench is still under development, and some features and functionalities of it need improvement.
1818

19-
### Documentation
20-
21-
> [!NOTE]
22-
> The full documentation is under development.
23-
24-
19+
### Documentations
20+
[User Guide](./doc/User_Guide.md)
2521
### Cite this repository
2622
If you use this software in your work, please cite it as below.
2723

‎doc/User_Guide.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# SEvoBench User Guide
2+
- [Introduction](#introduction)
3+
- [About SEvoBench](#about-sevobench)
4+
- [Installation](#installation)
5+
- [System Requirements](#system-requirements)
6+
- [Building the Project](#building-the-project)
7+
- [CMake](#using-cmake-for-package-management-in-sevobench)
8+
## Introduction
9+
### [About SEvoBench](#sevobench-user-guide)
10+
 SEvoBench is a single-objective optimization algorithm testing framework written in C++. Its purpose is to facilitate single-objective evolutionary algorithm researchers to quickly and effectively test the optimization performance of algorithms. For this reason, the framework not only provides users with a series of interfaces for optimization algorithms and optimization problems, but also incorporates a certain number of state-of-the-art optimization algorithms and test sets.
11+
12+
### [Installation](#sevobench-user-guide)
13+
 Simply download the source code from GitHub to your personal working directory. The computational kernel of SEvoBench is located in the *SEvoBench/inlcude/SEvoBench* folder, which contains all the necessary header files.
14+
15+
#### [System Requirements](#sevobench-user-guide)
16+
Compiler: Support for compilers with C++20 or above
17+
18+
#### [Building the Project](#sevobench-user-guide)
19+
 As SEvoBench is implemented using C++ template programming, it does not need to be pre-compiled into a library. Simply include the project's header files and specify the project's header file search path.
20+
21+
#### [Using CMake for Package Management in SEvoBench](#sevobench-user-guide)
22+
 SEvoBench supports package management using CMake.
23+
24+
 `cmake_minimum_required(VERSION 3.15)`
25+
26+
```shell
27+
cmake -B build -S . -DBUILD_TESTS=OFF -DBUILD_EXAMPLE=OFF -DCMAKE_INSTALL_PREFIX=/* user-specified directory */
28+
cd build && cmake --build . && cmake --install .
29+
```
30+
31+
+ [Compilation Options](#sevobench-user-guide)
32+
33+
 For GCC and Clang compilers, it is recommended to use the following compilation command:
34+
```shell
35+
-O3 -ffast-math -march=native -std=c++20 -lpthread
36+
```
37+
 For MSVC compiler, it is recommended to use the following compilation command:
38+
```shell
39+
/std:c++20 /O2 /fp:fast /arch:AVX2 /F 8388608
40+
```
41+
+ [Using CMake](#sevobench-user-guide)
42+
43+
```shell
44+
cmake_minimum_required(VERSION 3.15)
45+
project(quickstart LANGUAGES CXX)
46+
set(EXE quickstart)
47+
add_executable(${EXE} quickstart.cpp)
48+
find_package(SEvoBench REQUIRED)
49+
set_target_properties(${EXE} PROPERTIES
50+
CXX_STANDARD 20
51+
CXX_STANDARD_REQUIRED ON)
52+
target_link_libraries(${EXE} PUBLIC SEvoBench::SEvoBench)
53+
set(CMAKE_BUILD_TYPE Release)
54+
set(CMAKE_CONFIGURATION_TYPES Release)
55+
target_compile_options(${EXE} PRIVATE
56+
$<$<CXX_COMPILER_ID:MSVC>:/fp:fast /arch:AVX2 /F 8388608>
57+
$<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-ffast-math -march=native -Wall -Wextra>
58+
)
59+
target_link_libraries(${EXE} PRIVATE
60+
$<$<CXX_COMPILER_ID:GNU>:pthread>
61+
)
62+
```
63+
## Note on Version Migration and Namespace Changes
64+
65+
SEvoBench has undergone significant architectural revisions across its two major versions. In the first version, all built-in algorithm functions were organized under the namespace sevobench::other_algorithm. For users transitioning from the legacy version, please note the following:
66+
67+
### Backward Compatibility Reference:
68+
The original implementation details remain accessible in the first version's documentation [other_algorithm.md](./other_algorithm.md).
69+
This document serves as a historical reference but should be used with awareness of the updated namespace structure.
70+
### Action Required for Migration:
71+
Code referencing these algorithms must be updated to reflect the new namespace conventions in Version 2.
72+
The revised architecture aims to improve modularity and maintainability, though it introduces breaking changes.
73+
### Recommendation for New Development:
74+
New implementations should adhere to the current version's namespace design.
75+
Cross-check with the latest API documentation to ensure compatibility.
76+
77+
## Documentation Generation with Large Language Models**
78+
79+
The first version of SEvoBench required manual documentation writing, which imposed a significant workload for individual developers.
80+
To address this challenge, the second major version has adopted large language models (LLMs) for comprehensive documentation generation.
81+
82+
The "./llm_code_input" directory contains all module codes provided to LLMs as input for documentation generation. These files are also made publicly available to serve as references for those who wish to use LLMs with SEvoBench data. Specifically:
83+
84+
1. [cec2017.md](./cec2017.md) and [problem.md](./problem.md) were generated using [llm_cec2017.txt](./llm_code_input/llm_cec2017.txt)
85+
2. [de_module.md](./de_module.md) was produced from [llm_de.txt](./llm_code_input/llm_de.txt)
86+
3. [pso_module.md](./pso_module.md) was created based on [llm_pso.txt](./llm_code_input/llm_pso.txt)
87+
4. [experiment.md](./experiment.md) was generated using [llm_experiment.txt](./llm_code_input/llm_experiment.txt)
88+
89+
Important Notes:
90+
- The LLM-generated documentation is provided for reference only
91+
- We cannot guarantee the absolute accuracy of these documents
92+
- Users are encouraged to refer to the original code in "./doc/llm_code_input" when using LLMs to generate their own documentation
93+
- The provided input files may serve as useful templates for similar documentation tasks
94+
95+
This approach significantly reduces documentation workload while maintaining reasonable quality, though manual verification remains recommended for critical applications.
96+

‎doc/cec2017.md

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# SEvoBench CEC2017 Problem Suite Documentation
2+
3+
The `sevobench::problem` module provides a comprehensive implementation of the CEC2017 benchmark suite for single-objective real-parameter optimization. This document outlines its architecture, problem types, and usage patterns.
4+
5+
---
6+
7+
## 1. Overview
8+
The CEC2017 module implements:
9+
- **30 Test Functions**: 3 categories of optimization problems
10+
- *Unimodal/Simple Multimodal* (F1-F3)
11+
- *Hybrid Functions* (F11-F20)
12+
- *Composition Functions* (F21-F30)
13+
- **Problem Infrastructure**:
14+
- Shifted/rotated problem variants
15+
- Hybrid function constructions
16+
- Composition function mechanisms
17+
- **Instance Management**:
18+
- Official instances with data loading
19+
- Random instance generation
20+
21+
---
22+
23+
## 2. Core Components
24+
25+
### 2.1 Problem Types (`cec_problem.hpp`)
26+
| Category | Problem IDs | Characteristics |
27+
|--------------------|-------------|---------------------------------|
28+
| Basic Functions | F1-F10 | Core optimization landscapes |
29+
| Hybrid Functions | F11-F20 | Combined function structures |
30+
| Composition Funcs | F21-F30 | Adaptive function combinations |
31+
32+
### 2.2 Problem Transformations
33+
| Transformation | Description | Affected Problems |
34+
|--------------------|-------------------------------|-------------------------|
35+
| Shift | Offset search space | All problems |
36+
| Rotation | Coordinate system rotation | F4-F30 |
37+
| Shuffle | Dimension permutation | Hybrid/Composition funcs|
38+
| Bias | Fitness offset | All problems |
39+
40+
---
41+
42+
## 3. Problem Configuration
43+
44+
### 3.1 Problem Class Template
45+
```cpp
46+
template<int Index, int Dim, std::floating_point T>
47+
class cec2017 : public cec_common<Index, Dim, T, cec2017> {
48+
// Problem-specific evaluation logic
49+
};
50+
```
51+
52+
### 3.2 Suite Builder Pattern
53+
```cpp
54+
auto suite = problem::suite_builder<problem::cec2017>()
55+
.dim<30>() // 30D problem
56+
.type<double>() // Double precision
57+
.problem_index({1,4,7}) // Select F1, F4, F7
58+
.instance_count(5) // Generate 5 random instances
59+
.build();
60+
```
61+
62+
---
63+
64+
## 4. Key Features
65+
66+
### 4.1 Basic Functions (F1-F10)
67+
| ID | Name | Formula |
68+
|----|----------------------|----------------------------------|
69+
| F1 | Bent Cigar | `f(x) = x₁² + 10⁶Σx_i²` |
70+
| F4 | Rosenbrock | `f(x) = Σ[100(x_i² - x_{i+1})² + (x_i -1)²]` |
71+
| F7 | Bi-Rastrigin | `f(x) = Σ[z_i² - 10cos(2πz_i) + 10]` |
72+
73+
### 4.2 Hybrid Functions (F11-F20)
74+
**Construction Pattern:**
75+
```math
76+
f_{\text{hybrid}}(x) = \sum_{k=1}^K w_k \cdot f_k(z^{(k)})
77+
```
78+
Where subcomponents:
79+
- Use different base functions
80+
- Operate on rotated/shuffled subspaces
81+
- Combine through dynamic weighting
82+
83+
### 4.3 Composition Functions (F21-F30)
84+
**Adaptive Mechanism:**
85+
```math
86+
f_{\text{comp}}(x) = \frac{\sum_{i=1}^m w_i [λ_i f_i(z^{(i)}) + bias_i]}{\sum_{i=1}^m w_i}
87+
```
88+
With:
89+
- Automatic subfunction selection
90+
- Adaptive σ parameters
91+
- Rotated/shuffled coordinates
92+
93+
---
94+
95+
## 5. API Reference
96+
97+
### 5.1 Core Classes
98+
| Class | Responsibilities |
99+
|-------------------------|----------------------------------|
100+
| `cec_common` | Base problem infrastructure |
101+
| `suite` | Problem collection manager |
102+
| `single_problem` | Interface for individual functions |
103+
104+
### 5.2 Key Methods
105+
| Method | Description |
106+
|---------------------------------|--------------------------------------|
107+
| `operator()` | Evaluate solution fitness |
108+
| `problem_information()` | Get bounds/optimum data |
109+
| `load_rotate_matrix()` | Load official rotation matrices |
110+
| `generate_problem_factory()` | Create problem instances |
111+
112+
---
113+
114+
## 6. Usage Example
115+
116+
```cpp
117+
#include "SEvoBench/sevobench.hpp"
118+
119+
int main() {
120+
using namespace sevobench::problem;
121+
122+
// Create CEC2017 suite with F15 in 10D
123+
auto suite = suite_builder<cec2017>()
124+
.dim<10>()
125+
.type<float>()
126+
.problem_index({15})
127+
.instance_count(3)
128+
.build();
129+
130+
// Evaluate solution
131+
std::vector<float> x(10, 0.5f);
132+
for(auto& prob : suite) {
133+
auto fitness = prob(x);
134+
std::cout << "F15 Instance " << prob.instance()
135+
<< " fitness: " << fitness << "\n";
136+
}
137+
}
138+
```
139+
140+
---
141+
142+
## 7. Advanced Functionality
143+
144+
### 7.1 Data Loading System
145+
**Official Instance Setup:**
146+
```cpp
147+
// Load official F17 data files
148+
cec2017<17, 30, double> official_prob("CEC2017_data/");
149+
```
150+
151+
**File Structure:**
152+
```
153+
CEC2017_data/
154+
├── shift_data_17.txt
155+
├── M_17_D30.txt
156+
└── shuffle_data_17_D30.txt
157+
```
158+
159+
### 7.2 Random Instance Generation
160+
**Automatic Configuration:**
161+
```cpp
162+
// Generate random F24 instance
163+
cec2017<24, 50, float> random_prob(5); // Instance ID=5
164+
```
165+
166+
**Generation Logic:**
167+
1. Random shift vectors in [-100, 100]
168+
2. Random orthogonal rotation matrices
169+
3. Random dimension permutations
170+
171+
---
172+
173+
## 8. Benchmarking Considerations
174+
175+
### 8.1 Evaluation Protocol
176+
1. Initialize population within [-100, 100]^D
177+
2. Use problem's `optimum_solution()` for error calculation:
178+
```math
179+
\text{Error} = f(x) - f(x^*)
180+
```
181+
3. Track function evaluations (FES)
182+
183+
### 8.2 Performance Tips
184+
- **Precision**: Use `double` for official result comparisons
185+
- **Vectorization**: Leverage SIMD for rotated coordinate calculations
186+
- **Memory**: Cache rotation matrices for hybrid/composition functions
187+
188+
---
189+
190+
## 9. Contribution Guidelines
191+
1. Implement new problems via `cec_common` CRTP pattern
192+
2. Follow official problem specifications exactly
193+
3. Include data file parsing logic
194+
4. Maintain separate evaluation paths for:
195+
- Basic functions
196+
- Hybrid constructions
197+
- Composition mechanisms
198+
5. Support both pre-generated and random instances
199+
6. Validate against official MATLAB implementations

0 commit comments

Comments
 (0)