PySwarms Documentation

PySwarms is a research toolkit for Particle Swarm Optimization (PSO) that includes several key features for both practitioners and researchers:

• Standard PSO Algorithms: Native numpy-based implementations of classic global-best PSO, local-best PSO, and binary PSO for discrete optimization.
• Built-in Objective Functions: A collection of single-objective functions (e.g., sphere, Beale, and Rastrigin functions) for testing optimizers.
• Visualization: A matplotlib-based plotting environment for visualizing costs and animating swarms in both 2D and 3D.
• Hyperparameter Tuning: Tools for performing random and grid search to optimize hyperparameters that control swarm behavior.
• Extensibility: Base classes designed for implementing custom single-objective optimizers.

The pyswarms.utils module provides various tools to assist in the optimization process. These utilities are organized into several submodules based on their functionality:

• Decorators (pyswarms.utils.decorators): Tools for modifying or wrapping functions.
• Functions (pyswarms.utils.functions): Includes benchmark objective functions for testing.
• Plotters (pyswarms.utils.plotters): Functionalities for visualizing optimization results.
• Reporter (pyswarms.utils.reporter): Tools for reporting optimization progress or results.
• Search (pyswarms.utils.search): Utilities for hyperparameter search to optimize the PSO configuration itself.

PySwarms provides off-the-shelf implementations of standard optimization algorithms, including classic variants like global-best and local-best. These are designed for quick-and-easy optimization problems. The optimizers are organized into two main categories:

1. Single-objective optimizers: Found in pyswarms.single.
2. Discrete optimizers: Found in pyswarms.discrete.

Particle Swarm Optimization (PSO) is a computational method that emulates the social behavior of groups (swarms), such as birds or fish, to find the global optimum of a function.

In PSO:

• Particles: Represent individual candidate solutions scattered throughout the search space.
• Swarm: The collective group of particles.
• Global Optimum: The 'treasure' or target value being searched for.

Particles move through the search space based on two main influences:

1. Cognitive desire: The particle's tendency to search individually based on its own experience.
2. Social influence: The collective action of the group or its neighbors, where particles move towards the best-known positions found by the swarm.

A key advantage of PSO is that it is a gradient-free optimizer, meaning the objective functions being optimized do not need to be differentiable.

PySwarms provides several Particle Swarm Optimization (PSO) algorithms for continuous search spaces. You can choose between different topologies depending on how particles interact:

• pyswarms.single.global_best: A classic global-best PSO with a star-topology. Each particle compares its performance against the single best-performing particle in the entire swarm.
• pyswarms.single.local_best: A classic local-best PSO with a ring-topology. Each particle only compares itself with its nearest neighbors based on a distance metric.
• pyswarms.single.general_optimizer: A flexible PSO that allows for custom topologies. You can pass any topology defined in the pyswarms.backend module as an argument.

The pyswarms.backend module serves as the core engine of the library. It provides the primitive methods and classes required to build custom swarm implementations. High-level Particle Swarm Optimization (PSO) algorithms provided by the library, such as GlobalBestPSO and LocalBestPSO, are constructed using these backend components. Developers looking to extend the library or create specialized swarm behaviors should interact with the following sub-modules:

• pyswarms.backend: Core primitives.
• pyswarms.handlers: Logic for handling swarm updates and constraints.
• pyswarms.topology: Definitions for how particles communicate (e.g., global vs. local topologies).
• pyswarms.swarms: Implementation of swarm structures.

The pyswarms.topology package provides various swarm topology implementations that can be used to build custom swarm algorithms. A topology defines how particles interact and share information within a swarm. Specifically, a topology implementation is capable of:

• Determining the best particle in a given swarm.
• Computing the next position based on the current swarm position.
• Computing velocities based on a specific swarm configuration.

To implement a custom swarm algorithm, you can bypass the high-level API and write your own optimization loop using the pyswarms.backend module. This approach requires you to manually manage the interaction between two core components: the Swarm class and a Topology class.

In each iteration of your loop, you retrieve the current state from the Swarm instance and update its attributes using methods provided by a Topology class or the pyswarms.backend.operators module. This allows for a highly flexible, black-box implementation of different swarm behaviors.

PySwarms is designed to balance ease-of-use with ease-of-experimentation. To ensure repeatability and a consistent framework, the library follows specific data conventions for swarm representations:

• Swarm Representation: A swarm $\mathcal{S}$ is defined as an $m \times n$ matrix, where $m$ is the number of particles and $n$ is the number of dimensions in the search space.
• Fitness Representation: Fitness is expressed as an $m$-dimensional array, containing one value for each particle.

This convention allows the library to provide a high-level declarative interface while maintaining a consistent API for custom implementations.