Replacement policy#

class pygmo.r_policy(udrp=fair_replace())#

Replacement policy.

A replacement policy establishes how, during migration within an archipelago, a group of migrants replaces individuals in an existing population. In other words, a replacement policy is tasked with producing a new set of individuals from an original set of individuals and a set of candidate migrants.

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

Every UDRP must implement at least the following method:

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

The replace() 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,

  • a set of migrants mig,

and it produces in output another set of individuals resulting from replacing individuals in inds with individuals from mig (following some logic established by the UDRP). The sets of individuals inds and mig, and the return value of the replace() 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 UDRP:

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 UDRP are used by r_policy.

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

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

Parameters

udrp – a user-defined replacement policy, either C++ or Python

Raises

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

  • unspecified – any exception thrown by methods of the UDRP invoked during construction, the deep copy of the UDRP, 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 replacement policy.

This method allows to extract a reference to the user-defined replacement policy (UDRP) stored within this r_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 UDRP:

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

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

  • otherwise, None will be returned.

Parameters

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

Returns

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

Raises

TypeError – if t is not a type

get_extra_info()#

Replacement policy’s extra info.

If the UDRP 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 UDRP

Return type

str

Raises

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

get_name()#

Name of the replacement policy.

If the UDRP 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 UDRP will be returned.

Returns

the name of the replacement policy

Return type

str

is_(t)#

Check the type of the user-defined replacement 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 UDRP

Returns

whether the UDRP is of type t or not

Return type

bool

Raises

unspecified – any exception thrown by extract()

replace(inds, nx, nix, nobj, nec, nic, tol, mig)#

Replace individuals in a group with migrants from another group.

This method will invoke the replace() method of the UDRP. Given a set of individuals, inds, and a set of migrants, mig, the replace() method of the UDRP is expected to replace individuals in inds with individuals from mig, and return the new set of individuals resulting from the replacement. The other arguments of this method describe the properties of the problem that the individuals in inds and mig refer to.

The sets of individuals inds and mig, 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 replace() method of the UDRP, this method will also perform a variety of sanity checks on both the input arguments and on the output produced by the UDRP.

Parameters

  • inds (tuple) – the original group of individuals

  • nx (int) – the dimension of the problem inds and mig refer to

  • nix (int) – the integral dimension of the problem inds and mig refer to

  • nobj (int) – the number of objectives of the problem inds and mig refer to

  • nec (int) – the number of equality constraints of the problem inds and mig refer to

  • nic (int) – the number of inequality constraints of the problem inds and mig refer to

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

  • mig (tuple) – the group of migrants

Returns

a new set of individuals resulting from replacing individuals in inds with individuals from mig

Return type

tuple

Raises

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

  • ValueError – if inds, mig or the return value are not consistent with the problem properties, or the ID, decision and fitness vectors in inds, mig 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.)