NLopt solvers#

#include <pagmo/algorithms/nlopt.hpp>

class nlopt : public pagmo::not_population_based#

NLopt algorithms.

../../../_images/nlopt.png

This user-defined algorithm wraps a selection of solvers from the NLopt library, focusing on local optimisation (both gradient-based and derivative-free). The complete list of supported NLopt algorithms is:

  • COBYLA,

  • BOBYQA,

  • NEWUOA + bound constraints,

  • PRAXIS,

  • Nelder-Mead simplex,

  • sbplx,

  • MMA (Method of Moving Asymptotes),

  • CCSA,

  • SLSQP,

  • low-storage BFGS,

  • preconditioned truncated Newton,

  • shifted limited-memory variable-metric,

  • augmented Lagrangian algorithm.

The desired NLopt solver is selected upon construction of a pagmo::nlopt algorithm. Various properties of the solver (e.g., the stopping criteria) can be configured after construction via methods provided by this class. Multiple stopping criteria can be active at the same time: the optimisation will stop as soon as at least one stopping criterion is satisfied. By default, only the xtol_rel stopping criterion is active (see get_xtol_rel()).

All NLopt solvers support only single-objective optimisation, and, as usual in pagmo, minimisation is always assumed. The gradient-based algorithms require the optimisation problem to provide a gradient. Some solvers support equality and/or inequality constraints. The constraints’ tolerances will be set to those specified in the pagmo::problem being optimised (see pagmo::problem::set_c_tol()).

In order to support pagmo’s population-based optimisation model, nlopt::evolve() will select a single individual from the input pagmo::population to be optimised by the NLopt solver. If the optimisation produces a better individual (as established by pagmo::compare_fc()), the optimised individual will be inserted back into the population. The selection and replacement strategies can be configured via set_selection(const std::string &), set_selection(population::size_type), set_replacement(const std::string &) and set_replacement(population::size_type).

See also

The NLopt website contains a detailed description of each supported solver.

Note

This user-defined algorithm is available only if pagmo was compiled with the PAGMO_WITH_NLOPT option enabled (see the installation instructions).

Warning

A moved-from pagmo::nlopt is destructible and assignable. Any other operation will result in undefined behaviour.

Public Types

using log_line_type = std::tuple<unsigned long, double, vector_double::size_type, double, bool>#

Single data line for the algorithm’s log.

A log data line is a tuple consisting of:

  • the number of objective function evaluations made so far,

  • the objective function value for the current decision vector,

  • the number of constraints violated by the current decision vector,

  • the constraints violation norm for the current decision vector,

  • a boolean flag signalling the feasibility of the current decision vector.

using log_type = std::vector<log_line_type>#

Log type.

The algorithm log is a collection of nlopt::log_line_type data lines, stored in chronological order during the optimisation if the verbosity of the algorithm is set to a nonzero value (see nlopt::set_verbosity()).

Public Functions

nlopt()#

Default constructor.

The default constructor initialises the pagmo::nlopt algorithm with the "cobyla" solver. The individual selection/replacement strategies are those specified by not_population_based::not_population_based().

Throws

unspecified – any exception thrown by pagmo::nlopt(const std::string &).

explicit nlopt(const std::string&)#

Constructor from solver name.

This constructor will initialise a pagmo::nlopt object which will use the NLopt algorithm specified by the input string algo. The individual selection/replacement strategies are those specified by not_population_based::not_population_based(). algo is translated to an NLopt algorithm type according to the following table:

algo string

NLopt algorithm

"cobyla"

NLOPT_LN_COBYLA

"bobyqa"

NLOPT_LN_BOBYQA

"newuoa"

NLOPT_LN_NEWUOA

"newuoa_bound"

NLOPT_LN_NEWUOA_BOUND

"praxis"

NLOPT_LN_PRAXIS

"neldermead"

NLOPT_LN_NELDERMEAD

"sbplx"

NLOPT_LN_SBPLX

"mma"

NLOPT_LD_MMA

"ccsaq"

NLOPT_LD_CCSAQ

"slsqp"

NLOPT_LD_SLSQP

"lbfgs"

NLOPT_LD_LBFGS

"tnewton_precond_restart"

NLOPT_LD_TNEWTON_PRECOND_RESTART

"tnewton_precond"

NLOPT_LD_TNEWTON_PRECOND

"tnewton_restart"

NLOPT_LD_TNEWTON_RESTART

"tnewton"

NLOPT_LD_TNEWTON

"var2"

NLOPT_LD_VAR2

"var1"

NLOPT_LD_VAR1

"auglag"

NLOPT_AUGLAG

"auglag_eq"

NLOPT_AUGLAG_EQ

The parameters of the selected algorithm can be specified via the methods of this class.

See also

The NLopt website contains a detailed description of each supported solver.

Parameters

algo – the name of the NLopt algorithm that will be used by this pagmo::nlopt object.

Throws

  • std::runtime_error – if the NLopt version is not at least 2.

  • std::invalid_argument – if algo is not one of the allowed algorithm names.

  • unspecified – any exception thrown by not_population_based::not_population_based().

nlopt(const nlopt&)#

Copy constructor.

The copy constructor will deep-copy the state of other.

Parameters

other – the construction argument.

Throws

unspecified – any exception thrown by copying the internal state of other.

nlopt(nlopt&&) = default#

Move constructor.

nlopt &operator=(nlopt&&) = default#

Move assignment operator.

Returns

a reference to this.

population evolve(population) const#

Evolve population.

This method will select an individual from pop, optimise it with the NLopt algorithm specified upon construction, replace an individual in pop with the optimised individual, and finally return pop. The individual selection and replacement criteria can be set via set_selection(const std::string &), set_selection(population::size_type), set_replacement(const std::string &) and set_replacement(population::size_type). The NLopt solver will run until one of the stopping criteria is satisfied, and the return status of the NLopt solver will be recorded (it can be fetched with get_last_opt_result()).

Parameters

pop – the population to be optimised.

Throws

  • std::invalid_argument – in the following cases:

    • the population’s problem is multi-objective,

    • the setup of the NLopt algorithm fails (e.g., if the problem is constrained but the selected NLopt solver does not support constrained optimisation),

    • the selected NLopt solver needs gradients but they are not provided by the population’s problem,

    • the components of the individual selected for optimisation contain NaNs or they are outside the problem’s bounds.

  • unspecified – any exception thrown by the public interface of pagmo::problem or pagmo::not_population_based.

Returns

the optimised population.

std::string get_name() const#

Algorithm’s name.

Returns

a human-readable name for the algorithm.

inline void set_verbosity(unsigned n)#

Set verbosity.

This method will set the algorithm’s verbosity. If n is zero, no output is produced during the optimisation and no logging is performed. If n is nonzero, then every n objective function evaluations the status of the optimisation will be both printed to screen and recorded internally. See nlopt::log_line_type and nlopt::log_type for information on the logging format. The internal log can be fetched via get_log().

Example (verbosity 5): 

objevals:       objval:      violated:    viol. norm:
       1       47.9474              1        2.07944 i
       6       17.1986              2       0.150557 i
      11        17.014              0              0
      16        17.014              0              0
The i at the end of some rows indicates that the decision vector is infeasible. Feasibility is checked against the problem’s tolerance.

By default, the verbosity level is zero.

Parameters

n – the desired verbosity level.

std::string get_extra_info() const#

Get extra information about the algorithm.

Returns

a human-readable string containing useful information about the algorithm’s properties (e.g., the stopping criteria, the selection/replacement policies, etc.).

inline const log_type &get_log() const#

Get the optimisation log.

See nlopt::log_type for a description of the optimisation log. Logging is turned on/off via set_verbosity().

Returns

a const reference to the log.

inline std::string get_solver_name() const#

Get the name of the solver that was used to construct this pagmo::nlopt algorithm.

Returns

the name of the NLopt solver used upon construction.

inline ::nlopt_result get_last_opt_result() const#

Get the result of the last optimisation.

Returns

the result of the last evolve() call, or NLOPT_SUCCESS if no optimisations have been run yet.

inline double get_stopval() const#

Get the stopval stopping criterion.

The stopval stopping criterion instructs the solver to stop when an objective value less than or equal to stopval is found. Defaults to the C constant -HUGE_VAL (that is, this stopping criterion is disabled by default).

Returns

the stopval stopping criterion for this pagmo::nlopt.

void set_stopval(double)#

Set the stopval stopping criterion.

Parameters

stopval – the desired value for the stopval stopping criterion (see get_stopval()).

Throws

std::invalid_argument – if stopval is NaN.

inline double get_ftol_rel() const#

Get the ftol_rel stopping criterion.

The ftol_rel stopping criterion instructs the solver to stop when an optimization step (or an estimate of the optimum) changes the objective function value by less than ftol_rel multiplied by the absolute value of the function value. Defaults to 0 (that is, this stopping criterion is disabled by default).

Returns

the ftol_rel stopping criterion for this pagmo::nlopt.

void set_ftol_rel(double)#

Set the ftol_rel stopping criterion.

Parameters

ftol_rel – the desired value for the ftol_rel stopping criterion (see get_ftol_rel()).

Throws

std::invalid_argument – if ftol_rel is NaN.

inline double get_ftol_abs() const#

Get the ftol_abs stopping criterion.

The ftol_abs stopping criterion instructs the solver to stop when an optimization step (or an estimate of the optimum) changes the function value by less than ftol_abs. Defaults to 0 (that is, this stopping criterion is disabled by default).

Returns

the ftol_abs stopping criterion for this pagmo::nlopt.

void set_ftol_abs(double)#

Set the ftol_abs stopping criterion.

Parameters

ftol_abs – the desired value for the ftol_abs stopping criterion (see get_ftol_abs()).

Throws

std::invalid_argument – if ftol_abs is NaN.

inline double get_xtol_rel() const#

Get the xtol_rel stopping criterion.

The xtol_rel stopping criterion instructs the solver to stop when an optimization step (or an estimate of the optimum) changes every parameter by less than xtol_rel multiplied by the absolute value of the parameter. Defaults to 1E-8.

Returns

the xtol_rel stopping criterion for this pagmo::nlopt.

void set_xtol_rel(double)#

Set the xtol_rel stopping criterion.

Parameters

xtol_rel – the desired value for the xtol_rel stopping criterion (see get_xtol_rel()).

Throws

std::invalid_argument – if xtol_rel is NaN.

inline double get_xtol_abs() const#

Get the xtol_abs stopping criterion.

The xtol_abs stopping criterion instructs the solver to stop when an optimization step (or an estimate of the optimum) changes every parameter by less than xtol_abs. Defaults to 0 (that is, this stopping criterion is disabled by default).

Returns

the xtol_abs stopping criterion for this pagmo::nlopt.

void set_xtol_abs(double)#

Set the xtol_abs stopping criterion.

Parameters

xtol_abs – the desired value for the xtol_abs stopping criterion (see get_xtol_abs()).

Throws

std::invalid_argument – if xtol_abs is NaN.

inline int get_maxeval() const#

Get the maxeval stopping criterion.

The maxeval stopping criterion instructs the solver to stop when the number of function evaluations exceeds maxeval. Defaults to 0 (that is, this stopping criterion is disabled by default).

Returns

the maxeval stopping criterion for this pagmo::nlopt.

inline void set_maxeval(int n)#

Set the maxeval stopping criterion.

Parameters

n – the desired value for the maxeval stopping criterion (see get_maxeval()).

inline int get_maxtime() const#

Get the maxtime stopping criterion.

The maxtime stopping criterion instructs the solver to stop when the optimization time (in seconds) exceeds maxtime. Defaults to 0 (that is, this stopping criterion is disabled by default).

Returns

the maxtime stopping criterion for this pagmo::nlopt.

inline void set_maxtime(int n)#

Set the maxtime stopping criterion.

Parameters

n – the desired value for the maxtime stopping criterion (see get_maxtime()).

void set_local_optimizer(nlopt)#

Set the local optimizer.

Some NLopt algorithms rely on other NLopt algorithms as local/subsidiary optimizers. This method allows to set such local optimizer. By default, no local optimizer is specified.

Note

At the present time, only the "auglag" and "auglag_eq" solvers make use of a local optimizer. Setting a local optimizer on any other solver will have no effect.

Note

The objective function, bounds, and nonlinear-constraint parameters of the local optimizer are ignored (as they are provided by the parent optimizer). Conversely, the stopping criteria should be specified in the local optimizer. The verbosity of the local optimizer is also forcibly set to zero during the optimisation.

Parameters

n – the local optimizer that will be used by this pagmo::nlopt algorithm.

inline const nlopt *get_local_optimizer() const#

Get the local optimizer.

This method returns a raw const pointer to the local optimizer, if it has been set via set_local_optimizer(). Otherwise, nullptr will be returned.

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 local optimizer.

inline nlopt *get_local_optimizer()#

Get the local optimizer.

This method returns a raw pointer to the local optimizer, if it has been set via set_local_optimizer(). Otherwise, nullptr will be returned.

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

Returns

a pointer to the local optimizer.

void unset_local_optimizer()#

Unset the local optimizer.

After a call to this method, get_local_optimizer() and get_local_optimizer() const will return nullptr.

void set_random_sr_seed(unsigned)#

Set the seed for the "random" selection/replacement policies.

Parameters

seed – the value that will be used to seed the random number generator used by the "random" selection/replacement policies.

void set_selection(const std::string&)#

Set the individual selection policy.

This method will set the policy that is used to select the individual that will be optimised when calling the evolve() method of the algorithm.

The input string must be one of "best", "worst" and "random":

  • "best" will select the best individual in the population,

  • "worst" will select the worst individual in the population,

  • "random" will randomly choose one individual in the population.

set_random_sr_seed() can be used to seed the random number generator used by the "random" policy.

Instead of a selection policy, a specific individual in the population can be selected via set_selection(population::size_type).

Parameters

select – the selection policy.

Throws

std::invalid_argument – if select is not one of "best", "worst" or "random".

inline void set_selection(population::size_type n)#

Set the individual selection index.

This method will set the index of the individual that is selected for optimisation in the evolve() method of the algorithm.

Parameters

n – the index in the population of the individual to be selected for optimisation.

boost::any get_selection() const#

Get the individual selection policy or index.

This method will return a boost::any containing either the individual selection policy (as an std::string) or the individual selection index (as a population::size_type). The selection policy or index is set via set_selection(const std::string &) and set_selection(population::size_type).

Returns

the individual selection policy or index.

void set_replacement(const std::string&)#

Set the individual replacement policy.

This method will set the policy that is used in the evolve() method of the algorithm to select the individual that will be replaced by the optimised individual.

The input string must be one of "best", "worst" and "random":

  • "best" will select the best individual in the population,

  • "worst" will select the worst individual in the population,

  • "random" will randomly choose one individual in the population.

set_random_sr_seed() can be used to seed the random number generator used by the "random" policy.

Instead of a replacement policy, a specific individual in the population can be selected via set_replacement(population::size_type).

Parameters

replace – the replacement policy.

Throws

std::invalid_argument – if replace is not one of "best", "worst" or "random".

inline void set_replacement(population::size_type n)#

Set the individual replacement index.

This method will set the index of the individual that is replaced after the optimisation in the evolve() method of the algorithm.

Parameters

n – the index in the population of the individual to be replaced after the optimisation.

boost::any get_replacement() const#

Get the individual replacement policy or index.

This method will return a boost::any containing either the individual replacement policy (as an std::string) or the individual replacement index (as a population::size_type). The replacement policy or index is set via set_replacement(const std::string &) and set_replacement(population::size_type).

Returns

the individual replacement policy or index.