Replacement policy ================== .. versionadded:: 2.11 *#include * .. cpp:namespace-push:: pagmo .. cpp:class:: r_policy Replacement policy. A replacement policy establishes how, during migration within an :cpp:class:`~pagmo::archipelago`, a group of migrants replaces individuals in an existing :cpp:class:`~pagmo::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 :cpp:class:`~pagmo::problem`, :cpp:class:`~pagmo::algorithm`, etc., :cpp:class:`~pagmo::r_policy` exposes a type-erased generic interface to *user-defined replacement policies* (or UDRP for short). UDRPs are classes providing a certain set of member functions 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, :cpp:class:`~pagmo::r_policy`, which provides a generic interface to replacement policies for use by :cpp:class:`~pagmo::island`. Every UDRP must implement at least the following member function: .. code-block:: c++ individuals_group_t replace(const individuals_group_t &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double &, const individuals_group_t &) const; The ``replace()`` function takes in input the following parameters: * a group of individuals *inds* (represented as an :cpp:type:`~pagmo::individuals_group_t`), * a set of arguments describing the properties of the :cpp:class:`~pagmo::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). In addition to providing the above member function, a UDRP must also be default, copy and move constructible. Additional optional member functions can be implemented in a UDRP: .. code-block:: c++ std::string get_name() const; std::string get_extra_info() const; See the documentation of the corresponding member functions in this class for details on how the optional member functions in the UDRP are used by :cpp:class:`~pagmo::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()`` member function of the UDRP might be invoked concurrently with any other member function of the UDRP interface (except for the destructor, the move constructor, and, if implemented, the deserialisation function). It is up to the authors of user-defined replacement policies to ensure that this safety requirement is satisfied. .. warning:: The only operations allowed on a moved-from :cpp:class:`pagmo::r_policy` are destruction, assignment, and the invocation of the :cpp:func:`~pagmo::r_policy::is_valid()` member function. Any other operation will result in undefined behaviour. .. cpp:function:: r_policy() Default constructor. The default constructor will initialize an :cpp:class:`~pagmo::r_policy` containing a :cpp:class:`~pagmo::fair_replace` replacement policy. :exception unspecified: any exception raised by the constructor from a generic UDRP. .. cpp:function:: r_policy(const r_policy &) .. cpp:function:: r_policy(r_policy &&) noexcept .. cpp:function:: r_policy &operator=(const r_policy &) .. cpp:function:: r_policy &operator=(r_policy &&) noexcept :cpp:class:`~pagmo::r_policy` is copy/move constructible, and copy/move assignable. Copy construction/assignment will perform deep copies, move operations will leave the moved-from object in a state which is destructible and assignable. :exception unspecified: when performing copy operations, any exception raised by the UDRP upon copying, or by memory allocation failures. .. cpp:function:: template explicit r_policy(T &&x) Generic constructor from a UDRP. This constructor participates in overload resolution only if ``T``, after the removal of reference and cv qualifiers, is not :cpp:class:`~pagmo::r_policy` and if it satisfies :cpp:class:`pagmo::is_udrp`. This constructor will construct an :cpp:class:`~pagmo::r_policy` from the UDRP (user-defined replacement policy) *x* of type ``T``. The input parameter *x* will be perfectly forwarded to construct the internal UDRP instance. :param x: the input UDRP. :exception unspecified: any exception thrown by the public API of the UDRP, or by memory allocation failures. .. cpp:function:: template r_policy &operator=(T &&x) Generic assignment operator from a UDRP. This operator participates in overload resolution only if ``T``, after the removal of reference and cv qualifiers, is not :cpp:class:`~pagmo::r_policy` and if it satisfies :cpp:class:`pagmo::is_udrp`. This operator will set the internal UDRP to *x* by constructing an :cpp:class:`~pagmo::r_policy` from *x*, and then move-assigning the result to *this*. :param x: the input UDRP. :return: a reference to *this*. :exception unspecified: any exception thrown by the generic constructor from a UDRP. .. cpp:function:: template const T *extract() const noexcept .. cpp:function:: template T *extract() noexcept Extract a (const) pointer to the internal UDRP instance. If ``T`` is the type of the UDRP currently stored within this object, then this function will return a (const) pointer to the internal UDRP instance. Otherwise, ``nullptr`` will be returned. 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. .. warning:: The non-const overload of this function is provided only in order to allow to call non-const member functions on the internal UDRP instance. Assigning a new UDRP via pointers obtained through this function is undefined behaviour. :return: a (const) pointer to the internal UDRP instance, or ``nullptr``. .. cpp:function:: template bool is() const noexcept Check the type of the UDRP. :return: ``true`` if ``T`` is the type of the UDRP currently stored within this object, ``false`` otherwise. .. cpp:function:: individuals_group_t replace(const individuals_group_t &inds, const vector_double::size_type &nx, \ const vector_double::size_type &nix, const vector_double::size_type &nobj, \ const vector_double::size_type &nec, const vector_double::size_type &nic, \ const vector_double &tol, const individuals_group_t &mig) const Replace individuals in a group with migrants from another group. This member function will invoke the ``replace()`` member function of the UDRP. Given a set of individuals, *inds*, and a set of migrants, *mig*, the ``replace()`` member function 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 member function describe the properties of the :cpp:class:`~pagmo::problem` that the individuals in *inds* and *mig* refer to. In addition to invoking the ``replace()`` member function of the UDRP, this function will also perform a variety of sanity checks on both the input arguments and on the output produced by the UDRP. :param inds: the original group of individuals. :param nx: the dimension of the problem *inds* and *mig* refer to. :param nix: the integral dimension of the problem *inds* and *mig* refer to. :param nobj: the number of objectives of the problem *inds* and *mig* refer to. :param nec: the number of equality constraints of the problem *inds* and *mig* refer to. :param nic: the number of inequality constraints of the problem *inds* and *mig* refer to. :param tol: the vector of constraints tolerances of the problem *inds* and *mig* refer to. :param mig: the group of migrants. :return: a new set of individuals resulting from replacing individuals in *inds* with individuals from *mig*. :exception std\:\:invalid_argument: if either: * *inds*, *mig* or the return value are not consistent with the problem properties, * the ID, decision and fitness vectors in *inds*, *mig* or the return value have inconsistent sizes, * the problem properties are invalid (e.g., *nobj* is zero, *nix* > *nx*, etc.). :exception unspecified: any exception raised by the ``replace()`` member function of the UDRP. .. cpp:function:: std::string get_name() const Get the name of this replacement policy. If the UDRP satisfies :cpp:class:`pagmo::has_name`, then this member function will return the output of its ``get_name()`` member function. Otherwise, an implementation-defined name based on the type of the UDRP will be returned. :return: the name of this replacement policy. :exception unspecified: any exception thrown by copying an ``std::string`` object. .. cpp:function:: std::string get_extra_info() const Extra info for this replacement policy. If the UDRP satisfies :cpp:class:`pagmo::has_extra_info`, then this member function will return the output of its ``get_extra_info()`` member function. Otherwise, an empty string will be returned. :return: extra info about the UDRP. :exception unspecified: any exception thrown by the ``get_extra_info()`` member function of the UDRP, or by copying an ``std::string`` object. .. cpp:function:: bool is_valid() const Check if this replacement policy is in a valid state. :return: ``false`` if *this* was moved from, ``true`` otherwise. .. cpp:function:: std::type_index get_type_index() const .. versionadded:: 2.15 Get the type of the UDRP. This function will return the type of the UDRP stored within this :cpp:class:`~pagmo::r_policy` instance. :return: the type of the UDRP. .. cpp:function:: const void *get_ptr() const .. cpp:function:: void *get_ptr() .. versionadded:: 2.15 Get a pointer to the UDRP. These functions will return a raw (const) pointer to the internal UDRP instance. Differently from the :cpp:func:`~pagmo::r_policy::extract()` overloads, these functions do 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 UDRP instance. Assigning a new UDRP via this pointer is undefined behaviour. :return: a pointer to the internal UDRP. Functions --------- .. cpp:function:: std::ostream &operator<<(std::ostream &os, const r_policy &r) Stream insertion operator. This function will direct to *os* a human-readable representation of the input :cpp:class:`~pagmo::r_policy` *r*. :param os: the input ``std::ostream``. :param r: the replacement policy that will be directed to *os*. :return: a reference to *os*. :exception unspecified: any exception thrown by querying various properties of the replacement policy and directing them to *os*. Associated type traits ---------------------- .. cpp:class:: template has_replace The :cpp:any:`value` of this type trait will be ``true`` if ``T`` provides a member function with signature: .. code-block:: c++ individuals_group_t replace(const individuals_group_t &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double::size_type &, const vector_double &, const individuals_group_t &) const; The ``replace()`` member function is part of the interface for the definition of an :cpp:class:`~pagmo::r_policy`. .. cpp:member:: static const bool value The value of the type trait. .. cpp:class:: template is_udrp This type trait detects if ``T`` is a user-defined replacement policy (or UDRP). Specifically, the :cpp:any:`value` of this type trait will be ``true`` if: * ``T`` is not a reference or cv qualified, * ``T`` is destructible, default, copy and move constructible, and * ``T`` satisfies :cpp:class:`pagmo::has_replace`. .. cpp:member:: static const bool value The value of the type trait. .. cpp:namespace-pop::