mspo 0.1.0

Multi-Strategy Parrot Optimizer for hyperparameter tuning

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

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

Requires Python 3.10+, NumPy, SciPy.

Quick start

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:

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:

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:

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:

@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.