`culebra.trainer.ea.ElitistEA` class¶

class ElitistEA(fitness_func: FitnessFunction, solution_cls: type[Individual], species: Species, crossover_func: Callable[[Individual, Individual], tuple[Individual, Individual]] | None = None, mutation_func: Callable[[Individual, float], tuple[Individual]] | None = None, selection_func: Callable[[list[Individual], int, Any], list[Individual]] | None = None, crossover_prob: float | None = None, mutation_prob: float | None = None, gene_ind_mutation_prob: float | None = None, pop_size: int | None = None, elite_size: int | None = None, custom_termination_func: Callable[[ElitistEA], bool] | None = None, max_num_iters: int | None = None, checkpoint_activation: bool | None = None, checkpoint_freq: int | None = None, checkpoint_basename: str | None = None, verbosity: bool | None = None, random_seed: int | None = None)¶

Bases: EA

Create a new trainer.

Parameters:

fitness_func (FitnessFunction) – The training fitness function
solution_cls (type[Individual]) – The individual class
species (Species) – The species for all the individuals
crossover_func (Callable) – The crossover function. If omitted, _default_crossover_func is used. Defaults to None
mutation_func (Callable) – The mutation function. If omitted, _default_mutation_func is used. Defaults to None
selection_func (Callable) – The selection function. If omitted, _default_selection_func is used. Defaults to None
crossover_prob (float) – The crossover probability. If omitted, _default_crossover_prob is used. Defaults to None
mutation_prob (float) – The mutation probability. If omitted, _default_mutation_prob is used. Defaults to None
gene_ind_mutation_prob (float) – The gene independent mutation probability. If omitted, _default_gene_ind_mutation_prob is used. Defaults to None
pop_size (int) – The population size. If omitted, _default_pop_size is used. Defaults to None
elite_size (int) – Number of individuals that will be preserved as the elite. If omitted, _default_elite_size will be used. Defaults to None
custom_termination_func (Callable) – Custom termination criterion. If omitted, _default_termination_func() is used. Defaults to None
max_num_iters (int) – Maximum number of iterations. If omitted, _default_max_num_iters will be used. Defaults to None
checkpoint_activation (bool) – Checkpoining activation. If omitted, _default_checkpoint_activation will be used. Defaults to None
checkpoint_freq (int) – The checkpoint frequency. If omitted, _default_checkpoint_freq will be used. Defaults to None
checkpoint_basename (str) – The checkpoint base file path. If omitted, _default_checkpoint_basename will be used. Defaults to None
verbosity (bool) – The verbosity. If omitted, _default_verbosity will be used. Defaults to None
random_seed (int) – The seed. Defaults to None

Raises:

TypeError – If any argument is not of the appropriate type
ValueError – If any argument has an incorrect value

Class methods¶

classmethod ElitistEA.load(filename: str) → Base¶

Load a serialized object from a file.

Parameters:

filename (str) – The file name.

Returns:

The loaded object

Raises:

TypeError – If filename is not a valid file name
ValueError – If the filename extension is not SERIALIZED_FILE_EXTENSION

Properties¶

property ElitistEA.checkpoint_activation: bool¶

Checkpointing activation.

Returns:: True if checkpointing is active, or False otherwise
Return type:: bool
Setter:: Modify the checkpointing activation
Parameters:: value (bool) – New value for the checkpoint activation. If set to None, _default_checkpoint_activation is chosen
Raises:: TypeError – If value is not a boolean value

property ElitistEA.checkpoint_basename: str¶

Checkpoint base file path.

Return type:: str
Setter:: Modify the checkpoint base file path
Parameters:: value (str) – New value for the checkpoint base file path. If set to None, _default_checkpoint_basename is chosen
Raises:: TypeError – If value is not a valid file name

property ElitistEA.checkpoint_filename: str¶

Checkpoint file path.

Returns:: The file path to store checkpoints
Return type:: str

property ElitistEA.checkpoint_freq: int¶

Checkpoint frequency.

Return type:

int

Setter:

Modify the checkpoint frequency

Parameters:

value (int) – New value for the checkpoint frequency. If set to None, _default_checkpoint_freq is chosen

Raises:

TypeError – If value is not an integer
ValueError – If value is not a positive number

property ElitistEA.container: DistributedTrainer | None¶

Container of this trainer.

The trainer container is only used by distributed trainers. For the rest of trainers defaults to None.

Return type:: DistributedTrainer
Setter:: Set a new value for container of this trainer
Parameters:: value (DistributedTrainer) – New value for the container or None
Raises:: TypeError – If value is not a valid trainer

property ElitistEA.cooperative_fitness_estimation_func: Callable[Sequence[Sequence[float]], Sequence[float]]¶

Cooperative fitness estimation function.

Funtion to estimate the cooperative fitness of a solution from several fitness trials with different cooperators. Only used by cooperative trainers.

Return type:: Callable
Setter:: Set a new function
Parameters:: func (Callable) – The new function
Raises:: TypeError – If func is not a valid function

property ElitistEA.cooperators: list[list[Solution | None]] | None¶

Cooperators of the other species.

Only used by cooperative trainers. If the trainer does not use cooperators, None is returned.

Return type:: list[list[Solution]]

property ElitistEA.crossover_func: Callable[[Individual, Individual], tuple[Individual, Individual]]¶

Crossover function.

Return type:: Callable
Setter:: Set the crossover function
Parameters:: value (Callable) – The new crossover function. If set to :data`None`, _default_crossover_func is chosen
Raises:: TypeError – If value is not Callable

property ElitistEA.crossover_prob: float¶

Crossover probability.

Return type:

float

Setter:

Set the crossover probability

Parameters:

value (float) – The new crossover probability. Must be in (0, 1). If set to :data`None`, _default_crossover_prob is chosen

Raises:

TypeError – If value is not a real number
ValueError – If value is not in (0, 1)

property ElitistEA.current_iter: int | None¶

Current iteration.

Returns:: The current iteration or None if the training has not been done yet
Return type:: int

property ElitistEA.custom_termination_func: Callable[[CentralizedTrainer], bool] | None¶

Custom termination criterion.

Although the trainer will always stop when the max_num_iters are reached, a custom termination criterion can be set to detect convergente and stop the trainer earlier. This custom termination criterion must be a function which receives the trainer as its unique argument and returns a boolean value, True if the training should terminate or False otherwise.

If more than one arguments are needed to define the termination condition, functools.partial() can be used:

from functools import partial

def my_crit(trainer, max_iters):
    if trainer.current_iter < max_iters:
        return False
    return True

trainer.custom_termination_func = partial(my_crit, max_iters=10)

Setter:: Set a new custom termination criterion
Parameters:: func (Callable) – The new custom termination criterion. If set to None, the default termination criterion is used
Raises:: TypeError – If func is not callable

property ElitistEA.elite_size: int¶

Elite size.

Return type:

int

Setter:

Set a new value for the elite size

Parameters:

value (int) – The new size. If omitted, _default_elite_size is chosen

Raises:

TypeError – If value is not an int
ValueError – If value is lower than or equal to 0

property ElitistEA.fitness_func: FitnessFunction¶

Training fitness function.

Return type:: FitnessFunction
Setter:: Set a new fitness function
Parameters:: value (FitnessFunction) – The new training fitness function
Raises:: TypeError – If value is not a valid fitness function

property ElitistEA.gene_ind_mutation_prob: float¶

Gene independent mutation probability.

Return type:

float

Setter:

Set the gene independent mutation probability

Parameters:

value (float) – The new gene independent mutation probability. Must be in (0, 1). If set to :data`None`, _default_gene_ind_mutation_prob is chosen

Raises:

TypeError – If value is not a real number
ValueError – If value is not in (0, 1)

property ElitistEA.index: int¶

Trainer index.

The trainer index is only used within distributed trainers.

Return type:

int

Setter:

Set a new value for trainer index.

Parameters:

value (int) – New value for the trainer index. If set to None, _default_index is chosen

Raises:

TypeError – If value is not an integer
ValueError – If value is a negative number

property ElitistEA.iteration_metric_names: tuple(str)¶

Names of the metrics recorded each iteration.

Return type:: tuple[str]

property ElitistEA.iteration_obj_stats: dict(str, Callable)¶

Stats applied to each objective every iteration.

Return type:: dict

property ElitistEA.logbook: Logbook | None¶

Trainer logbook.

Returns:: A logbook with the statistics of the training or None if the training has not been done yet
Return type:: Logbook

property ElitistEA.max_num_iters: int¶

Maximum number of iterations.

Return type:

int

Setter:

Set a new value for the maximum number of iterations

Parameters:

value (int) – The new maximum number of iterations. If set to None, _default_max_num_iters is chosen

Raises:

TypeError – If value is not an integer
ValueError – If value is not a positive number

property ElitistEA.mutation_func: Callable[[Individual, float], tuple[Individual]]¶

Mutation function.

Return type:: Callable
Setter:: Set the mutation function
Parameters:: value (Callable) – The new mutation function. If set to :data`None`, _default_mutation_func is chosen
Raises:: TypeError – If value is not Callable

property ElitistEA.mutation_prob: float¶

Mutation probability.

Return type:

float

Setter:

Set the mutation probability

Parameters:

value (float) – The new mutation probability. Must be in (0, 1). If set to :data`None`, _default_mutation_prob is chosen

Raises:

TypeError – If value is not a real number
ValueError – If value is not in (0, 1)

property ElitistEA.num_evals: int | None¶

Number of evaluations performed while training.

Returns:: The number of evaluations or None if the training has not been done yet
Return type:: int

property ElitistEA.num_iters: int | None¶

Number of iterations performed while training.

Returns:: The number of iterations or None if the training has not been done yet
Return type:: int

property ElitistEA.pop: list[Individual] | None¶

Population.

Returns:: The population or None if it has not been generated yet
Return type:: list[Individual]

property ElitistEA.pop_size: int¶

Population size.

Returns:

The population size

Return type:

int

Setter:

Set the population size

Parameters:

value (int) – The new population size. Must be greater then zero. If set to :data`None`, _default_pop_size is chosen

Raises:

TypeError – If value is not an int
ValueError – If value is not greater than zero

property ElitistEA.random_seed: int¶

Random seed used by this trainer.

Return type:: int
Setter:: Set a new value for the random seed
Parameters:: value (int) – New value

property ElitistEA.receive_representatives_func: Callable[[CentralizedTrainer], None]¶

Representatives reception function.

Distributed trainers should set this property to their subtrainers in order to implement an adequate representatives exchange mechanism.

Return type:: Callable
Setter:: Set a new function
Parameters:: func (Callable) – The new function
Raises:: TypeError – If func is not a valid function

property ElitistEA.runtime: float | None¶

Training runtime.

Returns:: The training runtime or None if the training has not been done yet.
Return type:: float

property ElitistEA.send_representatives_func: Callable[[CentralizedTrainer], None]¶

Representatives sending function.

Distributed trainers should set this property to their subtrainers in order to implement an adequate representatives exchange mechanism.

Return type:: Callable
Setter:: Set a new function
Parameters:: func (Callable) – The new function
Raises:: TypeError – If func is not a valid function

property ElitistEA.selection_func: Callable[[list[Individual], int, Any], list[Individual]]¶

Selection function.

Return type:: Callable
Setter:: Set the selection function
Parameters:: value (Callable) – The new selection function. If set to :data`None`, _default_selection_func is chosen
Raises:: TypeError – If value is not Callable

property ElitistEA.solution_cls: type[Solution]¶

Solution class.

Return type:: type[Solution]
Setter:: Set the new solution class
Parameters:: value (type[Solution]) – The new class
Raises:: TypeError – If value is not a Solution subclass

property ElitistEA.species: Species¶

Species.

Return type:: Species
Setter:: Set the new species
Parameters:: value (Species) – The new species
Raises:: TypeError – If value is not a Species

property ElitistEA.state_proxy: DictProxy | None¶

Proxy for the state of this trainer.

The proxy is used to copy the state of the trainer only when training is executed within a multiprocess.Process. Defaults to None

Return type:: DictProxy
Setter:: Set a new value for the state proxy of this trainer
Parameters:: value (DictProxy) – New value for the state proxy or None
Raises:: TypeError – If value is not a valid proxy

property ElitistEA.training_finished: bool¶

Check if training has finished.

Returns:: :data`True` if training has finished
Return type:: bool

property ElitistEA.verbosity: bool¶

Verbosity of this trainer.

Return type:: bool
Setter:: Set a new value for the verbosity
Parameters:: value (bool) – The verbosity. If set to None, _default_verbosity is chosen
Raises:: TypeError – If value is not boolean

Private properties¶

property ElitistEA._default_checkpoint_activation: bool¶

Default checkpointing activation.

Returns:: DEFAULT_CHECKPOINT_ACTIVATION
Return type:: bool

property ElitistEA._default_checkpoint_basename: str¶

Default checkpointing base file name.

Returns:: DEFAULT_CHECKPOINT_BASENAME
Return type:: str

property ElitistEA._default_checkpoint_freq: int¶

Default checkpointing frequency.

Returns:: DEFAULT_CHECKPOINT_FREQ
Return type:: int

property ElitistEA._default_cooperative_fitness_estimation_func: Callable[Sequence[Sequence[float]], Sequence[float]]¶

Default cooperative fitness estimation function.

Return the average of all fitness trials.

property ElitistEA._default_crossover_func: Callable[[Individual, Individual], tuple[Individual, Individual]]¶

Default crossover function.

Returns:: The crossover() method of solution_cls
Return type:: Callable

property ElitistEA._default_crossover_prob: float¶

Default crossover probability.

Returns:: DEFAULT_CROSSOVER_PROB
Return type:: float

property ElitistEA._default_elite_size: int¶

Default elite size.

Returns:: DEFAULT_ELITE_SIZE
Return type:: int

property ElitistEA._default_gene_ind_mutation_prob: float¶

Default gene independent mutation probability.

Returns:: DEFAULT_GENE_IND_MUTATION_PROB
Return type:: float

property ElitistEA._default_index: int¶

Default index.

Returns:: DEFAULT_INDEX
Return type:: int

property ElitistEA._default_max_num_iters: int¶

Default maximum number of iterations.

Returns:: DEFAULT_MAX_NUM_ITERS
Return type:: int

property ElitistEA._default_mutation_func: Callable[[Individual, float], tuple[Individual]]¶

Default mutation function.

Returns:: The mutate() method of solution_cls
Return type:: Callable

property ElitistEA._default_mutation_prob: float¶

Default mutation probability.

Returns:: DEFAULT_MUTATION_PROB
Return type:: float

property ElitistEA._default_pop_size: int¶

Default population size.

Returns:: DEFAULT_POP_SIZE
Return type:: int

property ElitistEA._default_receive_representatives_func: Callable[[CentralizedTrainer], None]¶

Default implementation for the representatives reception function.

It does nothing.

property ElitistEA._default_selection_func: Callable[[list[Individual], int, Any], list[Individual]]¶

Default selection function.

Returns:: DEFAULT_SELECTION_FUNC
Return type:: Callable

property ElitistEA._default_send_representatives_func: Callable[[CentralizedTrainer], None]¶

Default implementation for the representatives sending function.

It does nothing.

property ElitistEA._default_verbosity: bool¶

Default verbosity.

Returns:: DEFAULT_VERBOSITY
Return type:: bool

Methods¶

ElitistEA.best_cooperators() → list[list[Solution | None]] | None¶

Return a list of cooperators from each species.

Only used for cooperative trainers.

Returns:: A list of cooperators lists if the trainer is cooperative or None in other cases
Return type:: list[list[Solution]]

ElitistEA.best_solutions() → tuple[HallOfFame]¶

Get the best solutions found for each species.

Returns:: One Hall of Fame for each species
Return type:: tuple[HallOfFame]

ElitistEA.dump(filename: str) → None¶

Serialize this object and save it to a file.

Parameters:

filename (str) – The file name.

Raises:

TypeError – If filename is not a valid file name
ValueError – If the filename extension is not SERIALIZED_FILE_EXTENSION

ElitistEA.evaluate(sol: Solution, fitness_func: FitnessFunction | None = None, index: int | None = None, cooperators: Sequence[Sequence[Solution | None]] | None = None) → int¶

Evaluate one solution.

Its fitness will be modified according with the fitness function results.

Parameters:

sol (Solution) – The solution
fitness_func (FitnessFunction) – The fitness function. If omitted, the training function is used
index (int) – Index where sol should be inserted in the cooperators sequence to form a complete solution for the problem
cooperators (Sequence[Sequence[Solution]]) – Sequence of cooperators of other species or None (if no cooperators are needed to evaluate sol)

Returns:

The number of evaluations performed

Return type:

int

ElitistEA.integrate_representatives(representatives: list[Individual]) → None¶

Integrate representative solutions.

This method is intended to be called within distributed trainers to make the implementation of migrations easier.

Parameters:: representatives (list[Individual]) – A list of solutions

ElitistEA.reset() → None¶

Reset the trainer.

Delete the state of the trainer (with _reset_state()) and also all the internal data structures needed to perform the training (with _reset_internals()).

This method should be invoqued each time a hyper parameter is modified.

ElitistEA.select_representatives() → list[Individual]¶

Select representative solutions.

This method is intended to be called within distributed trainers to make the implementation of migrations easier.

Returns:: A list of solutions
Return type:: list[Individual]

ElitistEA.test(best_found: Sequence[HallOfFame], fitness_func: FitnessFunction, cooperators: Sequence[Sequence[Solution]] | None = None) → None¶

Apply the test fitness function to the solutions found.

Update the solutions in best_found with their test fitness.

Parameters:

best_found (Sequence[HallOfFame]) – The best solutions found for each species. One HallOfFame for each species
fitness_func (FitnessFunction) – Fitness function used to evaluate the final solutions
cooperators (Sequence[ Sequence[Solution]]) – Sequence of cooperators of other species or None (if no cooperators are needed)

Raises:

TypeError – If any parameter has a wrong type
ValueError – If any parameter has an invalid value.

ElitistEA.train()¶: Perform the training process.

Private methods¶

ElitistEA._default_termination_func() → bool¶

Default termination criterion.

Returns:: True if max_num_iters iterations have been run
Return type:: bool

ElitistEA._do_iteration() → None¶

Implement an iteration of the training process.

In this case, the best elite_size individuals of each iteration (the elite) are preserved for the next iteration. The breeding and selection are implemented as in the EA trainer.

ElitistEA._do_training() → None¶

Apply the training algorithm.

Execute the trainer until the termination condition is met. Each iteration is composed by the following steps:

ElitistEA._evaluate_several(inds: Sequence[Individual]) → None¶

Evaluate the individuals that have an invalid fitness.

Parameters:: inds (Sequence[Individual]) – A sequence of individuals

ElitistEA._finish_iteration() → None¶

Finish an iteration.

Finish the iteration metrics (number of evaluations, execution time) after each iteration is run.

ElitistEA._finish_training() → None¶

Finish the training process.

This method is called after the training has finished. It can be overridden to perform any treatment of the solutions found.

ElitistEA._generate_cooperators() → Sequence[Sequence[Solution | None]] | None¶

Generate cooperators from other species.

Returns:: The cooperators
Return type:: Sequence[ Sequence[Solution | None]] | None

ElitistEA._generate_pop() → None¶

Generate the initial population.

The population is filled with random generated individuals.

ElitistEA._get_iteration_metrics() → dict¶

Collect the iteration metrics.

Returns:: The metrics
Return type:: dict

ElitistEA._get_objective_stats() → dict¶

Gather the objective stats.

Returns:: The stats
Return type:: dict

ElitistEA._get_state() → dict[str, Any]¶

Return the state of this trainer.

Overridden to add the current elite to the trainer’s state.

Return type:: dict

ElitistEA._init_internals() → None¶

Set up the trainer internal data structures to start training.

Overridden to create and initialize the Deap’s Toolbox.

ElitistEA._init_state() → None¶

Init the trainer state.

If there is any checkpoint file, the state is initialized from it with the _load_state() method. Otherwise a new initial state is generated with the _new_state() method.

ElitistEA._init_training() → None¶

Init the training process.

Initialize the state of the trainer and all the internal data structures needed to perform the training.

ElitistEA._load_state() → None¶

Load the state of the last checkpoint.

Raises:: Exception – If the checkpoint file can’t be loaded

ElitistEA._new_state() → None¶

Generate a new trainer state.

Overridden to initialize the elite.

ElitistEA._reset_internals() → None¶

Reset the internal structures of the trainer.

Overridden to reset the Deap’s Toolbox.

ElitistEA._reset_state() → None¶

Reset the trainer state.

Overridden to reset the elite.

ElitistEA._save_state() → None¶

Save the state at a new checkpoint.

Raises:: Exception – If the checkpoint file can’t be written

ElitistEA._set_state(state: dict[str, Any]) → None¶

Set the state of this trainer.

Overridden to add the current elite to the trainer’s state.

Parameters:: state (dict) – The last loaded state

ElitistEA._start_iteration() → None¶

Start an iteration.

Prepare the iteration metrics (number of evaluations, execution time) before each iteration is run.

ElitistEA._termination_criterion() → bool¶

Control the training termination.

Returns:: True if either the default termination criterion or a custom termination criterion is met. The default termination criterion is implemented by the _default_termination_func() method. Another custom termination criterion can be set with custom_termination_func method
Return type:: bool

ElitistEA._update_logbook() → None¶

Append the iteration dato to the logbook.

If verbosity is activated, also output the log data to the console.

culebra.trainer.ea.ElitistEA class¶

Class methods¶

Properties¶

Private properties¶

Methods¶

Private methods¶

`culebra.trainer.ea.ElitistEA` class¶