Metadata-Version: 2.4
Name: mspo
Version: 0.1.0
Summary: Multi-Strategy Parrot Optimizer for hyperparameter tuning
Project-URL: Homepage, https://github.com/vijaygovindaraja/mspo
Project-URL: Issues, https://github.com/vijaygovindaraja/mspo/issues
Author-email: Vijay Govindarajan <vijay.govindarajan91@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Vijay Govindarajan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: hyperparameter-tuning,metaheuristic,optimization,parrot-optimizer,swarm-intelligence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.11
Provides-Extra: benchmark
Requires-Dist: opfunu>=1.0; extra == 'benchmark'
Requires-Dist: setuptools<82; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# mspo

Multi-Strategy Parrot Optimizer — a population-based metaheuristic for hyperparameter tuning and continuous black-box optimization.

This is a reference implementation of the algorithm described in:

> Govindarajan, V. (2025). MSPO: A machine learning hyperparameter optimization method for enhanced breast cancer image classification. *Digital Health*.

## Install

```bash
git clone https://github.com/vijaygovindaraja/mspo.git
cd mspo
pip install -e .
```

Requires Python 3.10+, NumPy, SciPy.

## Quick start

```python
import numpy as np
from mspo import MSPO

def sphere(x):
    return float(np.sum(x ** 2))

opt = MSPO(
    objective=sphere,
    bounds=[(-100, 100)] * 10,
    n_parrots=30,
    max_iter=1000,
    seed=42,
)
result = opt.run()

print(result.best_value)        # ~1.6e-12
print(result.best_params)       # ~zeros
print(result.history[-1])       # final best-so-far
print(result.n_evaluations)     # 30030
```

## How it works

MSPO maintains a swarm of agents ("parrots") that explore the search space. Each iteration, every agent independently picks one of four behavioral updates uniformly at random:

| Behavior | Role | Mechanism |
|---|---|---|
| **Foraging** | Exploration | Levy flight from the global best, with a decaying mean-pull term |
| **Staying** | Exploitation | Drift toward the global best with shrinking uniform noise |
| **Communicating** | Social | Either flock toward the population mean (50%) or fly off solitary with exponential decay (50%) |
| **Fear of strangers** | Chaotic | Cosine-modulated mix of attraction-to-best and repulsion-from-current, driven by a Tent map |

Three components distinguish MSPO from the base Parrot Optimizer:

1. **Sobol initialization** — low-discrepancy quasi-random sequence for uniform starting coverage of the search space
2. **Nonlinear decreasing inertia weight** — exponential decay from `w_max = 2.0` toward `w_min = 0.2`, driving the algorithm from broad exploration to fine exploitation over the course of the run
3. **Parametric Tent map** — chaotic coefficient (`β = 0.4`, `C₀ = 0.255`) for the fear-of-strangers behavior, helping the swarm escape local optima in the late stages of optimization

## Module layout

```
mspo/
├── initialization.py   # Sobol low-discrepancy starting population
├── inertia.py          # Nonlinear decreasing inertia weight schedule
├── chaos.py            # Parametric Tent map (state-carrying iterator)
├── utils.py            # Levy flight via Mantegna's algorithm
├── behaviors.py        # The four position update rules
└── optimizer.py        # MSPO class and main loop
```

Each module is small (under 200 lines) and accompanied by unit tests in `tests/`. The four behaviors share a uniform signature so the main loop dispatches to them by index.

## Validation

### Unit tests

73 tests across 7 modules, under 3 seconds:

```bash
pytest                     # full suite
pytest -m "not slow"       # skip the long sphere test
```

### CEC 2022 benchmark (official shifted/rotated functions)

Full benchmark using the official CEC 2022 SO-BO competition suite (12 shifted/rotated functions with the published shift vectors and rotation matrices from Suganthan et al., NTU Singapore). Evaluation protocol: N=30 agents, T=1000 iterations, dim=10, 30 independent runs per function, bounds [-100, 100].

Results — median error (f(x) - f*) on each function:

| Func | Name | MSPO | PSO | Random | Winner |
|---|---|---|---|---|---|
| F1  | Zakharov | 45.06 | 0.00 | 5436.40 | PSO |
| F2  | Rosenbrock | 10.05 | 62.98 | 256.16 | MSPO |
| F3  | Schaffer F7 | 1.71e-04 | 0.03 | 0.20 | MSPO |
| F4  | Rastrigin | 38.00 | 51.00 | 87.90 | MSPO |
| F5  | Levy | 0.55 | 0.67 | 2.47 | MSPO |
| F6  | Hybrid 1 | 39637 | 58895 | 10425125 | MSPO |
| F7  | Hybrid 2 | 60.02 | 29.50 | 214.49 | PSO |
| F8  | Hybrid 3 | 472.03 | 298.72 | 1061.58 | PSO |
| F9  | Composition 1 | 398.04 | 426.70 | 516.36 | MSPO |
| F10 | Composition 2 | -1254.97 | 29.57 | -366.14 | MSPO |
| F11 | Composition 3 | 2.32 | 79.14 | 117.85 | MSPO |
| F12 | Composition 4 | 165.34 | 170.97 | 242.15 | MSPO |

**MSPO ranks 1st on 9 of 12 functions with average rank 1.25**, consistent with the paper's reported results (1st on 9/12, avg rank 1.42).

To reproduce:

```bash
pip install -e ".[benchmark]"
python benchmarks/run_cec2022.py          # full run (~2.5 hours)
python benchmarks/run_cec2022.py --quick  # 5 runs, T=200 (~2 min)
```

### Convergence on 10D Sphere

End-to-end demo on the paper's exact CEC configuration (N=30, T=1000):

| Iteration | Best so far |
|---|---|
| 0   | 3.65 × 10³ |
| 100 | 8.56 × 10⁻² |
| 500 | 1.10 × 10⁻⁴ |
| 1000 | 1.63 × 10⁻¹² |

## Configuration

The defaults match the paper. The full constructor:

```python
MSPO(
    objective,            # f(x) -> float, position vector in -> scalar out
    bounds,               # iterable of (low, high) per dimension
    n_parrots=30,         # population size
    max_iter=1000,        # number of outer iterations
    w_max=2.0,            # initial inertia weight
    w_min=0.2,            # asymptotic floor
    lambda_=0.005,        # inertia exponential decay rate
    tent_c0=0.255,        # tent map initial value
    tent_beta=0.4,        # tent map breakpoint
    seed=None,            # for reproducibility
)
```

Set `seed` to make the run fully reproducible — the same seed reproduces the Sobol initialization, the per-iteration behavior choices, the Levy draws, and every internal uniform draw.

## Citation

If you use this code, please cite:

```bibtex
@article{govindarajan2025mspo,
    title   = {MSPO: A machine learning hyperparameter optimization method for enhanced breast cancer image classification},
    author  = {Govindarajan, Vijay},
    journal = {Digital Health},
    year    = {2025},
}
```

## License

MIT — see `LICENSE`.
