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 existingpopulation
. 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 byisland
.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 atype
) 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.
- 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 itsget_extra_info()
method. Otherwise, an empty string will be returned.- Returns
extra info about the UDRP
- Return type
- 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 itsget_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
- is_(t)#
Check the type of the user-defined replacement policy.
This method returns
False
ifextract(t)
returnsNone
, andTrue
otherwise.
- 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, thereplace()
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 theproblem
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 tonix (
int
) – the integral dimension of the problem inds and mig refer tonobj (
int
) – the number of objectives of the problem inds and mig refer tonec (
int
) – the number of equality constraints of the problem inds and mig refer tonic (
int
) – the number of inequality constraints of the problem inds and mig refer totol (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
- 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 exceptionValueError – 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.)