# 🚀 MHA Flow - Meta-Heuristic Algorithms Optimization Library

**Version 2.0.4** | Production Ready | 130+ Algorithms | AI-Powered Recommendations

A comprehensive Python library for meta-heuristic optimization algorithms with AI-powered algorithm recommendations, modern web interface, and support for feature selection, hyperparameter tuning, and benchmark testing.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Web Interface](https://img.shields.io/badge/Web-mha--flow.streamlit.app-brightgreen)](https://mha-flow.streamlit.app/)

---

## ✨ What's New in v2.0.4

- 🤖 **AI-Powered Algorithm Recommender** - Smart recommendations based on dataset characteristics
- 🎨 **Modern 3-Step Workflow** - Intuitive guided interface
- 🌐 **Online Web Interface** - Access from anywhere at [mha-flow.streamlit.app](https://mha-flow.streamlit.app/)
- 📊 **Enhanced Visualizations** - Real-time convergence plots and comparisons
- 🔐 **Multi-User Authentication** - Personal optimization history tracking
- 💫 **130+ Algorithms** - Expanded algorithm library with hybrids

---

## 📊 Features

- ✅ **130+ Meta-Heuristic Algorithms** with hybrid combinations
- 🤖 **AI-Powered Algorithm Recommendations** based on dataset analysis
- 🎯 **13 Algorithm Categories** (Swarm, Bio-Inspired, Physics-Based, etc.)
- 🔧 **4 Usage Modes**: Python Library, Web UI, Online Interface, CLI
- 📈 **Real-Time Visualization** with interactive plots
- 💾 **Complete Results Saving** with comprehensive analysis
- 🔄 **Multi-User Session Management** with authentication
- 📤 **Export Results**: CSV, Excel, JSON, PNG
- 📚 **Comprehensive Documentation** and examples
- 🌐 **Access Anywhere** - Online or local deployment

---

## 🚀 Quick Start

### Installation

```bash
# Install from PyPI (recommended)
pip install mha-flow

# With web interface
pip install mha-flow[ui]

# Complete installation (all features)
pip install mha-flow[complete]

# Or install from source
git clone https://github.com/Achyut103040/MHA-Algorithm.git
cd MHA-Algorithm
pip install -e .
```

### Launch Commands

```bash
# Open online web interface (no local installation needed)
mha-flow-web

# Launch local web interface
mha-flow

# Command-line interface
mha-flow-cli

# Run demo system
mha-demo
```

### Python Library Usage

```python
from mha_toolbox import MHAToolbox
from sklearn.datasets import load_iris

# Load data
X, y = load_iris(return_X_y=True)

# Initialize toolbox
toolbox = MHAToolbox()

# Run optimization
result = toolbox.optimize('pso', X=X, y=y, population_size=30, max_iterations=100)

# Access results
print(f"Best fitness: {result.best_fitness_}")
print(f"Runtime: {result.execution_time_}s")
print(f"Best solution: {result.best_solution_}")
```

### AI-Powered Recommendations

```python
from mha_toolbox import AlgorithmRecommender

# Initialize recommender
recommender = AlgorithmRecommender()

# Get recommendations based on your dataset
recommendations = recommender.recommend_algorithms(X, y, top_k=5)

for algo, confidence, reason in recommendations:
    print(f"{algo.upper()}: {confidence:.1f}/10 - {reason}")
```

---

## 🌐 Web Interfaces

### Online Interface (Recommended)
**No installation required!** Access the full-featured web interface at:
👉 **[https://mha-flow.streamlit.app/](https://mha-flow.streamlit.app/)**

Features:
- 🔐 User authentication & history
- 🤖 AI-powered algorithm recommendations
- 📊 6 sample datasets included
- 📈 Real-time visualizations
- 💾 Export results in multiple formats

### Local Interface
Run the web interface on your machine:
```bash
mha-flow
```

---

## 📦 130+ Available Algorithms

### 🐝 Swarm Intelligence (18)
PSO, GWO, WOA, ACO, ABC, BA, FA, SSA, ALO, MFO, CS, FPA, KH, etc.

### 🧬 Bio-Inspired (21)
SMA, HBA, DMO, EHO, GAO, TSO, MRFO, SOS, BMO, etc.

### 🌡️ Physics-Based (12)
SA, EO, GSA, MSA, CSA, AOA, MVO, HGSO, WDO, WCA, etc.

### 🔍 Search-Based (20)
TS, VNS, HS, HC, HGS, ILS, GLS, etc.

### 🧠 Human-Based (9)
TLBO, LCA, LCBO, SOS, ICA, TBO, CHIO, QSA, etc.

### 🔥 Hybrid Algorithms (22)
PSO_GA, GWO_PSO, ABC_DE, ACO_PSO, FA_DE, WOA_GA, SMA_DE, etc.

### 🧬 Evolutionary (2)
GA, DE

### 🎯 Advanced Meta-Heuristics (6)
SCA, HHO, AO, GTO, RSA, ASO

### 📐 Mathematical (4)
CEM, GCO, GBMO, GSKA

### 🌊 Nature-Inspired (1)
DA (Dragonfly Algorithm)

### 🦠 Pandemic-Inspired (1)
CHIO (Coronavirus Herd Immunity)

### 🎮 Game-Based (1)
THRO (Throwing Game)

### 🔬 Other Specialized (8)
Various domain-specific algorithms

---

## 🎯 Usage Modes

### 1️⃣ Python Library (Programmatic)

```python
from mha_toolbox import optimize, MHAToolbox

# Simple API - Quick optimization
result = optimize('pso', X=X, y=y)

# Advanced API - Full control
toolbox = MHAToolbox(verbose=False)
algorithms = toolbox.list_algorithms()  # Returns 125 algorithms
hybrids = toolbox.registry.list_hybrid_algorithms()  # Returns 22 hybrids

# Run with custom parameters
result = toolbox.optimize(
    'PSO_GA_Hybrid',
    X=X, y=y,
    population_size=50,
    max_iterations=200,
    verbose=True
)

# Access all results
print(f"Best solution: {result.best_solution_}")     # numpy array
print(f"Best fitness: {result.best_fitness_}")       # float
print(f"Convergence: {result.global_fitness_}")      # list
print(f"Agent history: {result.local_fitness_}")     # list
print(f"Positions: {result.local_positions_}")       # list
print(f"Algorithm: {result.algorithm_name_}")        # string
print(f"Runtime: {result.execution_time_}s")         # float
```

### 2️⃣ Web Interface (Streamlit)

```bash
# Launch the web UI
python mha_ui_complete.py

# Or use streamlit directly
streamlit run mha_ui_complete.py
```

**Features:**
- 125 algorithms with interactive parameter tuning
- Real-time visualization of convergence
- Multi-user session management
- Compare multiple algorithms
- Export results (CSV, Excel, JSON, PNG)
- Algorithm recommendations

### 3️⃣ Command-Line Interface (CLI)

```bash
# List all algorithms
python -m mha_toolbox list

# List only hybrid algorithms
python -m mha_toolbox list --filter hybrid

# Get algorithm information
python -m mha_toolbox info pso

# Get recommendations
python -m mha_toolbox recommend --problem-type feature_selection

# Launch web interface
python -m mha_toolbox ui

# Show demo
python -m mha_toolbox demo
```

---

## 🔥 Hybrid Algorithms (All 22 Working)

Hybrid algorithms combine the strengths of multiple optimization approaches:

```python
from mha_toolbox import optimize

# Available hybrid algorithms:
hybrids = [
    'PSO_GA_Hybrid',           # Particle Swarm + Genetic Algorithm
    'GWO_PSO_Hybrid',          # Grey Wolf + Particle Swarm
    'ABC_DE_Hybrid',           # Artificial Bee Colony + Differential Evolution
    'ACO_PSO_Hybrid',          # Ant Colony + Particle Swarm
    'FA_DE_Hybrid',            # Firefly + Differential Evolution
    'FA_GA_Hybrid',            # Firefly + Genetic Algorithm
    'WOA_GA_Hybrid',           # Whale + Genetic Algorithm
    'WOA_SMA_Hybrid',          # Whale + Slime Mould
    'SMA_DE_Hybrid',           # Slime Mould + Differential Evolution
    'CS_GA_Hybrid',            # Cuckoo Search + Genetic Algorithm
    'ALO_PSO_Hybrid',          # Ant Lion + Particle Swarm
    'SSA_DE_Hybrid',           # Salp Swarm + Differential Evolution
    'GWO_DE_Hybrid',           # Grey Wolf + Differential Evolution
    'HS_DE_Hybrid',            # Harmony Search + Differential Evolution
    'KH_PSO_Hybrid',           # Krill Herd + Particle Swarm
    'MFO_DE_Hybrid',           # Moth Flame + Differential Evolution
    'SA_PSO_Hybrid',           # Simulated Annealing + Particle Swarm
    'TS_GA_Hybrid',            # Tabu Search + Genetic Algorithm
    'DA_GA_Hybrid',            # Dragonfly + Genetic Algorithm
    'FPA_GA_Hybrid',           # Flower Pollination + Genetic Algorithm
    'DifferentialEvolutionPSOHybrid',
    'GeneticSimulatedAnnealingHybrid'
]

# Use any hybrid algorithm
result = optimize('PSO_GA_Hybrid', X=X, y=y, population_size=30, max_iterations=100)
```

---

## 📋 Examples

### Example 1: Feature Selection

```python
from mha_toolbox import optimize
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split

# Load dataset
X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)

# Optimize with PSO
result = optimize(
    'pso',
    X=X_train,
    y=y_train,
    population_size=30,
    max_iterations=50,
    verbose=True
)

print(f"Selected {sum(result.best_solution_)} features")
print(f"Best fitness: {result.best_fitness_:.6f}")
```

### Example 2: Compare Multiple Algorithms

```python
from mha_toolbox import optimize

algorithms = ['pso', 'gwo', 'woa', 'PSO_GA_Hybrid']
results = {}

for algo in algorithms:
    result = optimize(algo, X=X_train, y=y_train, max_iterations=30)
    results[algo] = {
        'fitness': result.best_fitness_,
        'time': result.execution_time_
    }
    print(f"{algo:15s} - Fitness: {result.best_fitness_:.6f} - Time: {result.execution_time_:.2f}s")
```

### Example 3: Using Toolbox API

```python
from mha_toolbox import MHAToolbox

# Initialize
toolbox = MHAToolbox(verbose=True)

# Get algorithm info
total = len(toolbox.list_algorithms())
hybrids = len(toolbox.registry.list_hybrid_algorithms())
print(f"Total algorithms: {total}")
print(f"Hybrid algorithms: {hybrids}")

# Get algorithms by category
by_category = toolbox.registry.get_algorithm_by_category()
for category, algos in by_category.items():
    print(f"{category}: {len(algos)} algorithms")

# Run optimization
result = toolbox.optimize('pso', X=X, y=y)
```

---

## 🧪 Testing

### Quick Verification

```bash
# Test system
python final_system_test.py

# Test hybrid algorithms
python test_fixed_hybrids.py

# Quick start demo
python hybrid_quick_start.py
```

### Run Tests

```python
# In Python
from mha_toolbox import MHAToolbox

toolbox = MHAToolbox(verbose=False)
print(f"✅ Algorithms discovered: {len(toolbox.list_algorithms())}")
print(f"✅ Hybrids available: {len(toolbox.registry.list_hybrid_algorithms())}")
```

---

## 📊 Performance Benchmarks

Tested on Iris dataset (150 samples, 4 features):

| Algorithm | Runtime | Best Fitness | Convergence |
|-----------|---------|--------------|-------------|
| PSO | 9.9s | 0.071667 | 10 iterations |
| GWO_PSO_Hybrid | 2.8s | 0.120238 | 3 iterations |
| ABC_DE_Hybrid | 5.0s | 0.107143 | 3 iterations |
| ACO_PSO_Hybrid | 2.3s | 0.107143 | 3 iterations |
| FA_DE_Hybrid | 3.1s | 0.101190 | 3 iterations |

*Note: Times vary based on population size and iterations*

---

## 🛠️ Requirements

- Python 3.8+
- numpy >= 1.19.0
- scipy >= 1.5.0
- scikit-learn >= 0.23.0
- matplotlib >= 3.3.0
- pandas >= 1.1.0
- streamlit >= 1.0.0 (for UI)
- plotly >= 4.14.0 (for visualization)

---

## 📁 Project Structure

```
MHA-Algorithm/
├── mha_toolbox/              # Main package
│   ├── __init__.py
│   ├── base.py               # BaseOptimizer class
│   ├── toolbox.py            # Main MHAToolbox class
│   ├── complete_algorithm_registry.py  # Algorithm discovery
│   ├── algorithms/           # 103 algorithm implementations
│   │   └── hybrid/           # 22 hybrid algorithms
│   ├── ui.py                 # Web interface
│   └── __main__.py           # CLI implementation
├── mha_ui_complete.py        # Complete web interface
├── examples/                 # Example scripts
├── objective_functions/      # Benchmark functions
├── requirements.txt
├── setup.py
├── README.md                 # This file
└── LICENSE
```

---

## 💡 Tips & Best Practices

### Choosing Population Size
- Small datasets (< 1000 samples): 20-30
- Medium datasets (1000-10000): 30-50
- Large datasets (> 10000): 50-100

### Choosing Iterations
- Quick test: 10-20 iterations
- Standard optimization: 50-100 iterations
- Thorough search: 200-500 iterations

### Choosing Algorithm
- **Fast convergence**: PSO, GWO, WOA
- **Exploration**: GA, DE, ABC
- **Balanced**: Hybrid algorithms (PSO_GA, GWO_PSO)
- **Complex problems**: Advanced hybrids (ABC_DE, FA_DE)

---

## 🐛 Troubleshooting

### Import Error
```bash
pip install -r requirements.txt --upgrade
```

### Algorithm Not Found
```python
from mha_toolbox import MHAToolbox
toolbox = MHAToolbox()
print(toolbox.list_algorithms())  # Check available names
```

### Slow Optimization
- Reduce `population_size` (e.g., from 50 to 20)
- Reduce `max_iterations` (e.g., from 100 to 30)
- Use faster algorithms (PSO, GWO instead of GA)

### Memory Error
- Reduce population size
- Process data in batches
- Use simpler algorithms

---

## 🤝 Contributing

Contributions are welcome! To add a new algorithm:

1. Create algorithm file in `mha_toolbox/algorithms/`
2. Inherit from `BaseOptimizer`
3. Implement `_optimize()` method
4. Add tests
5. Submit pull request

---

## 📄 License

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

---

## 📧 Contact

- **Author**: MHA Development Team
- **GitHub**: [Achyut103040/MHA-Algorithm](https://github.com/Achyut103040/MHA-Algorithm)
- **Issues**: [GitHub Issues](https://github.com/Achyut103040/MHA-Algorithm/issues)

---

## 🎉 Acknowledgments

This library implements meta-heuristic algorithms from various research papers and combines them into a unified, easy-to-use framework.

---

## 📈 Version History

### v2.0.0 (2025-11-05) - Production Ready
- ✅ 125 algorithms (103 main + 22 hybrids)
- ✅ All hybrid algorithms fixed and working
- ✅ Complete web interface with multi-user support
- ✅ CLI implementation
- ✅ Comprehensive documentation
- ✅ All tests passing

### v1.x - Previous versions
- Initial implementations
- Core algorithms
- Basic UI

---

**Made with ❤️ for the optimization community**

*Last Updated: November 5, 2025*
