Algorithm

class pagmo::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 optimizaztion 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
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:

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
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:

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.