Population

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

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.

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

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