Algorithm#

class algorithm#

Algorithm class.

../../_images/algo_no_text.png

This class represents an optimization algorithm. An algorithm can be stochastic, deterministic, population based, derivative-free, using hessians, using gradients, a meta-heuristic, evolutionary, etc.. Via this class pagmo offers a common interface to all types of algorithms that can be applied to find solution to a generic mathematical programming problem as represented by the pagmo::problem class.

In order to define an optimization algorithm in pagmo, the user must first define a class (or a struct) whose methods describe the properties of the algorithm and implement its logic. In pagmo, we refer to such a class as a user-defined algorithm, or UDA for short. Once defined and instantiated, a UDA can then be used to construct an instance of this class, pagmo::algorithm, which provides a generic interface to optimization algorithms.

Every UDA must implement at least the following method:

population evolve(const population&) const;

The evolve() method takes as input a pagmo::population, and it is expected to return a new population generated by the evolution (or optimisation) of the original population. In addition to providing the above method, a UDA must also be default, copy and move constructible.

Additional optional methods can be implemented in a UDA:

void set_seed(unsigned);
bool has_set_seed() const;
void set_verbosity(unsigned);
bool has_set_verbosity() const;
std::string get_name() const;
std::string get_extra_info() const;
thread_safety get_thread_safety() const;

See the documentation of the corresponding methods in this class for details on how the optional methods in the UDA are used by pagmo::algorithm.

Note

The only operations allowed on a moved-from pagmo::algorithm are destruction, assignment, and the invocation of the is_valid() member function. Any other operation will result in undefined behaviour.

Public Functions

algorithm()#

Default constructor.

The default constructor will initialize a pagmo::algorithm containing a pagmo::null_algorithm.

Throws: unspecified – any exception thrown by the constructor from UDA.

template<typename T, generic_ctor_enabler<T> = 0> inline explicit algorithm(T &&x)#

Constructor from a user-defined algorithm of type T.

This constructor will construct a pagmo::algorithm from the UDA (user-defined algorithm) x of type T. In order for the construction to be successful, the UDA must implement a minimal set of methods, as described in the documentation of pagmo::algorithm. The constructor will examine the properties of x and store them as data members of this.

Note

This constructor is not enabled if, after the removal of cv and reference qualifiers, T is of type pagmo::algorithm (that is, this constructor does not compete with the copy/move constructors of pagmo::algorithm), or if T does not satisfy pagmo::is_uda.

Parameters: x – the UDA.
Throws: unspecified – any exception thrown by methods of the UDA invoked during construction or by memory errors in strings and standard containers.

algorithm(const algorithm&)#

Copy constructor.

The copy constructor will deep copy the input algorithm other.

Parameters

other – the algorithm to be copied.

Throws

unspecified – any exception thrown by:

memory allocation errors in standard containers,
the copying of the internal UDA.

algorithm(algorithm&&) noexcept#

Move constructor.

Parameters: other – the algorithm from which this will be move-constructed.

algorithm &operator=(algorithm&&) noexcept#

Move assignment operator.

Parameters: other – the assignment target.
Returns: a reference to this.

algorithm &operator=(const algorithm&)#

Copy assignment operator.

Copy assignment is implemented as a copy constructor followed by a move assignment.

Parameters: other – the assignment target.
Throws: unspecified – any exception thrown by the copy constructor.
Returns: a reference to this.

template<typename T, generic_ctor_enabler<T> = 0> inline algorithm &operator=(T &&x)#

Assignment from a user-defined algorithm of type T.

This operator will set the internal UDA to x by constructing a pagmo::algorithm from x, and then move-assigning the result to this.

Note

This operator is not enabled if, after the removal of cv and reference qualifiers, T is of type pagmo::algorithm (that is, this operator does not compete with the copy/move assignment operators of pagmo::algorithm), or if T does not satisfy pagmo::is_uda.

Parameters: x – the UDA.
Throws: unspecified – any exception thrown by the constructor from UDA.
Returns: a reference to this.

template<typename T> inline const T *extract() const noexcept#

Extract a const pointer to the UDA.

This method will extract a const pointer to the internal instance of the UDA. If T is not the same type as the UDA used during construction (after removal of cv and reference qualifiers), this method will return nullptr.

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.

Returns: a const pointer to the internal UDA, or nullptr if T does not correspond exactly to the original UDA type used in the constructor.

template<typename T> inline T *extract() noexcept#

Extract a pointer to the UDA.

This method will extract a pointer to the internal instance of the UDA. If T is not the same type as the UDA used during construction (after removal of cv and reference qualifiers), this method will return nullptr.

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 UDA instance. Assigning a new UDA via this pointer is undefined behaviour.

Returns: a pointer to the internal UDA, or nullptr if T does not correspond exactly to the original UDA type used in the constructor.

template<typename T> inline bool is() const noexcept#

Checks the user-defined algorithm type at run-time.

Returns: true if the user-defined algorithm is T, false otherwise.

population evolve(const population&) const#

Evolve method.

This method will invoke the evolve() method of the UDA. This is where the core of the optimization (evolution) is made.

Parameters: pop – starting population
Throws: unspecified – any exception thrown by the evolve() method of the UDA.
Returns: evolved population

void set_seed(unsigned)#

Set the seed for the stochastic evolution.

Sets the seed to be used in the evolve() method of the UDA for all stochastic variables. If the UDA satisfies pagmo::has_set_seed, then its set_seed() method will be invoked. Otherwise, an error will be raised.

Parameters

seed – seed.

Throws

not_implemented_error – if the UDA does not satisfy pagmo::has_set_seed.
unspecified – any exception thrown by the set_seed() method of the UDA.

inline bool has_set_seed() const#

Check if a set_seed() method is available in the UDA.

This method will return true if a set_seed() method is available in the UDA, false otherwise.

The availability of the a set_seed() method is determined as follows:

if the UDA does not satisfy pagmo::has_set_seed, then this method will always return false;
if the UDA satisfies pagmo::has_set_seed but it does not satisfy pagmo::override_has_set_seed, then this method will always return true;
if the UDA satisfies both pagmo::has_set_seed and pagmo::override_has_set_seed, then this method will return the output of the has_set_seed() method of the UDA.

Returns: a flag signalling the availability of the set_seed() method in the UDA.

inline bool is_stochastic() const#

Alias for algorithm::has_set_seed().

Returns: the output of algorithm::has_set_seed().

void set_verbosity(unsigned)#

Set the verbosity of logs and screen output.

This method will set the level of verbosity for the algorithm. If the UDA satisfies pagmo::has_set_verbosity, then its set_verbosity() method will be invoked. Otherwise, an error will be raised.

The exact meaning of the input parameter level is dependent on the UDA.

Parameters

level – the desired verbosity level.

Throws

not_implemented_error – if the UDA does not satisfy pagmo::has_set_verbosity.
unspecified – any exception thrown by the set_verbosity() method of the UDA.

inline bool has_set_verbosity() const#

Check if a set_verbosity() method is available in the UDA.

This method will return true if a set_verbosity() method is available in the UDA, false otherwise.

The availability of the a set_verbosity() method is determined as follows:

if the UDA does not satisfy pagmo::has_set_verbosity, then this method will always return false;
if the UDA satisfies pagmo::has_set_verbosity but it does not satisfy pagmo::override_has_set_verbosity, then this method will always return true;
if the UDA satisfies both pagmo::has_set_verbosity and pagmo::override_has_set_verbosity, then this method will return the output of the has_set_verbosity() method of the UDA.

Returns: a flag signalling the availability of the set_verbosity() method in the UDA.

inline std::string get_name() const#

Algorithm’s name.

If the UDA satisfies pagmo::has_name, then this method will return the output of its get_name() method. Otherwise, an implementation-defined name based on the type of the UDA will be returned.

Throws: unspecified – any exception thrown by copying an std::string object.
Returns: the algorithm’s name.

std::string get_extra_info() const#

Algorithm’s extra info.

If the UDA satisfies pagmo::has_extra_info, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

Throws: unspecified – any exception thrown by the get_extra_info() method of the UDA.
Returns: extra info about the UDA.

inline thread_safety get_thread_safety() const#

Algorithm’s thread safety level.

If the UDA satisfies pagmo::has_get_thread_safety, then this method will return the output of its get_thread_safety() method. Otherwise, thread_safety::basic will be returned. That is, pagmo assumes by default that is it safe to operate concurrently on distinct UDA instances.

Returns: the thread safety level of the UDA.

bool is_valid() const#

Check if the algorithm is in a valid state.

Returns: false if this was moved from, true otherwise.

std::type_index get_type_index() const#

Get the type of the UDA.

New in version 2.15.

This function will return the type of the UDA stored within this algorithm instance.

Returns: the type of the UDA.

const void *get_ptr() const#

Get a const pointer to the UDA.

New in version 2.15.

This function will return a raw const pointer to the internal UDA instance. Differently from extract(), this function does 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.

Returns: a pointer to the internal UDA.

void *get_ptr()#

Get a mutable pointer to the UDA.

New in version 2.15.

This function will return a raw pointer to the internal UDA instance. Differently from extract(), this function does 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 UDA instance. Assigning a new UDA via this pointer is undefined behaviour.

Returns: a pointer to the internal UDA.