Metadata-Version: 2.4
Name: swarmtorch
Version: 0.3.0
Summary: Professional PyTorch library for 120+ metaheuristic optimization algorithms (Swarm, Evolutionary, Physics, Hybrid).
Author-email: Halleluyah Darasimi Oludele <hallelx2@gmail.com>
Keywords: pytorch,metaheuristics,swarm-intelligence,evolutionary-algorithms,hpo,gradient-free
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy>=1.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pyright>=1.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Provides-Extra: benchmark
Requires-Dist: pandas>=1.3.0; extra == "benchmark"
Requires-Dist: matplotlib>=3.5.0; extra == "benchmark"
Requires-Dist: scipy>=1.10.0; extra == "benchmark"
Requires-Dist: optuna>=3.0; extra == "benchmark"
Requires-Dist: cma>=3.3.0; extra == "benchmark"
Requires-Dist: scikit-learn>=1.2.0; extra == "benchmark"
Requires-Dist: nevergrad>=1.0.0; extra == "benchmark"
Provides-Extra: benchmarks
Requires-Dist: pandas>=1.3.0; extra == "benchmarks"
Requires-Dist: matplotlib>=3.5.0; extra == "benchmarks"
Requires-Dist: scipy>=1.10.0; extra == "benchmarks"
Requires-Dist: optuna>=3.0; extra == "benchmarks"
Requires-Dist: cma>=3.3.0; extra == "benchmarks"
Provides-Extra: cmaes
Requires-Dist: cma>=3.3.0; extra == "cmaes"
Provides-Extra: baselines
Requires-Dist: optuna>=3.0; extra == "baselines"
Provides-Extra: torchvision
Requires-Dist: torchvision>=0.15.0; extra == "torchvision"
Provides-Extra: xgboost
Requires-Dist: xgboost>=1.7.0; extra == "xgboost"
Provides-Extra: all
Requires-Dist: pandas>=1.3.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: scipy>=1.10.0; extra == "all"
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: ruff>=0.1.0; extra == "all"
Requires-Dist: pyright>=1.1.0; extra == "all"
Requires-Dist: build>=1.0.0; extra == "all"
Requires-Dist: cma>=3.3.0; extra == "all"
Requires-Dist: optuna>=3.0; extra == "all"
Requires-Dist: torchvision>=0.15.0; extra == "all"
Requires-Dist: xgboost>=1.7.0; extra == "all"
Dynamic: license-file

# SwarmTorch 🐝🔥
**A PyTorch Library for Metaheuristic Optimization in Deep Learning**

[![arXiv](https://img.shields.io/badge/arXiv-2503.XXXXX-red)](https://arxiv.org/abs/XXXXX)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-green.svg)](https://pytorch.org/)

---

## 📄 About

SwarmTorch is a comprehensive PyTorch library that brings **120 metaheuristic optimization algorithms** to the deep learning ecosystem. It provides a unified API for:

- **60 model-training optimizers** — gradient-free weight optimization for neural networks
- **60 hyperparameter searchers** — intelligent hyperparameter optimization (HPO)

Published on arXiv: **[arXiv:2503.XXXXX](https://arxiv.org/abs/XXXXX)**

---

## 🚀 Key Features

- **120 Algorithms Across 6 Families**: Swarm Intelligence, Evolutionary, Physics-based, Human-based, Bio-inspired, and Hybrid methods
- **Native PyTorch Integration**: Drop-in replacement for `torch.optim.Optimizer`
- **GPU-Accelerated**: Full tensor parallelism using PyTorch's CUDA support
- **Research-Grade Benchmarks**: Comprehensive evaluation across 60 training algorithms and 60 HPO searchers with reproducible results

---

## 📊 Key Research Findings

Our empirical evaluation on standard benchmarks demonstrates:

- **63.3%** of SwarmTorch's hyperparameter searchers outperform Random Search baseline
- Metaheuristics achieve significantly lower loss on multimodal (non-convex) test functions where gradient-based methods fail
- Up to **17.4×** GPU speedup for models with >50K parameters

See our [paper](paper/swarmtorch_paper.pdf) for detailed results.

---

## 📦 Installation

```bash
pip install swarmtorch
```

**With development dependencies:**

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

---

## 💻 Usage Examples

### Model Weight Optimization

```python
import torch.nn as nn
from swarmtorch import PSO

# Define model
model = nn.Sequential(
    nn.Linear(10, 64),
    nn.ReLU(),
    nn.Linear(64, 1)
)

# Use PSO as optimizer
optimizer = PSO(model.parameters(), swarm_size=30)

# Training loop
for epoch in range(100):
    def closure():
        optimizer.zero_grad()
        output = model(inputs)
        loss = criterion(output, targets)
        loss.backward()
        return loss
    
    optimizer.step(closure)
```

### Hyperparameter Optimization

```python
from swarmtorch import PSOSearch

# Define search space
searcher = PSOSearch(
    model_fn=build_model,
    param_space={
        'lr': (0.001, 0.1),
        'hidden_dim': [32, 64, 128],
        'batch_size': [16, 32, 64]
    },
    train_fn=train_fn,
    iterations=50,
    swarm_size=20
)

# Run optimization
best_params = searcher.search()
```

---

## 📂 Repository Structure

```
swarmtorch/
├── swarmtorch/          # Main library
│   ├── swarm/          # Swarm Intelligence algorithms
│   ├── evolutionary/   # Evolutionary algorithms
│   ├── physics/       # Physics-based algorithms
│   ├── bio_inspired/  # Bio-inspired algorithms
│   ├── human_based/  # Human-based algorithms
│   └── hybrid/        # Hybrid algorithms
├── benchmarks/         # Experimental benchmarks
├── paper/             # Research paper & figures
└── README.md
```

---

## 📚 Benchmark Results

Detailed experimental results are available in:
- **[COMPREHENSIVE_EXPERIMENT_REPORT.md](benchmarks/COMPREHENSIVE_EXPERIMENT_REPORT.md)**
- **[BENCHMARKS.md](benchmarks/BENCHMARKS.md)**

### Top Performing HPO Searchers

| Rank | Algorithm | Best Accuracy |
|------|-----------|---------------|
| 1 | SA Search | 98.5% |
| 2 | DVBA Search | 98.5% |
| 3 | PBIL Search | 98.0% |
| 4 | AFSA Search | 98.0% |
| 5 | JSO Search | 98.0% |

### Top Performing Training Optimizers

| Rank | Algorithm | Final Loss |
|------|-----------|------------|
| 1 | Adam (baseline) | 0.033 |
| 2 | CA | 0.132 |
| 3 | HHO | 0.167 |
| 4 | CEM | 0.199 |
| 5 | PFA | 0.239 |

---

## 🔧 Hardware & Reproducibility

All benchmarks were run on:
- **GPU**: NVIDIA T4x2 (Kaggle)
- **CPU**: Intel Core i7-12700K (workstation)
- **Software**: PyTorch 2.9.0+cu126, Python 3.11, NumPy 1.26

Random seeds fixed at 42 for reproducibility.

---

## 📝 Citation

If you use SwarmTorch in your research, please cite:

```bibtex
@article{swarmtorch2026,
  author  = {Halleluyah Darasimi Oludele},
  title   = {SwarmTorch: A PyTorch Library for 120 Metaheuristic Optimization Algorithms in Deep Learning},
  journal = {arXiv preprint arXiv:2503.XXXXX},
  year    = {2026}
}
```

---

## 📄 License

MIT License - See [LICENSE](LICENSE) for details.

---

## 🤝 Acknowledgments

Inspired by [pyMetaheuristic](https://github.com/mariosv/pyMetaheuristic) and the broader metaheuristic optimization community.
