Archipelago#

#include <pagmo/archipelago.hpp>

class archipelago#

Archipelago.

../../_images/archi_no_text.png

An archipelago is a collection of island objects connected by a topology. The islands in the archipelago can exchange individuals (i.e., candidate solutions) via a process called migration. The individuals migrate across the routes described by the topology, and the islands’ replacement and selection policies (see r_policy and s_policy) establish how individuals are replaced in and selected from the islands’ populations.

The interface of archipelago mirrors partially the interface of island: the evolution is initiated by a call to evolve(), and at any time the user can query the state of the archipelago and access its island members. The user can explicitly wait for pending evolutions to conclude by calling the wait() and wait_check() methods. The status of ongoing evolutions in the archipelago can be queried via status().

Warning

The only operations allowed on a moved-from pagmo::archipelago are destruction and assignment. Any other operation will result in undefined behaviour.

Public Types

using size_type = size_type_implementation#

The size type of the archipelago.

This is an unsigned integer type used to represent the number of islands in the archipelago.

using migrants_db_t = std::vector<individuals_group_t>#

Database of migrants.

During the evolution of an archipelago, islands will periodically store the individuals selected for migration in a migrant database. This is a vector of individuals_group_t whose size is equal to the number of islands in the archipelago, and which contains the current candidate outgoing migrants for each island.

using migration_entry_t = std::tuple<double, unsigned long long, vector_double, vector_double, size_type, size_type>#

Entry for the migration log.

Each time an individual migrates from an island (the source) to another (the destination), an entry will be added to the migration log. The entry is a tuple containing:

a timestamp of the migration,
the ID of the individual that migrated,
the decision and fitness vectors of the individual that migrated,
the indices of the source and destination islands.

using migration_log_t = std::vector<migration_entry_t>#

Migration log.

The migration log is a collection of migration_entry_t entries.

using iterator = iterator_implementation#

Mutable iterator.

Dereferencing a mutable iterator will yield a reference to an island within the archipelago.

Warning

Mutable iterators are provided solely in order to allow calling non-const methods on the islands. Assigning an island via a mutable iterator will result in undefined behaviour.

using const_iterator = const_iterator_implementation#

Const iterator.

Dereferencing a const iterator will yield a const reference to an island within the archipelago.

Public Functions

archipelago()#

Default constructor.

The default constructor will initialise an empty archipelago with a default-constructed (i.e., unconnected) topology, a point-to-point migration_type and a preserve migrant_handling policy.

archipelago(const archipelago&)#

Copy constructor.

The copy constructor will perform a deep copy of other.

Parameters: other – the archipelago that will be copied.
Throws: unspecified – any exception thrown by the public interface of pagmo::archipelago.

archipelago(archipelago&&) noexcept#

Move constructor.

The move constructor will wait for any ongoing evolution in other to finish and it will then transfer the state of other into this. After the move, other is left in a state which is assignable and destructible.

Parameters: other – the archipelago that will be moved.

template<typename Topo, topo_ctor_enabler<Topo> = 0> inline explicit archipelago(Topo &&t)#

Constructor from a topology.

This constructor is equivalent to the default constructor, but it will additionally allow to select the archipelago’s topology.

Note

This constructor is enabled only if t is not an archipelago and it can be used to construct a pagmo::topology.

Parameters: t – the desired (user-defined) topology.
Throws: unspecified – any exception thrown by the invoked topology constructor.

template<typename ...Args, n_ctor_enabler<const Args&...> = 0> inline explicit archipelago(size_type n, const Args&... args)#

Constructor from n islands.

This constructor will first initialise an empty archipelago with a default-constructed topology, and then forward n times the input arguments args to the push_back() method, thus creating and inserting n new islands into the archipelago.

If, however, the parameter pack args contains an argument which would be interpreted as a seed by the invoked island constructor, then this seed will be used to initialise a random number generator that in turn will be used to generate the seeds of populations of the islands that will be created within the archipelago. In other words, passing a seed argument to this constructor will not generate n islands with the same seed, but n islands whose population seeds have been randomly generated starting from the supplied seed argument.

Note

This constructor is enabled only if the parameter pack args can be used to construct a pagmo::island.

Parameters

n – the desired number of islands.
args – the arguments that will be used for the construction of each island.

Throws

unspecified – any exception thrown by archipelago::push_back().

template<typename Topo, typename ...Args, topo_n_ctor_enabler<Topo, const Args&...> = 0> inline explicit archipelago(Topo &&t, size_type n, const Args&... args)#

Constructor from a topology and n islands.

This constructor is equivalent to the previous one, but it will additionally allow to select the archipelago’s topology.

Note

This constructor is enabled only if t can be used to construct a topology and if the parameter pack args can be used to construct a island.

Parameters

t – the desired (user-defined) topology.
n – the desired number of islands.
args – the arguments that will be used for the construction of each island.

Throws

unspecified – any exception thrown by the previous constructor or by the constructor from a topology.

archipelago &operator=(const archipelago&)#

Copy assignment.

Copy assignment is implemented as copy construction followed by a move assignment.

Parameters: other – the assignment argument.
Throws: unspecified – any exception thrown by the copy constructor.
Returns: a reference to this.

archipelago &operator=(archipelago&&) noexcept#

Move assignment.

Move assignment will transfer the state of other into this, after any ongoing evolution in this and other has finished. After the move, other is left in a state which is assignable and destructible.

Parameters: other – the assignment argument.
Returns: a reference to this.

~archipelago()#

Destructor.

The destructor will call archipelago::wait_check() internally, ignoring any exception that might be thrown, and run checks in debug mode.

island &operator[](size_type)#

Mutable island access.

This subscript operator can be used to access the i-th island of the archipelago (that is, the i-th island that was inserted via push_back()). References returned by this method are valid even after a push_back() invocation. Assignment and destruction of the archipelago will invalidate island references obtained via this method.

Warning

The mutable version of the subscript operator exists solely to allow calling non-const methods on the islands. Assigning an island via a reference obtained through this operator will result in undefined behaviour.

Parameters: i – the index of the island to be accessed.
Throws: std::out_of_range – if i is not less than the size of the archipelago.
Returns: a reference to the i-th island of the archipelago.

const island &operator[](size_type) const#

Const island access.

Parameters: i – the index of the island to be accessed.
Throws: std::out_of_range – if i is not less than the size of the archipelago.
Returns: a const reference to the i-th island of the archipelago.

size_type size() const#

Size.

Returns: the number of islands in the archipelago.

template<typename ...Args, push_back_enabler<Args&&...> = 0> inline void push_back(Args&&... args)#

Add a new island.

This method will construct an island from the supplied arguments and add it to the archipelago. Islands are added at the end of the archipelago (that is, the new island will have an index equal to the value of size() before the call to this method). pagmo::topology::push_back() will also be called on the topology associated to this archipelago, so that the addition of a new island to the archipelago is mirrored by the addition of a new vertex to the topology.

Note

This method is enabled only if the parameter pack args can be used to construct a pagmo::island.

Parameters

args – the arguments that will be used for the construction of the island.

Throws

std::overflow_error – if the size of the archipelago is greater than an implementation-defined maximum.
unspecified – any exception thrown by:
- memory allocation errors,
- threading primitives,
- pagmo::topology::push_back(),
- the invoked constructor of pagmo::island.

void evolve(unsigned n = 1)#

Evolve archipelago.

This method will call island::evolve() on all the islands of the archipelago. The input parameter n will be passed to the invocations of island::evolve() for each island. archipelago::status() can be used to query the status of the asynchronous operations in the archipelago.

Parameters: n – the parameter that will be passed to island::evolve().
Throws: unspecified – any exception thrown by island::evolve().

void wait() noexcept#

Block until all evolutions have finished.

This method will call island::wait() on all the islands of the archipelago. Exceptions thrown by island evolutions can be re-raised via wait_check(): they will not be re-thrown by this method. Also, contrary to wait_check(), this method will not reset the status of the archipelago: after a call to wait(), status() will always return either evolve_status::idle or evolve_status::idle_error.

void wait_check()#

Block until all evolutions have finished and raise the first exception that was encountered.

This method will call island::wait_check() on all the islands of the archipelago (following the order in which the islands were inserted into the archipelago). The first exception raised by island::wait_check() will be re-raised by this method, and all the exceptions thrown by the other calls to island::wait_check() will be ignored.

Note that wait_check() resets the status of the archipelago: after a call to wait_check(), status() will always return evolve_status::idle.

Throws: unspecified – any exception thrown by any evolution task queued in the archipelago’s islands.

evolve_status status() const#

Status of the archipelago.

This method will return a pagmo::evolve_status flag indicating the current status of asynchronous operations in the archipelago. The flag will be:

evolve_status::idle if, for all the islands in the archipelago, island::status() returns evolve_status::idle;
evolve_status::busy if, for at least one island in the archipelago, island::status() returns evolve_status::busy, and for no island island::status() returns an error status;
evolve_status::idle_error if no island in the archipelago is busy and for at least one island island::status() returns evolve_status::idle_error;
evolve_status::busy_error if, for at least one island in the archipelago, island::status() returns an error status and at least one island is busy.

Note that after a call to wait_check(), status() will always return evolve_status::idle, and after a call to wait(), status() will always return either evolve_status::idle or evolve_status::idle_error.

Returns: a flag indicating the current status of asynchronous operations in the archipelago.

inline iterator begin()#

Mutable begin iterator.

This method will return a mutable iterator pointing to the beginning of the internal island container. That is, the returned iterator will either point to the first island of the archipelago (if size() is nonzero) or it will be the same iterator returned by archipelago::end() (is size() is zero).

Adding an island to the archipelago will invalidate all existing iterators.

Warning

Mutable iterators are provided solely in order to allow calling non-const methods on the islands. Assigning an island via a mutable iterator will result in undefined behaviour.

Returns: a mutable iterator to the beginning of the island container.

inline iterator end()#

Mutable end iterator.

This method will return a mutable iterator pointing to the end of the internal island container.

Adding an island to the archipelago will invalidate all existing iterators.

Warning

Mutable iterators are provided solely in order to allow calling non-const methods on the islands. Assigning an island via a mutable iterator will result in undefined behaviour.

Returns: a mutable iterator to the end of the island container.

inline const_iterator begin() const#

Const begin iterator.

This method will return a const iterator pointing to the beginning of the internal island container. That is, the returned iterator will either point to the first island of the archipelago (if size() is nonzero) or it will be the same iterator returned by archipelago::end() const (is size() is zero).

Adding an island to the archipelago will invalidate all existing iterators.

Returns: a const iterator to the beginning of the island container.

inline const_iterator end() const#

Const end iterator.

This method will return a const iterator pointing to the end of the internal island container.

Adding an island to the archipelago will invalidate all existing iterators.

Returns: a const iterator to the end of the island container.

std::vector<vector_double> get_champions_f() const#

Get the fitness vectors of the islands’ champions.

Throws: unspecified – any exception thrown by population::champion_f() or by memory errors in standard containers.
Returns: a collection of the fitness vectors of the islands’ champions.

std::vector<vector_double> get_champions_x() const#

Get the decision vectors of the islands’ champions.

Throws: unspecified – any exception thrown by population::champion_x() or by memory errors in standard containers.
Returns: a collection of the decision vectors of the islands’ champions.

migration_log_t get_migration_log() const#

Get the migration log.

Each time an individual migrates from an island (the source) to another (the destination), an entry will be added to the migration log. The entry is a tuple containing:

a timestamp of the migration,
the ID of the individual that migrated,
the decision and fitness vectors of the individual that migrated,
the indices of the source and destination islands.

The migration log is a collection of migration entries.

Throws: unspecified – any exception thrown by threading primitives or by memory allocation errors.
Returns: a copy of the migration log.

migrants_db_t get_migrants_db() const#

Get the database of migrants.

Throws: unspecified – any exception thrown by threading primitives or by memory allocation errors.
Returns: a copy of the database of migrants.

void set_migrants_db(migrants_db_t)#

Set the database of migrants.

This setter allows to replace the current database of migrants with a new one.

Note that this setter will accept in input a malformed database of migrants without complaining. An invalid database of migrants will however result in exceptions being raised when migration occurs.

Parameters: mig – the new database of migrants.
Throws: unspecified – any exception thrown by threading primitives.

topology get_topology() const#

Get a copy of the topology.

Throws: unspecified – any exception thrown by copying the topology.
Returns: a copy of the topology.

void set_topology(topology)#

Set a new topology.

This function will first wait for any ongoing evolution in the archipelago to conclude, and it will then set a new topology for the archipelago.

Note that it is the user’s responsibility to ensure that the new topology is consistent with the archipelago’s properties.

Parameters: topo – the new topology.
Throws: unspecified – any exception thrown by copying the topology.

migration_type get_migration_type() const#

Get the migration type.

Returns: the migration type for this archipelago.

void set_migration_type(migration_type)#

Set a new migration type.

Parameters: mt – a new migration type for this archipelago.

migrant_handling get_migrant_handling() const#

Get the migrant handling policy.

Returns: the migrant handling policy for this archipelago.

void set_migrant_handling(migrant_handling)#

Set a new migrant handling policy.

Parameters: mh – a new migrant handling policy for this archipelago.

Types#

enum class pagmo::migration_type#

Migration type.

This enumeration represents the available migration policies in an archipelago:

with the point-to-point migration policy, during migration an island will consider individuals from only one of the connecting islands;
with the broadcast migration policy, during migration an island will consider individuals from all the connecting islands.

Values:

enumerator p2p#: Point-to-point migration.

enumerator broadcast#: Broadcast migration.

enum class pagmo::migrant_handling#

Migrant handling policy.

This enumeration represents the available migrant handling policies in an archipelago.

During migration, individuals are selected from the islands and copied into a migration database, from which they can be fetched by other islands. This policy establishes what happens to the migrants in the database after they have been fetched by a destination island:

with the preserve policy, a copy of the candidate migrants remains in the database;
with the evict policy, the candidate migrants are removed from the database.

Values:

enumerator preserve#: Preserve migrants in the database.

enumerator evict#: Evict migrants from the database.

Archipelago

Contents

Archipelago#

Types#