<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./assets/evox_brand_dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="./assets/evox_brand_dark.svg">
    <img alt="EvoX Logo" height="128" width="500px" src="./assets/evox_brand_dark.svg">
  </picture>
</h1>

---

<h2 align="center">
  <p>🌟 AutoPSO: A Meta-Framework for Automated Particle Swarm Optimization 🌟</p>
  <a href="https://ieeexplore.ieee.org/document/11638110">
    <img src="https://img.shields.io/badge/PAPER-333333?style=for-the-badge" alt="AutoPSO Paper">
  </a>
  <a href="https://github.com/EMI-Group/AutoPSO">
    <img src="https://img.shields.io/badge/ARXIV-E94242?style=for-the-badge" alt="AutoPSO on arXiv">
  </a>
</h2>

---

<p align="center">
  <img src="https://img.shields.io/badge/backend-PyTorch-EE4C2C?style=for-the-badge" alt="PyTorch backend">
  <img src="https://img.shields.io/badge/platform-EvoX-6f42c1?style=for-the-badge" alt="EvoX platform">
  <img src="https://img.shields.io/badge/benchmark-CEC2022-green?style=for-the-badge" alt="CEC2022 benchmark">
</p>

AutoPSO is an online framework for automatically constructing PSO variants.
Traditional PSO research has produced many useful mechanisms, such as different
parameter schedules, exemplar choices, and swarm topologies. In practice, however,
turning those mechanisms into a strong optimizer often still depends on manual
trial-and-error: a researcher selects components, tunes coefficients, runs a
benchmark, then repeats the process for the next problem.

AutoPSO turns this hand-crafted design loop into a black-box optimization
problem. An outer PSO searches over a compact configuration space of PSO
components, while many inner generalized PSO solvers are instantiated in parallel
to solve the target problem and report feedback. With EvoX and PyTorch, those inner
runs are tensorized and mapped naturally to modern GPUs, making it practical to
adapt PSO designs online under a fixed wall-clock budget.

<p align="center">
  <img src="./assets/autopso_dynamic_modules.gif" alt="AutoPSO dynamically maps adaptive PSO modules to an exemplar pool" width="92%">
</p>

## Method

<p align="center">
  <img src="./assets/framework.png" alt="AutoPSO framework" width="92%">
</p>

Each outer particle encodes one candidate PSO variant:

- `weight`: the inertia coefficient shared by two update policies.
- `k1, k2, k3, k4`: acceleration coefficients for the two policies.
- `type1, type2, type3, type4`: exemplar choices selected from a nine-candidate pool.
- `percent`: the population split ratio for two sub-swarms.

The inner solver is a generalized PSO. At every step, it partitions the swarm into
two groups, assigns each group a different update policy, and selects exemplars
from a shared pool including current position, personal best, global best,
population center, random individuals, random personal bests, random elites, and
newly sampled candidates.

## Main Result

<p align="center">
  <img src="./assets/cec2022_20d_convergence.png" alt="CEC2022 20D convergence curves" width="88%">
</p>

The paper evaluates AutoPSO against six classical PSO variants on CEC2022 under
equal wall-clock time. For 20D functions, each run is limited to 120 seconds and
reported curves are averaged over 31 independent runs. The main CEC2022 setting
implemented in this repository uses:

```text
outer optimizer: PSO
outer population: 100
inner optimizer: AutoPSO / generalized PSO
inner population: 100
inner iterations per outer evaluation: 800
time budget: 60s for CEC2022 10D, 120s for CEC2022 20D
```

> Reproduction note: the paper reports wall-clock experiments on an RTX 3090 GPU.
> If PyTorch is running on CPU, the same 120-second budget will perform far fewer
> outer iterations and the results may be noticeably worse. Check your backend
> with `python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"`.

## Repository Layout

```text
assets/                         Logos and paper figures used by the README
examples/pytorch/example_cec2022.py  PyTorch CEC2022 example entry point
scripts/summarize_json_results.py Result summarizer for JSON outputs
src/autopso/                     AutoPSO package source
show_env.py                      Environment and dependency checker
```

## Installation

Create or activate an environment with PyTorch and EvoX. For CPU-only smoke tests:

```bash
pip install -e ".[pytorch]"
```

For GPU examples, install the CUDA-enabled PyTorch build that matches your CUDA
driver, then install EvoX. A typical setup is:

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip install -U "evox[default]"
pip install -e ".[pytorch]"
```

Verify the environment:

```bash
python show_env.py
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
```

## Quick Start

Run the CEC2022 test:

```bash
python examples/pytorch/example_cec2022.py \
  --dims 20 \
  --functions 1 2 3 4 5 6 7 8 9 10 11 12 \
  --runs 31 \
  --max-time 120 \
  --device cuda \
  --output outputs/cec2022_20d_31runs_pytorch
```

Summarize results:

```bash
python scripts/summarize_json_results.py outputs/cec2022_20d_31runs_pytorch/autopso_cec2022_20D.json
```

The runner prints progress during each run. Use `--progress-interval 1` for more
frequent updates, or `--progress-interval 0` to disable progress output.

The PyTorch runner uses the AutoPSO encoding and CEC2022 data packaged in this
repository. Its CEC2022 problem class follows the EvoX PyTorch `Problem` style
when `evox.core` is available, with a fallback for older EvoX installs.

## Citation

If you use this code, please cite the corresponding paper:

```bibtex
@article{yu2026autopso,
  title   = {AutoPSO: A Meta-Framework for Automated Particle Swarm Optimization},
  author  = {Yu, Xinmeng and Gao, Jiaxin and Zhang, Jianguo and Jiang, Dongmei and Cheng, Ran},
  journal = {IEEE Transactions on Evolutionary Computation},
  year    = {2026},
  doi     = {10.1109/TEVC.2026.3718908}
}
```

## Acknowledgements

AutoPSO is implemented with the EvoX framework for vectorized evolutionary
computation and hardware acceleration.
