Island#

#include <pagmo/island.hpp>

class island#

Island class.

../../_images/island_no_text.png

In the pagmo jargon, an island is a class that encapsulates the following entities:

Through the UDI, the island class manages the asynchronous evolution (or optimisation) of its population via the algorithm’s evolve() method. Depending on the UDI, the evolution might take place in a separate thread (e.g., if the UDI is a thread_island), in a separate process (see fork_island) or even in a separate machine. The evolution is always asynchronous (i.e., running in the “background”) and it is initiated by a call to the evolve() method. At any time the user can query the state of the island and fetch its internal data 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 island can be queried via status().

The replacement and selection policies are used when the island is part of an archipelago. They establish how individuals are selected and replaced from the island when migration across islands occurs within the archipelago. If the island is not part of an archipelago, the replacement and selection policies play no role.

Typically, pagmo users will employ an already-available UDI (such as thread_island) in conjunction with this class, but advanced users can implement their own UDI types. A user-defined island must implement the following method:

void run_evolve(island &) const;

The run_evolve() method of the UDI will use the input island algorithm’s algorithm::evolve() method to evolve the input island’s pagmo::population. Once the evolution is finished, run_evolve() will then replace the population and the algorithm of the input island with, respectively, the evolved population and the algorithm used for the evolution.

In addition to the mandatory run_evolve() method, a UDI may implement the following optional methods: 

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

See the documentation of the corresponding methods in this class for details on how the optional methods in the UDI are used by pagmo::island.

Note that, due to the asynchronous nature of pagmo::island, a UDI has certain requirements regarding thread safety. Specifically, run_evolve() is always called in a separate thread of execution, and consequently:

  • multiple UDI objects may be calling their own run_evolve() method concurrently,

  • in a specific UDI object, any method from the public API of the UDI may be called while run_evolve() is running concurrently in another thread (the only exception being the destructor, which will wait for the end of any ongoing evolution before taking any action). Thus, UDI writers must ensure that actions such as copying the UDI, calling the optional methods (such as get_name()), etc. can be safely performed while the island is evolving.

Warning

The only operations allowed on a moved-from pagmo::island are destruction, assignment, and the invocation of the is_valid() member function. Any other operation will result in undefined behaviour.

Public Functions

island()#

Default constructor.

The default constructor will initialise an island containing a UDI of type thread_island, and default-constructed algorithm, population and replacement/selection policies.

Throws

unspecified – any exception thrown by any invoked constructor or by memory allocation failures.

island(const island&)#

Copy constructor.

The copy constructor will initialise an island containing a copy of other’s UDI, population, algorithm and replacement/selection policies. It is safe to call this constructor while other is evolving.

Parameters

other – the island tht will be copied.

Throws

unspecified – any exception thrown by:

island(island&&) noexcept#

Move constructor.

The move constructor will transfer the state of other into this, after any ongoing evolution in other is finished.

Parameters

other – the island that will be moved.

template<typename Algo, typename Pop, algo_pop_enabler<Algo, Pop> = 0>
inline explicit island(Algo &&a, Pop &&p)#

Constructor from algorithm and population.

This constructor will use a to construct the internal algorithm, and p to construct the internal population. The UDI type will be inferred from the thread_safety properties of the algorithm and the population’s problem. Specifically:

  • if both the algorithm and the problem provide at least the basic thread_safety guarantee, or if the current platform is not POSIX, then the UDI type will be thread_island;

  • otherwise, the UDI type will be fork_island.

Note that on non-POSIX platforms, thread_island will always be selected as the UDI type, but island evolutions will fail if the algorithm and/or problem do not provide at least the basic thread_safety guarantee.

The replacement/selection policies will be default-constructed.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm and p is an instance of pagmo::population.

Parameters

  • a – the input algorithm.

  • p – the input population.

Throws

unspecified – any exception thrown by:

template<typename Algo, typename Pop, typename RPol, typename SPol, algo_pop_pol_enabler<Algo, Pop, RPol, SPol> = 0>
inline explicit island(Algo &&a, Pop &&p, RPol &&r, SPol &&s)#

Constructor from algorithm, population and replacement/selection policies.

This constructor is equivalent to the previous one, but it additionally allows to specify the replacement and selection policies for the island.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm, p is an instance of pagmo::population, and r and s can be used to construct, respectively, a pagmo::r_policy and a pagmo::s_policy.

Parameters

  • a – the input algorithm.

  • p – the input population.

  • r – the input replacement policy.

  • s – the input selection policy.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

template<typename Isl, typename Algo, typename Pop, isl_algo_pop_enabler<Isl, Algo, Pop> = 0>
inline explicit island(Isl &&isl, Algo &&a, Pop &&p)#

Constructor from UDI, algorithm and population.

This constructor will use isl to construct the internal UDI, a to construct the internal algorithm, and p to construct the internal population.

Note

This constructor is enabled only if:

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input population.

Throws

unspecified – any exception thrown by:

template<typename Isl, typename Algo, typename Pop, typename RPol, typename SPol, isl_algo_pop_pol_enabler<Isl, Algo, Pop, RPol, SPol> = 0>
inline explicit island(Isl &&isl, Algo &&a, Pop &&p, RPol &&r, SPol &&s)#

Constructor from UDI, algorithm, population and replacement/selection policies.

This constructor is equivalent to the previous one, but it additionally allows to specify the replacement and selection policies for the island.

Note

This constructor is enabled only if:

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input population.

  • r – the input replacement policy.

  • s – the input selection policy.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

template<typename Algo, typename Prob, algo_prob_enabler<Algo, Prob> = 0>
inline explicit island(Algo &&a, Prob &&p, population::size_type size, unsigned seed = pagmo::random_device::next())#

Constructor from algorithm, problem, size and seed.

This constructor will construct a pagmo::population pop from p, size and seed, and it will then invoke island(Algo &&, Pop &&) with a and pop as arguments.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm, and p can be used to construct a pagmo::problem.

Parameters

  • a – the input algorithm.

  • p – the input problem.

  • size – the population size.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the invoked pagmo::population constructor or by island(Algo &&, Pop &&).

template<typename Algo, typename Prob, typename RPol, typename SPol, algo_prob_pol_enabler<Algo, Prob, RPol, SPol> = 0>
inline explicit island(Algo &&a, Prob &&p, population::size_type size, RPol &&r, SPol &&s, unsigned seed = pagmo::random_device::next())#

Constructor from algorithm, problem, size, replacement/selections policies and seed.

This constructor is equivalent to the previous one, but it additionally allows to specify the replacement and selection policies for the island.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, and r and s can be used to construct, respectively, a pagmo::r_policy and a pagmo::s_policy.

Parameters

  • a – the input algorithm.

  • p – the input problem.

  • size – the population size.

  • r – the input replacement policy.

  • s – the input selection policy.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

template<typename Algo, typename Prob, typename Bfe, algo_prob_bfe_enabler<Algo, Prob, Bfe> = 0>
inline explicit island(Algo &&a, Prob &&p, Bfe &&b, population::size_type size, unsigned seed = pagmo::random_device::next())#

Constructor from algorithm, problem, batch fitness evaluator, size and seed.

This constructor is equivalent to the constructor from algorithm, problem, size and seed, the only difference being that the population’s individuals will be initialised using the input bfe or UDBFE b.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, and b can be used to construct a pagmo::bfe.

Parameters

  • a – the input algorithm.

  • p – the input problem.

  • b – the input (user-defined) batch fitness evaluator.

  • size – the population size.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the invoked pagmo::population constructor or by island(Algo &&, Pop &&).

template<typename Algo, typename Prob, typename Bfe, typename RPol, typename SPol, algo_prob_bfe_pol_enabler<Algo, Prob, Bfe, RPol, SPol> = 0>
inline explicit island(Algo &&a, Prob &&p, Bfe &&b, population::size_type size, RPol &&r, SPol &&s, unsigned seed = pagmo::random_device::next())#

Constructor from algorithm, problem, batch fitness evaluator, size, replacement/selection policies and seed.

This constructor is equivalent to the previous one, but it additionally allows to specify the replacement and selection policies for the island.

Note

This constructor is enabled only if a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, b can be used to construct a pagmo::bfe, and r and s can be used to construct, respectively, a pagmo::r_policy and a pagmo::s_policy.

Parameters

  • a – the input algorithm.

  • p – the input problem.

  • b – the input (user-defined) batch fitness evaluator.

  • size – the population size.

  • r – the input replacement policy.

  • s – the input selection policy.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

template<typename Isl, typename Algo, typename Prob, isl_algo_prob_enabler<Isl, Algo, Prob> = 0>
inline explicit island(Isl &&isl, Algo &&a, Prob &&p, population::size_type size, unsigned seed = pagmo::random_device::next())#

Constructor from UDI, algorithm, problem, size and seed.

This constructor will construct a pagmo::population pop from p, size and seed, and it will then invoke island(Isl &&, Algo &&, Pop &&) with isl, a and pop as arguments.

Note

This constructor is enabled only if Isl satisfies pagmo::is_udi, a can be used to construct a pagmo::algorithm, and p can be used to construct a pagmo::problem.

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input problem.

  • size – the population size.

  • seed – the population seed.

Throws

unspecified – any exception thrown by:

template<typename Isl, typename Algo, typename Prob, typename RPol, typename SPol, isl_algo_prob_pol_enabler<Isl, Algo, Prob, RPol, SPol> = 0>
inline explicit island(Isl &&isl, Algo &&a, Prob &&p, population::size_type size, RPol &&r, SPol &&s, unsigned seed = pagmo::random_device::next())#

Constructor from UDI, algorithm, problem, size, replacement/selection policies and seed.

This constructor is equivalent to the previous one, but it additionally allows to specify the replacement and selection policies for the island.

Note

This constructor is enabled only if Isl satisfies pagmo::is_udi, a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, and r and s can be used to construct, respectively, a pagmo::r_policy and a pagmo::s_policy.

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input problem.

  • size – the population size.

  • r – the input replacement policy.

  • s – the input selection policy.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

template<typename Isl, typename Algo, typename Prob, typename Bfe, isl_algo_prob_bfe_enabler<Isl, Algo, Prob, Bfe> = 0>
inline explicit island(Isl &&isl, Algo &&a, Prob &&p, Bfe &&b, population::size_type size, unsigned seed = pagmo::random_device::next())#

Constructor from UDI, algorithm, problem, batch fitness evaluator, size and seed.

This constructor is equivalent to the constructor from UDI, algorithm, problem, size and seed, the only difference being that the population’s individuals will be initialised using the input bfe or UDBFE b.

Note

This constructor is enabled only if Isl satisfies pagmo::is_udi, a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, and b can be used to construct a pagmo::bfe.

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input problem.

  • b – the input (user-defined) batch fitness evaluator.

  • size – the population size.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the invoked pagmo::population constructor or by island(Algo &&, Pop &&).

template<typename Isl, typename Algo, typename Prob, typename Bfe, typename RPol, typename SPol, isl_algo_prob_bfe_pol_enabler<Isl, Algo, Prob, Bfe, RPol, SPol> = 0>
inline explicit island(Isl &&isl, Algo &&a, Prob &&p, Bfe &&b, population::size_type size, RPol &&r, SPol &&s, unsigned seed = pagmo::random_device::next())#

Constructor from UDI, algorithm, problem, batch fitness evaluator, size, replacement/selection policies and seed.

This constructor is equivalent to the previous one, the only difference being that the population’s individuals will be initialised using the input bfe or UDBFE b.

Note

This constructor is enabled only if Isl satisfies pagmo::is_udi, a can be used to construct a pagmo::algorithm, p can be used to construct a pagmo::problem, b can be used to construct a pagmo::bfe, and r and s can be used to construct, respectively, a pagmo::r_policy and a pagmo::s_policy.

Parameters

  • isl – the input UDI.

  • a – the input algorithm.

  • p – the input problem.

  • b – the input (user-defined) batch fitness evaluator.

  • size – the population size.

  • r – the input replacement policy.

  • s – the input selection policy.

  • seed – the population seed.

Throws

unspecified – any exception thrown by the previous constructor or by the construction of the replacement/selection policies.

~island()#

Destructor.

If the island has not been moved-from, the destructor will call island::wait_check(), ignoring any exception that might be thrown.

island &operator=(island&&) noexcept#

Move assignment.

Move assignment will transfer the state of other into this, after any ongoing evolution in this and other is finished.

Parameters

other – the island tht will be moved.

Returns

a reference to this.

island &operator=(const island&)#

Copy assignment.

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

Parameters

other – the island tht will be copied.

Throws

unspecified – any exception thrown by the copy constructor.

Returns

a reference to this.

template<typename T>
inline const T *extract() const noexcept#

Extract a const pointer to the UDI used for construction.

This method will extract a const pointer to the internal instance of the UDI. If T is not the same type as the UDI used during construction (after removal of cv and reference qualifiers), this method will return nullptr.

Note

The returned value is a raw non-owning pointer: the lifetime of the pointee is tied to the lifetime of this, and delete must never be called on the pointer.

Returns

a const pointer to the internal UDI, or nullptr if T does not correspond exactly to the original UDI type used in the constructor.

template<typename T>
inline T *extract() noexcept#

Extract a pointer to the UDI used for construction.

This method will extract a pointer to the internal instance of the UDI. If T is not the same type as the UDI used during construction (after removal of cv and reference qualifiers), this method will return nullptr.

Note

The returned value is a raw non-owning pointer: the lifetime of the pointee is tied to the lifetime of this, and delete must never be called on the pointer.

Note

The ability to extract a mutable pointer is provided only in order to allow to call non-const methods on the internal UDI instance. Assigning a new UDI via this pointer is undefined behaviour.

Returns

a pointer to the internal UDI, or nullptr if T does not correspond exactly to the original UDI type used in the constructor.

template<typename T>
inline bool is() const noexcept#

Check if the UDI used for construction is of type T.

Returns

true if the UDI used in construction is of type T, false otherwise.

void evolve(unsigned n = 1)#

Launch evolution.

This method will evolve the island’s pagmo::population using the island’s pagmo::algorithm. The evolution happens asynchronously: a call to island::evolve() will create an evolution task that will be pushed to a queue, and then return immediately. The tasks in the queue are consumed by a separate thread of execution managed by the pagmo::island object. Each task will invoke the run_evolve() method of the UDI n times consecutively to perform the actual evolution. The island’s population will be updated at the end of each run_evolve() invocation. Exceptions raised inside the tasks are stored within the island object, and can be re-raised by calling wait_check().

If the island is part of a pagmo::archipelago, then migration of individuals to/from other islands might occur. The migration algorithm consists of the following steps:

  • before invoking run_evolve() on the UDI, the island will ask the archipelago if there are candidate incoming individuals from other islands. If so, the replacement policy is invoked and the current population of the island is updated with the migrants;

  • run_evolve() is then invoked and the current population is evolved;

  • after run_evolve() has concluded, individuals are selected in the evolved population and copied into the migration database of the archipelago for future migrations.

It is possible to call this method multiple times to enqueue multiple evolution tasks, which will be consumed in a FIFO (first-in first-out) fashion. The user may call island::wait() or island::wait_check() to block until all tasks have been completed, and to fetch exceptions raised during the execution of the tasks. island::status() can be used to query the status of the asynchronous operations in the island.

Parameters

n – the number of times the run_evolve() method of the UDI will be called within the evolution task. This corresponds also to the number of times migration can happen, if the island belongs to an archipelago.

Throws

  • std::out_of_range – if the island is part of an archipelago and during migration an invalid island index is used (this can happen if the archipelago’s topology is malformed).

  • unspecified – any exception thrown by:

    • threading primitives,

    • memory allocation errors,

    • the public interface of std::future,

    • the public interface of pagmo::archipelago,

    • the public interface of the replacement/selection policies.

void wait_check()#

Block until evolution ends and re-raise the first stored exception.

This method will block until all the evolution tasks enqueued via island::evolve() have been completed. If one task enqueued after the last call to wait_check() threw an exception, the exception will be re-thrown by this method. If more than one task enqueued after the last call to wait_check() threw an exception, this method will re-throw the exception raised by the first enqueued task that threw, and the exceptions from all the other tasks that threw will be ignored.

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

Throws

unspecified – any exception thrown by evolution tasks.

void wait()#

Block until evolution ends.

This method will block until all the evolution tasks enqueued via island::evolve() have been completed. Exceptions thrown by the enqueued tasks 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 island: after a call to wait(), status() will always return either evolve_status::idle or evolve_status::idle_error.

evolve_status status() const#

Status of the island.

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

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 island.

algorithm get_algorithm() const#

Get the algorithm.

It is safe to call this method while the island is evolving.

Throws

unspecified – any exception thrown by threading primitives or by the invoked copy constructor.

Returns

a copy of the island’s algorithm.

void set_algorithm(const algorithm&)#

Set the algorithm.

It is safe to call this method while the island is evolving.

Parameters

algo – the algorithm that will be copied into the island.

Throws

unspecified – any exception thrown by threading primitives, memory allocation errors or the invoked copy constructor.

population get_population() const#

Get the population.

It is safe to call this method while the island is evolving.

Throws

unspecified – any exception thrown by threading primitives or by the invoked copy constructor.

Returns

a copy of the island’s population.

void set_population(const population&)#

Set the population.

It is safe to call this method while the island is evolving.

Parameters

pop – the population that will be copied into the island.

Throws

unspecified – any exception thrown by threading primitives, memory allocation errors or by the invoked copy constructor.

r_policy get_r_policy() const#

Get the replacement policy.

Throws

unspecified – any exception thrown by the copy constructor of the replacement policy.

Returns

a copy of the current replacement policy.

s_policy get_s_policy() const#

Get the selection policy.

Throws

unspecified – any exception thrown by the copy constructor of the selection policy.

Returns

a copy of the current selection policy.

std::string get_name() const#

Island’s name.

If the UDI satisfies pagmo::has_name, then this method will return the output of its get_name() method. Otherwise, an implementation-defined name based on the type of the UDI will be returned.

It is safe to call this method while the island is evolving.

Throws

unspecified – any exception thrown by the get_name() method of the UDI.

Returns

the name of the UDI.

std::string get_extra_info() const#

Island’s extra info.

If the UDI satisfies pagmo::has_extra_info, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

It is safe to call this method while the island is evolving.

Throws

unspecified – any exception thrown by the get_extra_info() method of the UDI.

Returns

extra info about the UDI.

bool is_valid() const#

Check if the island is in a valid state.

Returns

false if this was moved from, true otherwise.

std::type_index get_type_index() const#

Get the type of the UDI.

New in version 2.15.

This function will return the type of the UDI stored within this island instance.

Returns

the type of the UDI.

const void *get_ptr() const#

Get a const pointer to the UDI.

New in version 2.15.

This function will return a raw const pointer to the internal UDI instance. Differently from extract(), this function does not require to pass the correct type in input. It is however the user’s responsibility to cast the returned void pointer to the correct type.

Note

The returned value is a raw non-owning pointer: the lifetime of the pointee is tied to the lifetime of this, and delete must never be called on the pointer.

Returns

a pointer to the internal UDI.

void *get_ptr()#

Get a mutable pointer to the UDI.

New in version 2.15.

This function will return a raw pointer to the internal UDI instance. Differently from extract(), this function does not require to pass the correct type in input. It is however the user’s responsibility to cast the returned void pointer to the correct type.

Note

The returned value is a raw non-owning pointer: the lifetime of the pointee is tied to the lifetime of this, and delete must never be called on the pointer.

Note

The ability to extract a mutable pointer is provided only in order to allow to call non-const methods on the internal UDI instance. Assigning a new UDI via this pointer is undefined behaviour.

Returns

a pointer to the internal UDI.

Functions#

std::ostream &operator<<(std::ostream &os, const island &isl)#

Stream operator for pagmo::island.

This operator will stream to os a human-readable representation of isl.

It is safe to call this method while the island is evolving.

Parameters

  • os – the target stream.

  • isl – the input island.

Returns

a reference to os.

Throws

unspecified – any exception thrown by the stream operators of fundamental types or by the public interface of pagmo::island and of all its members.

Types#

enum class pagmo::evolve_status#

Evolution status.

This enumeration contains status flags used to represent the current status of asynchronous evolution/optimisation in pagmo::island and pagmo::archipelago.

See also

pagmo::island::status() and pagmo::archipelago::status().

Values:

enumerator idle#

No asynchronous operations are ongoing, and no error was generated by an asynchronous operation in the past

enumerator busy#

Asynchronous operations are ongoing, and no error was generated by an asynchronous operation in the past

enumerator idle_error#

Idle with error: no asynchronous operations are ongoing, but an error was generated by an asynchronous operation in the past

enumerator busy_error#

Busy with error: asynchronous operations are ongoing, and an error was generated by an asynchronous operation in the past