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