Metadata-Version: 2.4
Name: bioalgo
Version: 0.9.0
Summary: A lightweight, modular Python toolkit for bio-inspired and nature-inspired metaheuristic optimization algorithms.
Author-email: Developer <developer@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/example/bioalgo
Project-URL: Repository, https://github.com/example/bioalgo
Project-URL: Documentation, https://github.com/example/bioalgo#readme
Keywords: optimization,metaheuristics,bio-inspired,nature-inspired,particle-swarm-optimization,differential-evolution,simulated-annealing,firefly-algorithm,biogeography-based-optimization,hill-climbing,n-queens,traveling-salesman-problem
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# bioalgo

[![PyPI version](https://img.shields.io/pypi/v/bioalgo.svg)](https://pypi.org/project/bioalgo/)
[![Python versions](https://img.shields.io/pypi/pyversions/bioalgo.svg)](https://pypi.org/project/bioalgo/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**bioalgo** is a lightweight, pure-Python library for nature-inspired, bio-inspired, and metaheuristic optimization algorithms. It includes both discrete combinatorial solvers (N-Queens, Traveling Salesman Problem) and continuous multimodal function optimizers.

---

pypi-AgEIcHlwaS5vcmcCJDRkNTQ5Yzk5LWQzNTgtNGZiZS1hOGEyLWI0MTNhZmEyMDllZQACKlszLCI4NmU3NTdlNy1iYWJiLTQzNTQtYjhlOC04ZTA3NWY0NThiYTkiXQAABiA_nmoBeOPi25RiDzwqaUokVcrjsG3TeUCAsTq1bUDsNQ

## Algorithms Included

| Algorithm | Type | Description / Operators | Typical Applications |
| :--- | :--- | :--- | :--- |
| **Hill Climbing** | Discrete Local Search | Steepest ascent, conflict evaluation, random-restart heuristics | N-Queens, constraint satisfaction |
| **Simulated Annealing (SA)** | Metaheuristic | Metropolis acceptance criterion ($P = e^{-\Delta E / T}$), 2-opt swaps, geometric cooling | Traveling Salesman Problem (TSP), combinatorial routing |
| **Particle Swarm Optimization (PSO)** | Swarm Intelligence | Velocity/position updates, cognitive ($\text{pBest}$) and social ($\text{gBest}$) components, inertia damping | Continuous multimodal minimization |
| **Differential Evolution (DE)** | Evolutionary | Mutation (`DE/rand/1`, `DE/best/1`), binomial crossover ($CR$), one-to-one selection | Non-linear parameter estimation, benchmark optimization |
| **Biogeography-Based Optimization (BBO)** | Ecological | Species migration ($\lambda, \mu$), Habitat Suitability Index (HSI), elitism, mutation | Continuous global optimization |
| **Firefly Algorithm (FA)** | Swarm Intelligence | Light intensity, distance attractiveness ($\beta(r) = \beta_0 e^{-\gamma r^2}$), randomized step damping | Multimodal landscapes with multiple local optima |

---

## Installation

Install via `pip`:

```bash
pip install bioalgo
```

Or install in development/editable mode:

```bash
git clone https://github.com/example/bioalgo.git
cd bioalgo
pip install -e .
```

---

## Quickstart

### 1. Particle Swarm Optimization (PSO)
```python
from bioalgo import ParticleSwarmOptimization
from bioalgo.benchmarks import rastrigin

# Optimize the multimodal Rastrigin function in 5 dimensions
pso = ParticleSwarmOptimization(
    cost_func=rastrigin,
    dim=5,
    bounds=(-5.12, 5.12),
    num_particles=40
)

best_vector, best_cost, history = pso.optimize(max_iter=100)
print(f"Optimal Cost: {best_cost:.6e}")
print(f"Optimal Solution: {best_vector}")
```

### 2. Differential Evolution (DE)
```python
from bioalgo import DifferentialEvolution
from bioalgo.benchmarks import ackley

de = DifferentialEvolution(
    cost_func=ackley,
    dim=5,
    bounds=(-32.768, 32.768),
    pop_size=40,
    strategy="best/1/bin"
)

best_vector, best_cost, history = de.optimize(max_generations=100)
print(f"Ackley Minimum: {best_cost:.6e}")
```

### 3. Solve N-Queens with Hill Climbing
```python
from bioalgo import NQueensProblem, HillClimbing

problem = NQueensProblem(n=8)
solver = HillClimbing(problem)
solution, restarts, steps = solver.search_with_restarts(max_restarts=50)

print(f"Solved in {restarts} restart(s) and {steps} steps:")
print(problem.render_board(solution))
```

### 4. Traveling Salesman Problem (TSP) with Simulated Annealing
```python
from bioalgo import TravelingSalesmanProblem, SimulatedAnnealing

problem = TravelingSalesmanProblem()
sa = SimulatedAnnealing(problem, initial_temp=1000.0, cooling_rate=0.995)

best_tour, best_distance, history = sa.optimize(seed=42)
print(f"Best Tour Length: {best_distance:.2f}")
print("Tour Sequence:", " -> ".join(best_tour))
```

---

## Built-in Benchmark Functions

`bioalgo.benchmarks` includes standard continuous functions:
- `sphere(x)`
- `rastrigin(x)`
- `ackley(x)`
- `rosenbrock(x)`
- `griewank(x)`

---

## Command Line Interface (CLI)

`bioalgo` comes with a command-line interface:

```bash
# Solve 8-Queens and render the board
bioalgo nqueens -n 8 --render

# Solve Traveling Salesman Problem
bioalgo tsp --temp 1000 --cooling 0.995

# Optimize a continuous benchmark using PSO, DE, BBO, or FA
bioalgo optimize pso --func rastrigin --dim 5 --iters 100
bioalgo optimize de --func ackley --dim 5 --iters 100
bioalgo optimize bbo --func sphere --dim 5 --iters 100
bioalgo optimize fa --func rastrigin --dim 5 --iters 100
```

---

## Building and Publishing to PyPI

### 1. Build the Distribution Archives
```bash
python -m build
```
This produces `.tar.gz` (source distribution) and `.whl` (built wheel) in `dist/`.

### 2. Check Package Metadata
```bash
twine check dist/*
```

### 3. Test on TestPyPI (Recommended first)
```bash
twine upload --repository testpypi dist/*
```

### 4. Upload to Production PyPI
```bash
twine upload dist/*
```

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
