1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
|
Replacement policy
==================
.. versionadded:: 2.11
*#include <pagmo/r_policy.hpp>*
.. 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 <typename T> 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 <typename T> 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 <typename T> const T *extract() const noexcept
.. cpp:function:: template <typename T> 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 <typename T> 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 <typename T> 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 <typename T> 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::
|
