EvoloPy 1.1.0

An open source nature-inspired optimization toolbox for global optimization in Python

EvoloPy: An open source nature-inspired optimization toolbox for global optimization in Python

The EvoloPy toolbox provides classical and recent nature-inspired metaheuristic algorithms for global optimization. The library includes popular algorithms such as Particle Swarm Optimization (PSO), Multi-Verse Optimizer (MVO), Grey Wolf Optimizer (GWO), and many others.

Features

• 14 Nature-Inspired Algorithms: Comprehensive collection of metaheuristic optimizers
• High Performance: Optimized implementation using NumPy vectorization
• Easy to Use: Simple and consistent API across all algorithms
• Configurable: Flexible parameter settings for all algorithms
• Comprehensive Benchmarks: 24 test functions to evaluate algorithms
• Visualization Tools: Built-in plotting for convergence analysis and comparative studies
• Command-Line Interface: Run optimizations directly from the terminal

Table of Contents

• Installation
• Quick Start
• Package Structure
• Available Optimizers
• Benchmark Functions
• API Reference
• Command-Line Interface
• Example Projects
• Recent Improvements
• Contributing
• Publications
• Cite Us
• License

Installation

Via pip (Recommended)

pip install EvoloPy

From Source

# Clone the repository
git clone https://github.com/7ossam81/EvoloPy.git

# Navigate to the directory
cd EvoloPy

# Install dependencies
pip install -r requirements.txt

# Install the package
pip install -e .

Requirements

• Python 3.6+
• Dependencies:
  • numpy >= 1.19.0
  • pandas >= 1.0.0
  • scipy >= 1.5.0
  • matplotlib >= 3.3.0
  • scikit-learn >= 0.23.0

Quick Start

Basic Example

from EvoloPy.optimizer import run

# Select optimizers from the available list
optimizer = ["PSO", "GWO", "MVO"]

# Select benchmark functions
objective_functions = ["F1", "F5"]

# Set number of independent runs
num_runs = 10

# Set general parameters
params = {"PopulationSize": 30, "Iterations": 50}

# Configure export options
export_flags = {
    "Export_avg": True,
    "Export_details": True,
    "Export_convergence": True,
    "Export_boxplot": True
}

# Run the optimization
run(optimizer, objective_functions, num_runs, params, export_flags)

Using the High-Level API

import EvoloPy as ep

# List available optimizers
print("Available optimizers:", ep.available_optimizers())

# Run a single optimizer on a benchmark function
result = ep.run_optimizer(
    optimizer="PSO",
    objective_func="F1",
    population_size=50,
    iterations=100
)

print(f"Best fitness: {result['best_fitness']}")
print(f"Execution time: {result['execution_time']} seconds")

Custom Objective Function

import numpy as np
from EvoloPy.optimizers import PSO

# Define your custom objective function
def my_function(x):
    return np.sum(x**2) + np.sum(np.sin(x))

# Set boundaries and dimensions
lb = -10
ub = 10
dim = 5
population_size = 30
iterations = 100

# Run optimization
result = PSO.PSO(my_function, lb, ub, dim, population_size, iterations)

# Get the best solution
best_solution = result.bestIndividual
best_fitness = my_function(best_solution)

print(f"Best solution: {best_solution}")
print(f"Best fitness: {best_fitness}")
print(f"Execution time: {result.executionTime} seconds")

Package Structure

EvoloPy/
  __init__.py       # Package entry point 
  api.py            # High-level API functions
  optimizer.py      # Core optimization functionalities
  benchmarks.py     # Test functions
  solution.py       # Solution data structure
  cli.py            # Command-line interface
  optimizers/       # Individual algorithm implementations
    __init__.py     # Direct imports for all optimizers
    PSO.py          # Particle Swarm Optimization
    GWO.py          # Grey Wolf Optimizer
    MVO.py          # Multi-Verse Optimizer
    ... (other algorithm implementations)

Import System

EvoloPy provides multiple ways to import and use its functionality:

1. Top-level imports:

   import EvoloPy as ep
   
   # Use high-level API functions
   result = ep.run_optimizer("PSO", "F1")
   

2. Direct optimizer imports:

   from EvoloPy.optimizers import PSO, GWO
   
   # Use specific optimizer directly
   result_pso = PSO.PSO(objective_function, lb=-10, ub=10, dim=5, PopSize=30, iters=50)
   

3. Dynamic optimizer selection:

   from EvoloPy.optimizers import optimizer_map
   
   # Select optimizer dynamically
   optimizer_func = optimizer_map["PSO"]
   result = optimizer_func(objective_function, lb=-10, ub=10, dim=5, PopSize=30, iters=50)
   

Available Optimizers

The following optimizers are implemented in EvoloPy:

Abbreviation	Algorithm Name	Reference
PSO	Particle Swarm Optimization	Kennedy, J., & Eberhart, R. (1995)
GWO	Grey Wolf Optimizer	Mirjalili, S. et al. (2014)
MVO	Multi-Verse Optimizer	Mirjalili, S. et al. (2015)
MFO	Moth Flame Optimization	Mirjalili, S. (2015)
CS	Cuckoo Search	Yang, X. S., & Deb, S. (2009)
BAT	Bat Algorithm	Yang, X. S. (2010)
WOA	Whale Optimization Algorithm	Mirjalili, S., & Lewis, A. (2016)
FFA	Firefly Algorithm	Yang, X. S. (2009)
SSA	Salp Swarm Algorithm	Mirjalili, S. et al. (2017)
GA	Genetic Algorithm	Holland, J. H. (1975)
HHO	Harris Hawks Optimization	Heidari, A. A. et al. (2019)
SCA	Sine Cosine Algorithm	Mirjalili, S. (2016)
JAYA	JAYA Algorithm	Rao, R. (2016)
DE	Differential Evolution	Storn, R., & Price, K. (1997)

Benchmark Functions

EvoloPy includes 24 benchmark functions (F1-F24) commonly used to evaluate optimization algorithms:

• F1-F4: Unimodal benchmark functions
• F5-F12: Multimodal benchmark functions
• F13-F24: Composite benchmark functions

Additionally, popular test functions are available:

• Ackley function
• Rosenbrock function
• Rastrigin function
• Griewank function

You can list all available benchmark functions using:

from EvoloPy import available_benchmarks
print(available_benchmarks())

API Reference

High-Level API Functions

available_optimizers()

Get a list of all available optimization algorithms.

Returns:

• List[str]: List of optimizer names

Example:

from EvoloPy import available_optimizers
print(available_optimizers())
# ['PSO', 'GWO', 'MVO', ...]

available_benchmarks()

Get a list of all available benchmark functions.

Returns:

• List[str]: List of benchmark function names

Example:

from EvoloPy import available_benchmarks
print(available_benchmarks())
# ['F1', 'F2', 'F3', ...]

run_optimizer(optimizer, objective_func, **kwargs)

Run a single optimizer on a specified objective function.

Parameters:

• optimizer (str): Name of the optimizer algorithm
• objective_func (str or callable): Either a benchmark name (e.g., "F1") or a custom objective function
• lb (float): Lower bound for variables (default: -100)
• ub (float): Upper bound for variables (default: 100)
• dim (int): Problem dimension (default: 30)
• population_size (int): Size of the population (default: 30)
• iterations (int): Maximum number of iterations (default: 50)
• num_runs (int): Number of independent runs (default: 1)
• export_results (bool): Whether to export average results (default: False)
• export_details (bool): Whether to export detailed results (default: False)
• export_convergence (bool): Whether to export convergence plots (default: False)
• export_boxplot (bool): Whether to export boxplots (default: False)
• results_directory (str, optional): Directory to save results

Returns:

• Dict[str, Any]: Results dictionary containing:
  • 'best_solution': Best solution found
  • 'best_fitness': Best fitness value
  • 'convergence': Convergence history
  • 'execution_time': Execution time

Example:

from EvoloPy import run_optimizer
result = run_optimizer("PSO", "F1", population_size=50, iterations=100)
print(f"Best fitness: {result['best_fitness']}")
print(f"Execution time: {result['execution_time']} seconds")

run_multiple_optimizers(optimizers, objective_funcs, **kwargs)

Run multiple optimizers on multiple objective functions.

Parameters:

• optimizers (List[str]): List of optimizer names
• objective_funcs (List[str]): List of benchmark function names
• lb (float): Lower bound for variables (default: -100)
• ub (float): Upper bound for variables (default: 100)
• dim (int): Problem dimension (default: 30)
• population_size (int): Size of the population (default: 30)
• iterations (int): Maximum number of iterations (default: 50)
• num_runs (int): Number of independent runs (default: 1)
• export_results (bool): Whether to export average results (default: True)
• export_details (bool): Whether to export detailed results (default: False)
• export_convergence (bool): Whether to export convergence plots (default: True)
• export_boxplot (bool): Whether to export boxplots (default: True)
• results_directory (str, optional): Directory to save results

Returns:

• Dict[str, Dict[str, Dict[str, Any]]]: Nested dictionary of results:
  • {optimizer_name: {objective_name: {result_data}}}

Example:

from EvoloPy import run_multiple_optimizers
results = run_multiple_optimizers(
    optimizers=["PSO", "GWO"], 
    objective_funcs=["F1", "F5"],
    population_size=30,
    iterations=50
)
# Access specific results
for opt_name, opt_results in results.items():
    for func_name, func_results in opt_results.items():
        print(f"{opt_name} on {func_name}: {func_results}")

Traditional Interface: optimizer.py

from EvoloPy.optimizer import run

run(optimizer, objectivefunc, NumOfRuns, params, export_flags)

Parameters:

• optimizer: List of optimizer names to use
• objectivefunc: List of benchmark function names to optimize
• NumOfRuns: Number of independent runs for statistical analysis
• params: Dictionary containing "PopulationSize" and "Iterations"
• export_flags: Dictionary with export configuration flags

Individual Optimizers

Each optimizer follows the same interface:

from EvoloPy.optimizers import PSO

result = PSO.PSO(objf, lb, ub, dim, PopSize, iters)

Parameters:

• objf: Objective function to minimize
• lb: Lower bounds for variables (scalar or list)
• ub: Upper bounds for variables (scalar or list)
• dim: Problem dimension
• PopSize: Population size
• iters: Maximum iterations

Returns:

• result: Solution object containing best solution and metadata

Command-Line Interface

EvoloPy provides a command-line interface (CLI) for running optimizations without writing Python code.

Basic Usage

# List all available optimizers and benchmark functions
evolopy-run --list

# Run PSO on F1 benchmark
evolopy-run --optimizer PSO --function F1 --iterations 100 --pop-size 50

# Run multiple optimizers on multiple benchmarks
evolopy-run --optimizer PSO,GWO,MVO --function F1,F5 --multi --output results.json

CLI Options

• --optimizer, -o: Optimizer to use (comma-separated for multiple)
• --function, -f: Objective function to optimize (comma-separated for multiple)
• --pop-size, -p: Population size (default: 30)
• --iterations, -i: Number of iterations (default: 50)
• --dim, -d: Problem dimension (default: 10)
• --lb: Lower bound of search space (default: -100)
• --ub: Upper bound of search space (default: 100)
• --runs, -r: Number of independent runs (default: 1)
• --output: Output file to save results (default: results.json)
• --list: List available optimizers and benchmark functions
• --multi: Run multiple optimizers and/or functions (with comma-separated lists)

Example Projects

• Hyperparameter Tuning: Use EvoloPy to optimize machine learning model hyperparameters
• Engineering Design: Solve complex engineering optimization problems
• Feature Selection: Select optimal features for classification tasks

Recent Improvements

EvoloPy has undergone significant improvements in version 2, transforming it into a more functional and Pythonic library:

1. Enhanced Package Structure

• Improved import system for easier access to components
• Better organization of modules and functions

2. New API Module (api.py)

• High-level functions with intuitive interfaces
• Better return values instead of side effects
• Type hints for better IDE support and code completion

3. Command-Line Interface (cli.py)

• Run optimizations directly from the terminal
• Support for single or multiple optimizers and benchmarks
• Export results to JSON files

4. Code Quality Improvements

• Vectorized operations for better performance
• Comprehensive docstrings with examples
• Type hints throughout the codebase

5. Enhanced Documentation

• Better docstrings with examples for all functions
• Cross-references between related components
• Clear parameter descriptions

6. Standardized Return Values

• Consistent return structures across all functions
• Easy access to results in a programmatic way

7. Import System Enhancements

• Direct imports for all optimizers
• Dynamic optimizer selection via dictionary
• Top-level imports for common functions

Contributing

• Issue Tracker: https://github.com/7ossam81/EvoloPy/issues
• Source Code: https://github.com/7ossam81/EvoloPy
• Pull Requests: We welcome contributions! Please follow our contribution guidelines

Publications

For more information about EvoloPy, please refer to our paper:

Faris, H., Aljarah, I., Mirjalili, S., Castillo, P. A., & Guervós, J. J. M. (2016). EvoloPy: An Open-source Nature-inspired Optimization Framework in Python. In IJCCI (ECTA) (pp. 171-177). https://www.scitepress.org/Papers/2016/60482/60482.pdf

Please include the following related citations:

• Qaddoura, R., Faris, H., Aljarah, I., & Castillo, P. A. (2020). EvoCluster: An Open-Source Nature-Inspired Optimization Clustering Framework in Python. In International Conference on the Applications of Evolutionary Computation (pp. 20-36). Springer, Cham.
• Abu Khurma, R., Aljarah, I., Sharieh, A., & Mirjalili, S. (2020). Evolopy-fs: An Open-Source Nature-Inspired Optimization Framework in Python for Feature Selection. In Evolutionary Machine Learning Techniques (pp. 131-173). Springer.

Cite Us

If you use EvoloPy in your research, please cite:

@inproceedings{faris2016evolopy,
  title={EvoloPy: An Open-source Nature-inspired Optimization Framework in Python},
  author={Faris, Hossam and Aljarah, Ibrahim and Mirjalili, Seyedali and Castillo, Pedro A and Guervós, Juan Julián Merelo},
  booktitle={IJCCI (ECTA)},
  pages={171--177},
  year={2016}
}

License

EvoloPy is licensed under the Apache License 2.0. See the LICENSE.txt file for details.