mha-flow 2.0.8

Professional Metaheuristic Algorithm Library with 142+ algorithms, Flask web interface, AI-powered recommendations, and GitHub-based custom algorithm submissions

🚀 MHA Flow - Advanced Meta-Heuristic Algorithms Framework

Version 2.0.7 | Open Source | 142+ Algorithms | AI-Powered | Flask Web Interface

A professional, production-ready Python framework for meta-heuristic optimization with Flask web interface, universal Levy flight integration, custom algorithm upload to GitHub, AI-powered recommendations, and SQLite/MongoDB database support.

---

✨ What's New in v2.0.7

🌐 Flask Production App - Modern web interface with user authentication, personal history, and admin dashboard

🔧 GitHub Integration - Custom algorithm submissions uploaded to GitHub for review and approval

🔬 Universal Levy Flight - All 142+ algorithms now support Levy flight for enhanced exploration

🎨 Custom Algorithm System - Upload your own MHA algorithms with automatic parsing and GitHub PR workflow

🤖 Enhanced AI Recommender - Intelligent algorithm selection based on dataset characteristics

💾 Flexible Database - SQLite (local) or MongoDB Atlas (cloud) support

📖 Complete CLI - Full command-line interface for headless operation

🔐 User Authentication - Secure login with personal optimization history tracking

---

📊 Key Features

Core Capabilities

• ✅ 142+ Metaheuristic Algorithms including evolutionary, swarm, physics-based, and hybrid variants
• 🧬 Universal Levy Flight - Integrated across all algorithms for better convergence
• 🔄 GitHub-Based Custom Algorithms - Submit your algorithms via GitHub PR workflow
• 🤖 AI-Powered Recommendations - Smart algorithm selection based on problem characteristics
• 📊 Real-Time Visualization - Live convergence plots and performance metrics
• 💾 Complete Session Management - Save, load, and compare optimization runs
• 🌐 Flask Web Interface - Professional UI with REST API and admin dashboard
• 📤 Multiple Export Formats - CSV, Excel, JSON, PNG, PDF
• 🔐 Multi-User Support - Authentication and personal history tracking
• 🖥️ Full CLI Support - Complete command-line interface for automation

Algorithm Categories

• Swarm Intelligence: PSO, GWO, WOA, SSA, ALO, GOA, HHO, JS, HBA, MPA, SMA, ChOA, AO, RSA, GTO
• Evolutionary: GA, DE, ABC, EP, ES
• Physics-Based: SA, GSA, MVO, EO, AOA
• Hybrid Algorithms: PSO-GA, GWO-PSO, DE-PSO, JS-PSO, HBA-GWO, MPA-DE, SMA-GA, AO-WOA
• Custom: User-uploaded algorithms with automatic integration

---

🚀 Quick Start

Installation

# Install from source (recommended for development)
git clone https://github.com/Achyut103040/MHA-Algorithm.git
cd MHA-Algorithm
pip install -e .

# Install with web interface
pip install -e .[ui]

# Install complete (all features)
pip install -e .[complete]

Launch the Application

# Flask web interface (recommended)
python -m mha_toolbox ui
# Then open http://127.0.0.1:5000

# Or using the installed command
mha-flow ui

# Command-line mode
mha-flow list                              # List all algorithms
mha-flow recommend --interactive           # Get recommendations
mha-flow run pso --dataset breast_cancer   # Run algorithm
mha-flow info gwo                          # Algorithm information
mha-flow version                           # Show version

---

🖥️ CLI Commands Reference

Command	Description
mha-flow ui	Launch Flask web interface
mha-flow list	List all 142+ algorithms
mha-flow recommend	AI-powered algorithm recommendations
mha-flow run <algo>	Run algorithm on dataset
mha-flow info <algo>	Show algorithm details
mha-flow demo	Run interactive demo
mha-flow version	Show version info

Examples

# Start web server on custom port
mha-flow ui --port 8080 --debug

# Filter algorithms by category
mha-flow list --category swarm
mha-flow list --category evolution
mha-flow list --category hybrid

# Run with custom parameters
mha-flow run gwo --dataset iris --population_size 50 --max_iterations 200

# Interactive recommendations
mha-flow recommend --interactive

For complete CLI documentation, see docs/CLI_COMMANDS.md.

---

💡 Usage Examples

1. Basic Optimization (Python API)

from mha_toolbox import MHAToolbox
from sklearn.datasets import load_iris

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

# Initialize toolbox
toolbox = MHAToolbox()

# Run optimization with Levy flight support
result = toolbox.optimize(
    algorithm='pso',
    X=X, 
    y=y,
    population_size=30,
    max_iterations=100,
    levy_enabled=True  # Enable Levy flight
)

# Access results
print(f"Best fitness: {result.best_fitness_:.6f}")
print(f"Runtime: {result.execution_time_:.2f}s")
print(f"Selected features: {result.n_selected_features_}")

2. Custom Algorithm Upload

from mha_toolbox.custom_algorithm_manager import CustomAlgorithmManager

# Initialize manager
manager = CustomAlgorithmManager()

# Process uploaded algorithm file
result = manager.process_upload(
    file_path='my_custom_algorithm.py',
    metadata={
        'author': 'Your Name',
        'description': 'My innovative MHA algorithm',
        'year': 2025
    }
)

# Check validation status
if result['success']:
    print(f"✓ Algorithm validated: {result['validation']['main_class_name']}")
    print(f"Parameters detected: {result['parameter_mapping']}")
    
    # Integrate into system
    integration = manager.integrate_algorithm(
        file_path='my_custom_algorithm.py',
        parameter_mapping=result['parameter_mapping'],
        category='custom'
    )
    print(f"✓ Algorithm integrated: {integration['algorithm_id']}")

3. AI-Powered Algorithm Recommendation

from mha_toolbox import AlgorithmRecommender
from mha_toolbox.dataset_intelligence import DatasetIntelligence

# Initialize recommender
recommender = AlgorithmRecommender()

# Analyze dataset
intelligence = DatasetIntelligence()
profile = intelligence.analyze_dataset(X, y)

# Get recommendations
recommendations = recommender.recommend(
    dataset_profile=profile,
    user_preferences={
        'priority': 'accuracy',  # or 'speed', 'balance'
        'expected_features': ['multimodal', 'complex'],
        'time_limit': 60  # seconds
    },
    top_k=5
)

# Display recommendations
for i, rec in enumerate(recommendations, 1):
    print(f"{i}. {rec['algorithm']} (confidence: {rec['confidence']:.2%})")
    print(f"   Reason: {rec['reasoning']}")

4. Using Levy Flight Directly

from mha_toolbox.algorithms.levy_flight_universal import add_levy_flight_to_position
import numpy as np

# Your algorithm's iteration
current_position = np.random.rand(10)
best_position = np.zeros(10)
bounds = (-100, 100)

# Apply Levy flight
new_position = add_levy_flight_to_position(
    position=current_position,
    best_position=best_position,
    bounds=bounds,
    iteration=10,
    max_iterations=100,
    beta=1.5  # Levy exponent
)

print(f"Position after Levy flight: {new_position}")

5. Flask Web Interface Usage

# Start the Flask server
# python app.py

# Then use the REST API
import requests

# Upload custom algorithm
files = {'file': open('my_algorithm.py', 'rb')}
response = requests.post('http://localhost:5000/api/upload-algorithm', files=files)
print(response.json())

# Get algorithm recommendations
data = {
    'dataset_size': 1000,
    'n_features': 20,
    'problem_type': 'classification',
    'complexity': 'high'
}
response = requests.post('http://localhost:5000/api/recommend-algorithm', json=data)
print(response.json()['recommendations'])

# Run optimization
optimization_data = {
    'algorithm': 'pso',
    'population_size': 30,
    'max_iterations': 100,
    'levy_enabled': True
}
response = requests.post('http://localhost:5000/api/optimize', json=optimization_data)
print(response.json()['results'])

---

📚 Documentation

For Users

• Quick Start Guide - Get running in 5 minutes
• User Manual - Complete usage guide
• Algorithm Catalog - All available algorithms
• API Reference - Python API documentation
• Web UI Guide - Using the Flask interface

For Contributors

• Contributing Guidelines - How to contribute
• Code of Conduct - Community standards
• Development Setup - Setting up dev environment
• Architecture Overview - System design
• Adding Algorithms - Contribute new algorithms

---

🏗️ Architecture

MHA-Algorithm/
├── mha_toolbox/                 # Core library
│   ├── algorithms/              # 137+ algorithm implementations
│   │   ├── levy_flight_universal.py  # Universal Levy flight
│   │   ├── base_algorithm.py    # Base classes
│   │   ├── hybrid/              # Hybrid algorithms
│   │   └── custom/              # User-uploaded algorithms
│   ├── levy_flight_engine.py    # Advanced Levy flight engine
│   ├── custom_algorithm_manager.py  # Algorithm upload system
│   ├── algorithm_recommender.py # AI recommendation system
│   ├── dataset_intelligence.py  # Dataset analysis
│   └── complete_algorithm_registry_v2.py  # Algorithm metadata
├── app.py                       # Flask web application
├── templates/                   # HTML templates
├── static/                      # CSS, JS, assets
├── tests/                       # Test suite
└── docs/                        # Documentation

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

1. Add New Algorithms - Implement and submit new MHA algorithms
2. Improve Existing Algorithms - Optimize performance and fix bugs
3. Enhance Documentation - Improve guides and examples
4. Report Issues - Help us identify and fix problems
5. Suggest Features - Share your ideas for improvements

Contribution Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and test thoroughly
4. Commit with clear messages (git commit -m 'Add amazing feature')
5. Push to your branch (git push origin feature/amazing-feature)
6. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

📈 Algorithm Performance Comparison

Algorithm	Convergence Speed	Exploration	Exploitation	Best For
PSO	⚡⚡⚡⚡⚡	⭐⭐⭐⭐	⭐⭐⭐	Fast, continuous
GWO	⚡⚡⚡⚡	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	Multimodal, complex
WOA	⚡⚡⚡	⭐⭐⭐⭐⭐	⭐⭐⭐	Large search space
JS	⚡⚡⚡⚡	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	Dynamic problems
HBA	⚡⚡⚡⚡	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Robust optimization
DE	⚡⚡⚡	⭐⭐⭐	⭐⭐⭐⭐⭐	Numerical optimization
GA	⚡⚡⚡	⭐⭐⭐⭐	⭐⭐⭐	Combinatorial problems
PSO-GA	⚡⚡⚡⚡	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	Complex, multimodal
HBA-GWO	⚡⚡⚡⚡	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	High-dimensional

---

🔬 Research & Citations

If you use MHA Flow in your research, please cite:

@software{mha_flow_2025,
  title={MHA Flow: Advanced Meta-Heuristic Algorithms Framework},
  author={MHA Flow Development Team},
  year={2025},
  version={3.0.0},
  url={https://github.com/yourusername/MHA-Algorithm}
}

Key Papers Implemented

• Kennedy & Eberhart (1995) - Particle Swarm Optimization
• Mirjalili et al. (2014) - Grey Wolf Optimizer
• Mirjalili & Lewis (2016) - Whale Optimization Algorithm
• Chou & Truong (2020) - Jellyfish Search
• Hashim et al. (2021) - Honey Badger Algorithm
• And 130+ more...

---

📊 Project Statistics

• Lines of Code: 50,000+
• Algorithms: 137+
• Test Coverage: 85%+
• Documentation Pages: 15+
• Active Contributors: Open for community
• GitHub Stars: ⭐ Star us!

---

🛠️ Technical Requirements

Minimum Requirements

• Python 3.8 or higher
• NumPy >= 1.19.0
• Pandas >= 1.1.0
• Scikit-learn >= 0.23.0
• Flask >= 2.0.0 (for web interface)
• 4GB RAM
• 1GB disk space

Recommended Setup

• Python 3.10+
• 8GB RAM
• GPU (optional, for large-scale optimization)
• Modern web browser (Chrome, Firefox, Edge)

---

🐛 Known Issues & Limitations

• Large datasets (>100k samples) may require significant memory
• Some algorithms are computationally intensive
• Web interface requires modern browser with JavaScript enabled
• Custom algorithm validation is heuristic-based

See Issues for current bugs and feature requests.

---

🗺️ Roadmap

Version 3.1 (Q1 2026)

• GPU acceleration for algorithms
• Distributed optimization support
• More visualization options
• Mobile app interface

Version 3.2 (Q2 2026)

• AutoML integration
• Neural architecture search
• Cloud deployment options
• Enhanced benchmarking suite

Version 4.0 (Q3 2026)

• Real-time collaborative optimization
• Advanced analytics dashboard
• Plugin system for extensions
• Commercial support options

---

📞 Support & Community

• Documentation: Read the Docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]
• Twitter: @MHAFlow

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 MHA Flow Development Team

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.

---

🙏 Acknowledgments

• All algorithm authors and researchers
• Open-source community contributors
• Scientific Python ecosystem (NumPy, SciPy, Scikit-learn)
• Flask and Streamlit teams
• Our amazing community of users and contributors

---

⭐ Star History

---

Made with ❤️ by the MHA Flow Team

Empowering researchers and developers with state-of-the-art optimization algorithms