pagmo2 Documentation

pagmo is a C++ scientific library designed for massively parallel optimization. It provides a unified interface to various optimization algorithms and problems, facilitating easy deployment in massively parallel environments.

Key Capabilities:

• Algorithm Variety: Combines bio-inspired and evolutionary algorithms with state-of-the-art optimization methods (e.g., Simplex, SQP, and interior point methods).
• Algorithmic Cooperation: Supports building 'super-algorithms' that exploit cooperation via an asynchronous, generalized island model.
• Problem Versatility: Capable of solving:
  • Constrained and unconstrained problems
  • Single-objective and multi-objective problems
  • Continuous and integer optimization
  • Stochastic and deterministic problems
• Research Support: Designed to allow researchers to implement and compare novel algorithms against established state-of-the-art implementations.

Python Support

If you prefer working in Python, you can use pygmo, which provides Python bindings for pagmo.

The pagmo2 C++ API is built around several core abstractions that allow you to define optimization problems, select algorithms, and manage populations across different execution models. The primary building blocks include:

• Problem: Defines the objective function(s), constraints, and variable bounds.
• Algorithm: The optimization method used to search the problem space.
• Population: A collection of individuals (solutions) being evolved.
• Island: An execution unit where an algorithm operates on a population.
• Archipelago: A collection of islands that can interact via topologies.
• Topology: Defines how islands communicate and exchange individuals.
• BFE (Batch Evaluator): Handles the evaluation of multiple individuals in parallel or in batches.
• R_policy (Replacement Policy): Determines how new individuals replace existing ones in a population.
• S_policy (Selection Policy): Determines how individuals are selected for reproduction or further processing.
• Types: Fundamental type definitions used throughout the library.

To define a User-Defined Replacement Policy (UDRP) in pagmo, your class must satisfy the requirements of the has_replace type trait. Specifically, it must provide a replace member function with the following signature:

individuals_group_t replace(
    const individuals_group_t &, 
    const vector_double::size_type &, 
    const vector_double::size_type &, 
    const vector_double::size_type &, 
    const vector_double::size_type &, 
    const vector_double::size_type &, 
    const vector_double &, 
    const individuals_group_t &
) const;

Additionally, to be recognized as a valid UDRP by the is_udrp type trait, the class must:

1. Not be a reference or cv-qualified.
2. Be destructible.
3. Be default, copy, and move constructible.
4. Satisfy pagmo::has_replace.

// Example skeleton of a valid replacement policy
class MyReplacementPolicy {
public:
    // Required signature for has_replace
    pagmo::individuals_group_t replace(
        const pagmo::individuals_group_t &, 
        const pagmo::vector_double::size_type &, 
        const pagmo::vector_double::size_type &, 
        const pagmo::vector_double::size_type &, 
        const pagmo::vector_double::size_type &, 
        const pagmo::vector_double::size_type &, 
        const pagmo::vector_double &, 
        const pagmo::individuals_group_t &
    ) const {
        // Implementation logic here
        return {}; 
    }

    // Must be default, copy, and move constructible
    MyReplacementPolicy() = default;
    MyReplacementPolicy(const MyReplacementPolicy&) = default;
    MyReplacementPolicy(MyReplacementPolicy&&) = default;
    ~MyReplacementPolicy() = default;
};

A replacement policy determines how migrants from an archipelago replace individuals in an existing population. To create a custom policy, you must implement a User-Defined Replacement Policy (UDRP) class.

Requirements

Your UDRP class must implement the following:

1. replace() member function: This contains the core logic for selecting which individuals to keep and which migrants to admit.
2. Constructibility: The class must be default, copy, and move constructible.

replace() Signature

individuals_group_t replace(
    const individuals_group_t &inds, 
    const vector_double::size_type &nx, 
    const vector_double::size_type &nix, 
    const vector_double::size_type &nobj, 
    const vector_double::size_type &nec, 
    const vector_double::size_type &nic, 
    const vector_double &tol, 
    const individuals_group_t &mig
) const;

Parameters

• inds: The original group of individuals (individuals_group_t).
• nx: Total dimension of the problem.
• nix: Integral dimension.
• nobj: Number of objectives.
• nec: Number of equality constraints.
• nic: Number of inequality constraints.
• tol: Vector of constraint tolerances.
• mig: The set of candidate migrants (individuals_group_t).

Optional Functions

You can also implement these to provide metadata:

• std::string get_name() const
• std::string get_extra_info() const

Thread Safety Warning

Replacement policies are used in asynchronous operations. The replace() function may be invoked concurrently with other member functions. You are responsible for ensuring your UDRP is thread-safe.

// Example skeleton of a UDRP
class MyReplacementPolicy {
public:
    individuals_group_t replace(
        const pagmo::individuals_group_t &inds, 
        const pagmo::vector_double::size_type &nx, 
        const pagmo::vector_double::size_type &nix, 
        const pagmo::vector_double::size_type &nobj, 
        const pagmo::vector_double::size_type &nec, 
        const pagmo::vector_double::size_type &nic, 
        const pagmo::vector_double &tol, 
        const pagmo::individuals_group_t &mig
    ) const {
        // Implementation logic here
        return inds; 
    }
};

The pagmo::free_form class is a User-Defined Topology (UDT) that allows for free manipulation of vertices and edges in a graph. It extends pagmo::base_bgl_topology and is useful when you need to build a topology incrementally or from an existing Boost Graph Library (BGL) graph.

Key Features

• Incremental Construction: Use push_back() to add new vertices without connections.
• BGL Integration: Initialize the topology directly from a pagmo::bgl_graph_t.
• Topology Conversion: You can create a free_form topology by copying an existing pagmo::topology or another UDT using its constructor, which internally calls to_bgl() to extract the graph representation.

Important Constraints

• When initializing from a bgl_graph_t, all edge weights must be within the range [0, 1]. If an edge weight is outside this range, a std::invalid_argument exception is thrown.

#include <pagmo/topologies/free_form.hpp>

// Example usage patterns:

// 1. Default constructor (empty topology)
pagmo::free_form f;

// 2. Add a vertex without connections
f.push_back();

// 3. Initialize from an existing BGL graph
pagmo::bgl_graph_t my_graph = ...;
pagmo::free_form f_from_graph(my_graph);

// 4. Initialize from another topology
pagmo::topology t = ...;
pagmo::free_form f_from_topo(t);

In pagmo, a User-Defined Problem (UDP) is a regular C++ class that implements specific member functions to represent an optimization problem. You do not need to inherit from any base class.

To create a basic UDP, your class must implement:

1. fitness(const pagmo::vector_double &dv) const: Computes the objective function value(s). It returns a pagmo::vector_double (an alias for std::vector<double>).
2. get_bounds() const: Returns the box bounds of the problem as a std::pair of pagmo::vector_double (lower and upper bounds). The size of these vectors implicitly defines the problem's dimension.

Example of a minimal UDP:

#include <pagmo/vector_double.hpp>
#include <utility>

using namespace pagmo;

class my_problem {
public:
    vector_double fitness(const vector_double &dv) const {
        return {dv[0] * dv[3] * (dv[0] + dv[1] + dv[2]) + dv[2]};
    }

    std::pair<vector_double, vector_double> get_bounds() const {
        return {{1., 1., 1., 1.}, {5., 5., 5., 5. }};
    }
};

The pagmo::base_bgl_topology class provides the building blocks for creating User-Defined Topologies (UDTs) based on the Boost Graph Library (BGL).

Important Implementation Note: base_bgl_topology is not a complete UDT on its own. To satisfy the requirements of a UDT (as defined by pagmo::is_udt), you must implement the mandatory push_back() member function in your derived class.

Key Features:

• Thread Safety: Any member function can be invoked concurrently with any other member function.
• BGL Integration: It wraps a BGL graph, allowing you to leverage Boost's graph algorithms.
• Deep Copying: Copy construction and assignment perform deep copies of the underlying graph.

#include <pagmo/topologies/base_bgl_topology.hpp>

class MyCustomTopology : public pagmo::base_bgl_topology {
public:
    // You MUST implement push_back() to make this a valid UDT
    void push_back(const pagmo::vector_double& x) {
        // Implementation logic here
    }

    // Other methods from base_bgl_topology are available
};