🔥 Clustered Firefly Algorithm (CFA)

An open-source implementation of the Clustered Firefly Algorithm (CFA) —
a variant of the classic Firefly Algorithm enhanced with KMeans clustering
and adaptive population control to balance exploration and exploitation
in continuous optimization problems.

---

⚙️ Description of the algorithm

The Clustered Firefly Algorithm (CFA) extends the classic Firefly Algorithm (FA) to improve computational efficiency while maintaining strong global search performance.

In the original FA, each firefly compares itself with every other firefly in each generation, resulting in an O(n^2) time complexity, where n is the number of fireflies. This can be costly when the objective function is time consuming. CFA mitigates this by applying k-means clustering to group fireflies dynamically and by dividing their movement into local and global phases.

Local movement: Each firefly moves only toward brighter fireflies within its own cluster, following the same movement rule as the original FA.

Global movement: Fireflies may also move toward the centroids of other clusters if those clusters have a higher average brightness (objective value). The movement toward a centroid is scaled by the cluster size, giving more influence to larger, more promising regions.

This modification reduces comparisons to O(n^(3/2)) when a cluster size of sqrt(n) is assumed.

A more detailed description of the algorithm will be provided in a future research article, as this work is still in progress.

---

🌟 Example Visualization

Below is an example of the algorithm optimizing the Schwefel function.
Fireflies explore the search space and gradually converge toward the global optimum.

---

🚀 Features

• 🔥 Continuous Firefly Algorithm for global optimization
• 🧩 KMeans-based clustering to dynamically group fireflies
• 📉 Adaptive population control for efficiency
• ⚙️ Adjustable randomness (alpha) and absorption (gamma)
• 🧪 Reproducible results with random seeds
• 🛑 Early termination via evaluation limits

---

🧰 Installation

Clone and install in editable (development) mode:

git clone https://github.com/flenji/clustered-firefly-algorithm.git
cd clustered-firefly-algorithm
pip install -e . 

Or install dependencies manually using:

pip install -r requirements.txt

(These are the versions that have been tested and confirmed to work with this implementation. Newer versions will likely work as well.)

Or manually like this:

pip install numpy scipy scikit-learn matplotlib

---

🧪 Basic Usage

Here's how to use CFA for optimization, an example script can be found in the examples folder: basic_usage.py:

import numpy as np
from clustered_firefly.algorithm import ClusteredFireflyAlgorithm

# Example objective function (Sphere)
def sphere(x):
    return np.sum(np.square(x))

# Parameter bounds
bounds = {"x1": (-5, 5), "x2": (-5, 5)}

# Initialize CFA
cfa = ClusteredFireflyAlgorithm(
    objective_function=sphere,
    parameter_bounds=bounds,
    maximize=False,       # Set True to maximize instead
    n_fireflies=20,
    n_generations=50,
    seed=42
)

# Run optimization
best_solution, best_value, _ = cfa.optimize()

print("Best solution:", best_solution)
print("Best objective value:", best_value) 

🧠 API Overview

The ClusteredFireflyAlgorithm class contains the following key methods:

Method	Description
optimize()	Runs the optimization loop over all generations. Returns the best solution, its objective value, and the final firefly positions.
_eval(x)	Internal evaluation function — computes the objective value and updates the evaluation counter.
cluster_fireflies()	Groups fireflies into clusters using KMeans to balance exploration and exploitation.
move_fireflies()	Updates the position of each firefly based on intensity and distance to others.
update_alpha()	Decreases the randomness factor (alpha) over time for convergence.
update_gamma()	Gradually adjusts the light absorption coefficient (gamma).
reduce_population()	Reduces the population size dynamically if population control is enabled.

All configuration is handled through the constructor.
Typical usage involves creating a ClusteredFireflyAlgorithm instance and calling optimize().

Constructor Parameters

For a full list of configurable parameters (e.g., alpha, gamma, maximize, population_control, etc.), see the class docstring in algorithm.py.

Visualization

A basic script for visualizing the clustered Firefly Algorithm on the 2-dimensional Schwefel-function can be found in the examples folder too: visualization.py

Note that to generate the script, one has to install imageio as well:

pip install imageio