Population#

class population#

Population class.

../../_images/pop_no_text.png

This class represents a population of individuals, i.e., potential candidate solutions to a given problem. In pagmo an individual is determined by:

a unique ID used to track it across generations and migrations,
a chromosome (a decision vector),
the fitness of the chromosome as evaluated by a pagmo::problem, and thus including objectives, equality constraints and inequality constraints if present.

A special mechanism is implemented to track the best individual that has ever been part of the population. Such an individual is called champion and its decision vector and fitness vector are automatically kept updated. The champion is not necessarily an individual currently in the population. The champion is only defined and accessible via the population interface if the pagmo::problem currently contained in the pagmo::population is single objective.

Warning

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

Public Types

typedef pop_size_t size_type#: The size type of the population.

Public Functions

population()#

Default constructor.

Constructs an empty population with a default-constructed problem. The random seed is initialised to zero.

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

template<typename T, generic_ctor_enabler<T> = 0> inline explicit population(T &&x, size_type pop_size = 0u, unsigned seed = pagmo::random_device::next())#

Constructor from a problem.

Constructs a population with pop_size individuals associated to the problem x and setting the population random seed to seed. The input problem x can be either a pagmo::problem or a user-defined problem (UDP).

Note

This constructor is enabled only if, after the removal of cv/reference qualifiers, T is not pagmo::population, and if pagmo::problem is constructible from T.

Parameters

x – the problem the population refers to.
pop_size – population size (i.e. number of individuals therein).
seed – seed of the random number generator used, for example, to create new random individuals within the bounds.

Throws

unspecified – any exception thrown by random_decision_vector(), push_back(), or by the invoked constructor of pagmo::problem.

template<typename T, typename U, enable_if_t<detail::conjunction<std::is_constructible<problem, T&&>, std::is_constructible<bfe, U&&>>::value, int> = 0> inline explicit population(T &&x, U &&b, size_type pop_size = 0u, unsigned seed = pagmo::random_device::next())#

Constructor from a problem and a batch fitness evaluator.

Constructs a population with pop_size individuals associated to the problem x and setting the population random seed to seed. The input problem x can be either a pagmo::problem or a user-defined problem (UDP). The fitnesses of the individuals will be evaluated with the input pagmo::bfe or UDBFE b.

Note

This constructor is enabled only if pagmo::problem is constructible from T, and pagmo::bfe is constructible from U.

Parameters

x – the problem the population refers to.
b – the (user-defined) batch fitness evaluator that will be used to evaluate the fitnesses of the individuals.
pop_size – population size (i.e. number of individuals therein).
seed – seed of the random number generator used, for example, to create new random individuals within the bounds.

Throws

unspecified – any exception thrown by batch_random_decision_vector(), the public API of the (user-defined) batch fitness evaluator, push_back(), or by the invoked constructor of pagmo::problem.

population(const population&)#: Defaulted copy constructor.

population(population&&) noexcept#

Move constructor.

Parameters: pop – construction argument.

population &operator=(const population&)#

Copy assignment operator.

Copy assignment is implemented via copy+move.

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

population &operator=(population&&) noexcept#

Move assignment operator.

Parameters: pop – assignment argument.
Returns: a reference to this.

~population()#

Destructor.

The destructor will run sanity checks in debug mode.

void push_back(const vector_double&)#

Adds one decision vector (chromosome) to the population.

Appends a new chromosome x to the population, evaluating its fitness and creating a new unique identifier for the newly born individual.

In case of exceptions, the population will not be altered.

Parameters

x – decision vector to be added to the population.

Throws

std::overflow_error – if the addition of x to the population would overflow the population size limit.
std::invalid_argument – if the size of x differs from the problem’s dimension.
unspecified – any exception thrown by memory errors in standard containers or by problem::fitness().

void push_back(vector_double&&)#

Adds one decision vector (chromosome) to the population (move overload).

This overload behaves like the previous one, the only difference being that x will be moved (rather than copied) into the population.

Parameters: x – decision vector to be added to the population.
Throws: unspecified – any exception thrown by the previous push_back() overload.

void push_back(const vector_double&, const vector_double&)#

Adds one decision vector/fitness vector to the population.

Appends a new chromosome x to the population, and sets its fitness to f creating a new unique identifier for the newly born individual.

In case of exceptions, the population will not be altered.

Parameters

x – decision vector to be added to the population.
f – fitness vector corresponding to the decision vector.

Throws

std::overflow_error – if the addition of x to the population would overflow the population size limit.
std::invalid_argument – if the size of x differs from the problem’s dimension, or if the size of f differs from the fitness dimension.
unspecified – any exception thrown by memory errors in standard containers.

void push_back(vector_double&&, vector_double&&)#

Adds one decision vector/fitness vector to the population (move overload).

This overload behaves like the previous one, the only difference being that x and f will be moved (rather than copied) into the population.

Parameters

x – decision vector to be added to the population.
f – fitness vector corresponding to the decision vector.

Throws

unspecified – any exception thrown by the previous push_back() overload.

vector_double random_decision_vector() const#

Creates a random decision vector.

Creates a random decision vector within the problem’s bounds. It calls internally pagmo::random_decision_vector().

Throws: unspecified – all exceptions thrown by pagmo::random_decision_vector()
Returns: a random decision vector

size_type best_idx() const#

Index of the best individual.

If the problem is single-objective and unconstrained, the best is simply the individual with the smallest fitness. If the problem is, instead, single objective, but with constraints, the best will be defined using the criteria specified in pagmo::sort_population_con(). If the problem is multi-objective one single best is not defined. In this case the user can still obtain a strict ordering of the population individuals by calling the pagmo::sort_population_mo() function.

The pagmo::problem::get_c_tol() tolerances are accounted by default. If different tolerances are required the other overloads can be used.

Throws

std::overflow_error – if the size of the population exceeds an implementation-defined limit.
std::invalid_argument – if the problem is multiobjective and thus a best individual is not well defined, or if the population is empty.
unspecified – any exception thrown by pagmo::sort_population_con().

Returns

the index of the best individual.

size_type best_idx(const vector_double&) const#

Index of the best individual (accounting for a vector tolerance)

Parameters

tol – vector of tolerances to be applied to each constraints.

Throws

std::overflow_error – if the size of the population exceeds an implementation-defined limit.
std::invalid_argument – if the problem is multiobjective and thus a best individual is not well defined, or if the population is empty.
unspecified – any exception thrown by pagmo::sort_population_con().

Returns

the index of the best individual.

size_type best_idx(double) const#

Index of the best individual (accounting for a scalar tolerance)

Parameters: tol – scalar tolerance to be considered for each constraint.
Throws: unspecified – any exception thrown by the previous best_idx() overload.
Returns: index of the best individual.

size_type worst_idx() const#

Index of the worst individual.

If the problem is single-objective and unconstrained, the worst is simply the individual with the largest fitness. If the problem is, instead, single objective, but with constraints, the worst individual will be defined using the criteria specified in pagmo::sort_population_con(). If the problem is multi-objective one single worst is not defined. In this case the user can still obtain a strict ordering of the population individuals by calling the pagmo::sort_population_mo() function.

The pagmo::problem::get_c_tol() tolerances are accounted by default. If different tolerances are required the other overloads can be used.

Throws

std::overflow_error – if the size of the population exceeds an implementation-defined limit.
std::invalid_argument – if the problem is multiobjective and thus a worst individual is not well defined, or if the population is empty.
unspecified – any exception thrown by pagmo::sort_population_con().

Returns

the index of the worst individual.

size_type worst_idx(const vector_double&) const#

Index of the worst individual (accounting for a vector tolerance)

Parameters

tol – vector of tolerances to be applied to each constraints.

Throws

std::overflow_error – if the size of the population exceeds an implementation-defined limit.
std::invalid_argument – if the problem is multiobjective and thus a worst individual is not well defined, or if the population is empty.
unspecified – any exception thrown by pagmo::sort_population_con().

Returns

the index of the worst individual.

size_type worst_idx(double) const#

Index of the worst individual (accounting for a scalar tolerance)

Parameters: tol – scalar tolerance to be considered for each constraint.
Throws: unspecified – any exception thrown by the previous worst_idx() overload.
Returns: index of the worst individual.

vector_double champion_x() const#

Champion decision vector.

Note

If the problem is stochastic the champion is the individual that had the lowest fitness for some lucky seed, not on average across seeds. Re-evaluating its decision vector may then result in a different fitness.

Returns: the champion decision vector.
Throws: std::invalid_argument – if the current problem is not single objective.

vector_double champion_f() const#

Champion fitness.

Note

Returns: the champion fitness.
Throws: std::invalid_argument – if the current problem is not single objective.

inline size_type size() const#

Number of individuals in the population.

Returns: the number of individuals in the population

void set_xf(size_type, const vector_double&, const vector_double&)#

Sets the \(i\)-th individual decision vector, and fitness.

Sets simultaneously the \(i\)-th individual decision vector and fitness thus avoiding to trigger a fitness function evaluation.

Warning

Pagmo will only control the input fitness f dimension, so the user can associate decision vector, fitness vectors pairs that are not consistent with the fitness function.

Parameters

i – individual’s index in the population.
x – a decision vector (chromosome).
f – a fitness vector.

Throws

std::invalid_argument – if either:

i is invalid (i.e. larger or equal to the population size),
x has not the correct dimension,
f has not the correct dimension.

void set_x(size_type, const vector_double&)#

Sets the \(i\)-th individual’s chromosome.

Sets the chromosome of the \(i\)-th individual to the value x and changes its fitness accordingly. The individual’s ID remains the same.

Note

A call to this method triggers one fitness function evaluation.

Parameters

i – individual’s index in the population
x – decision vector

Throws

unspecified – any exception thrown by population::set_xf().

inline const problem &get_problem() const#

Const getter for the pagmo::problem.

Returns: a const reference to the internal pagmo::problem.

inline problem &get_problem()#

Getter for the pagmo::problem.

Warning

The ability to extract a mutable reference to the problem is provided solely in order to allow calling non-const methods on the problem. Assigning the population’s problem via a reference returned by this method is undefined behaviour.

Returns: a reference to the internal pagmo::problem.

inline const std::vector<vector_double> &get_f() const#

Const getter for the fitness vectors.

Returns: a const reference to the vector of fitness vectors.

inline const std::vector<vector_double> &get_x() const#

Const getter for the decision vectors.

Returns: a const reference to the vector of decision vectors.

inline const std::vector<unsigned long long> &get_ID() const#

Const getter for the individual IDs.

Returns: a const reference to the vector of individual IDs.

inline unsigned get_seed() const#

Getter for the seed of the population random engine.

Returns: the seed of the population’s random engine.