Selection policy#

class pygmo.s_policy(udsp=select_best())#

Selection policy.

A selection policy establishes how, during migration within an archipelago, candidate migrants are selected from an island.

Following the same schema adopted for problem, algorithm, etc., s_policy exposes a generic interface to user-defined selection policies (or UDSP for short). UDSPs are classes providing a certain set of methods that implement the logic of the selection policy. Once defined and instantiated, a UDSP can then be used to construct an instance of this class, s_policy, which provides a generic interface to selection policies for use by island.

Every UDSP must implement at least the following method:

def select(self, inds, nx, nix, nobj, nec, nic, tol):
  ...

The select() method takes in input the following parameters:

  • a group of individuals inds,

  • a set of arguments describing the properties of the problem the individuals refer to:

    • the total dimension nx,

    • the integral dimension nix,

    • the number of objectives nobj,

    • the number of equality constraints nec,

    • the number of inequality constraints nic,

    • the problem’s constraint tolerances tol,

and it produces in output another set of individuals resulting from selecting individuals in inds (following some logic established by the UDSP). The sets of individuals inds and the return value of the select() method are represented as tuples of 3 elements containing:

  • a 1D NumPy array of individual IDs (represented as 64-bit unsigned integrals),

  • a 2D NumPy array of decision vectors (i.e., the decision vectors of each individual, stored in row-major order),

  • a 2D NumPy array of fitness vectors (i.e., the fitness vectors of each individual, stored in row-major order).

Additional optional methods can be implemented in a UDSP:

def get_name(self):
  ...
def get_extra_info(self):
  ...

See the documentation of the corresponding methods in this class for details on how the optional methods in the UDSP are used by s_policy.

Selection policies are used in asynchronous operations involving migration in archipelagos, and thus they need to provide a certain degree of thread safety. Specifically, the select() method of the UDSP might be invoked concurrently with any other method of the UDSP interface. It is up to the authors of user-defined selection policies to ensure that this safety requirement is satisfied.

This class is the Python counterpart of the C++ class pagmo::s_policy.

Parameters

udsp – a user-defined selection policy, either C++ or Python

Raises

  • NotImplementedError – if udsp does not implement the mandatory methods detailed above

  • unspecified – any exception thrown by methods of the UDSP invoked during construction, the deep copy of the UDSP, the constructor of the underlying C++ class, or failures at the intersection between C++ and Python (e.g., type conversion errors, mismatched function signatures, etc.)

__init__()#
__repr__()#

Return repr(self).

extract(t)#

Extract the user-defined selection policy.

This method allows to extract a reference to the user-defined selection policy (UDSP) stored within this s_policy instance. The behaviour of this function depends on the value of t (which must be a type) and on the type of the internal UDSP:

  • if the type of the UDSP is t, then a reference to the UDSP will be returned (this mirrors the behaviour of the corresponding C++ method pagmo::s_policy::extract()),

  • if t is object and the UDSP is a Python object (as opposed to an exposed C++ selection policy), then a reference to the UDSP will be returned (this allows to extract a Python UDSP without knowing its type),

  • otherwise, None will be returned.

Parameters

t (type) – the type of the user-defined selection policy to extract

Returns

a reference to the internal user-defined selection policy, or None if the extraction fails

Raises

TypeError – if t is not a type

get_extra_info()#

Selection policy’s extra info.

If the UDSP provides a get_extra_info() method, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

Returns

extra info about the UDSP

Return type

str

Raises

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

get_name()#

Name of the selection policy.

If the UDSP provides a get_name() method, then this method will return the output of its get_name() method. Otherwise, an implementation-defined name based on the type of the UDSP will be returned.

Returns

the name of the selection policy

Return type

str

is_(t)#

Check the type of the user-defined selection policy.

This method returns False if extract(t) returns None, and True otherwise.

Parameters

t (type) – the type that will be compared to the type of the UDSP

Returns

whether the UDSP is of type t or not

Return type

bool

Raises

unspecified – any exception thrown by extract()

select(inds, nx, nix, nobj, nec, nic, tol)#

Select individuals from a group.

This method will invoke the select() method of the UDSP. Given a set of individuals, inds, the select() method of the UDSP is expected to return a new set of individuals selected from inds. The other arguments of this method describe the properties of the problem that the individuals in inds refer to.

The set of individuals inds and the return value of this method are represented as tuples of 3 elements containing:

  • a 1D NumPy array of individual IDs (represented as 64-bit unsigned integrals),

  • a 2D NumPy array of decision vectors (i.e., the decision vectors of each individual, stored in row-major order),

  • a 2D NumPy array of fitness vectors (i.e., the fitness vectors of each individual, stored in row-major order).

In addition to invoking the select() method of the UDSP, this function will also perform a variety of sanity checks on both the input arguments and on the output produced by the UDSP.

Parameters

  • inds (tuple) – the original group of individuals

  • nx (int) – the dimension of the problem inds refers to

  • nix (int) – the integral dimension of the problem inds refers to

  • nobj (int) – the number of objectives of the problem inds refers to

  • nec (int) – the number of equality constraints of the problem inds refers to

  • nic (int) – the number of inequality constraints of the problem inds refers to

  • tol (array-like object) – the vector of constraints tolerances of the problem inds refers to

Returns

a new set of individuals resulting from selecting individuals in inds.

Return type

tuple

Raises

  • RuntimeError – if the object returned by a pythonic UDSP is not iterable, or it is an iterable whose number of elements is not exactly 3, or if the invocation of the select() method of the UDSP raises an exception

  • ValueError – if inds or the return value are not consistent with the problem properties, or the ID, decision and fitness vectors in inds or the return value have inconsistent sizes, or the problem properties are invalid (e.g., nobj is zero, nix > nx, etc.)

  • unspecified – any exception raised by failures at the intersection between C++ and Python (e.g., type conversion errors, mismatched function signatures, etc.)