Population

class pagmo::population
Population class.
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 movedfrom
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 defaultconstructed 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 problemx
and setting the population random seed toseed
. The input problemx
can be either a pagmo::problem or a userdefined problem (UDP).Note
This constructor is enabled only if, after the removal of cv/reference qualifiers,
T
is notpagmo::population
, and ifpagmo::problem
is constructible fromT
. 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 userdefined problem (UDP). The fitnesses of the individuals will be evaluated with the inputpagmo::bfe
or UDBFE b.Note
This constructor is enabled only if
pagmo::problem
is constructible fromT
, andpagmo::bfe
is constructible fromU
. Parameters
x – the problem the population refers to.
b – the (userdefined) 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 (userdefined) 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 tof
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 off
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
andf
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 singleobjective 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 multiobjective 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 implementationdefined 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 implementationdefined 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 singleobjective 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 multiobjective 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 implementationdefined 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)
If the problem is singleobjective 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 multiobjective 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.
 Parameters
tol – vector of tolerances to be applied to each constraints.
 Throws
std::overflow_error – if the size of the population exceeds an implementationdefined 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. Reevaluating 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
If the problem is stochastic the champion is the individual that had the lowest fitness for some lucky seed, not on average across seeds. Reevaluating its decision vector may then result in a different fitness.
 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 nonconst 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.