`culebra.trainer.ea.NSGA` class¶

class NSGA(solution_cls: type[Individual], species: Species, fitness_function: FitnessFunction, max_num_iters: int | None = None, custom_termination_func: Callable[[NSGA], bool] | None = None, pop_size: int | None = None, 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, selection_func_params: dict[str, Any] | None = None, nsga3_reference_points_p: int | None = None, nsga3_reference_points_scaling: float | None = None, checkpoint_activation: bool | None = None, checkpoint_freq: int | None = None, checkpoint_filename: str | None = None, verbosity: bool | None = None, random_seed: int | None = None)¶

Bases: SimpleEA

Create a new trainer.

Parameters:

solution_cls (type[Individual]) – The individual class
species (Species) – The species for all the individuals
fitness_function (FitnessFunction) – The training fitness function
max_num_iters (int) – Maximum number of iterations. If omitted, _default_max_num_iters will be used. Defaults to None
custom_termination_func (Callable) – Custom termination criterion. If omitted, _default_termination_func() is used. Defaults to None
pop_size (int) – The population size. If omitted, _default_pop_size is used. Defaults to None
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
selection_func_params (dict) – The parameters for the selection function. If omitted, _default_selection_func_params is used. Defaults to None
nsga3_reference_points_p (int) – Number of divisions along each objective to obtain the reference points of NSGA-III. If omitted, _default_nsga3_reference_points_p will be used. Defaults to None
nsga3_reference_points_scaling (float) – Scaling factor for the reference points of NSGA-III. 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_filename (str) – The checkpoint file path. If omitted, _default_checkpoint_filename 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 attributes¶

NSGA.objective_stats = {'Avg': <function mean>, 'Max': <function max>, 'Min': <function min>, 'Std': <function std>}¶: Statistics calculated for each objective.

NSGA.stats_names = ('Iter', 'NEvals')¶: Statistics calculated each iteration.

Class methods¶

classmethod NSGA.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 NSGA.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 NSGA.checkpoint_filename: str¶

Checkpoint file path.

Return type:

str

Setter:

Modify the checkpoint file path

Parameters:

value (str) – New value for the checkpoint file path. If set to None, _default_checkpoint_filename is chosen

Raises:

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

property NSGA.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 NSGA.container: Trainer | None¶

Container of this trainer.

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

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

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

Crossover function.

Return type:: Callable
Setter:: Set a new crossover function
Parameters:: func (Callable) – The new crossover function. If omitted, _default_crossover_func is chosen
Raises:: TypeError – If func is not callable

property NSGA.crossover_prob: float¶

Crossover probability.

Return type:

float

Setter:

Set a new crossover probability

Parameters:

prob (float) – The new probability. If omitted, _default_crossover_prob is chosen

Raises:

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

property NSGA.current_iter: int | None¶

Current iteration.

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

property NSGA.custom_termination_func: Callable[[Trainer], 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 search 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 NSGA.fitness_function: FitnessFunction¶

Training fitness function.

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

property NSGA.gene_ind_mutation_prob: float¶

Gene independent mutation probability.

Return type:

float

Setter:

Set a new gene independent mutation probability

Parameters:

prob (float) – The new probability. If omitted, _default_gene_ind_mutation_prob is chosen

Raises:

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

property NSGA.index: int¶

Trainer index.

The trainer index is only used by distributed trainers. For the rest of trainers _default_index is used.

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 NSGA.logbook: Logbook | None¶

Trainer logbook.

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

property NSGA.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, the default maximum number of iterations, _default_max_num_iters, is chosen

Raises:

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

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

Mutation function.

Return type:: Callable
Setter:: Set a new mutation function
Parameters:: func (Callable) – The new mutation function. If omitted, _default_mutation_func is chosen
Raises:: TypeError – If func is not callable

property NSGA.mutation_prob: float¶

Mutation probability.

Return type:

float

Setter:

Set a new mutation probability

Parameters:

prob (float) – The new probability. If omitted, _default_mutation_prob is chosen

Raises:

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

property NSGA.nsga3_reference_points: ndarray¶

Reference points for NSGA-III.

Return type:: ndarray

property NSGA.nsga3_reference_points_p: int¶

NSGA-III’s p parameter.

The p parameter indicates the number of divisions to be made along each objective to obtain the reference points of NSGA-III.

Return type:

int

Setter:

Set a new value for the p parameter for NSGA-III

Parameters:

value (int) – The new number of divisions. If omitted, _default_nsga3_reference_points_p is chosen

Raises:

TypeError – If value is not an integer
ValueError – If value < 1

property NSGA.nsga3_reference_points_scaling: float | None¶

Scaling factor for the reference points of NSGA-III.

Returns:: The scaling factor or None if it is not defined
Return type:: float
Setter:: Set a new scaling factor for the reference points of NSGA-III
Parameters:: value (float) – New scaling factor
Raises:: TypeError – If value is not a float number

property NSGA.num_evals: int | None¶

Number of evaluations performed while training.

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

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

Population.

Return type:: list[Individual]

property NSGA.pop_size: int¶

Population size.

Return type:

int

Setter:

Set a new population size

Parameters:

size (int) – The new population size. If omitted, _default_pop_size is chosen

Raises:

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

property NSGA.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 NSGA.representatives: list[list[Solution | None]] | None¶

Representatives of the other species.

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

Return type:: list[list[Solution]]

property NSGA.runtime: float | None¶

Training runtime.

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

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

Selection function.

Return type:: Callable
Setter:: Set a new selection function
Parameters:: func (Callable) – The new selection function. If omitted, _default_selection_func is chosen
Raises:: TypeError – If func is not callable

property NSGA.selection_func_params: dict[str, Any]¶

Parameters of the selection function.

Return type:: dict
Setter:: Set new parameters for the selection function
Parameters:: params (dict) – The new parameters. If omitted, _default_selection_func_params is chosen
Raises:: TypeError – If params is not a dict

property NSGA.solution_cls: type[Solution]¶

Solution class.

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

property NSGA.species: Species¶

Species.

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

property NSGA.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 NSGA._default_checkpoint_activation: bool¶

Default checkpointing activation.

Returns:: DEFAULT_CHECKPOINT_ACTIVATION
Return type:: bool

property NSGA._default_checkpoint_filename: str¶

Default checkpointing file name.

Returns:: DEFAULT_CHECKPOINT_FILENAME
Return type:: str

property NSGA._default_checkpoint_freq: int¶

Default checkpointing frequency.

Returns:: DEFAULT_CHECKPOINT_FREQ
Return type:: int

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

Default crossover function.

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

property NSGA._default_crossover_prob: float¶

Default crossover probability.

Returns:: DEFAULT_CROSSOVER_PROB
Return type:: float

property NSGA._default_gene_ind_mutation_prob: float¶

Default gene independent mutation probability.

Returns:: DEFAULT_GENE_IND_MUTATION_PROB
Return type:: float

property NSGA._default_index: int¶

Default index.

Returns:: DEFAULT_INDEX
Return type:: int

property NSGA._default_max_num_iters: int¶

Default maximum number of iterations.

Returns:: DEFAULT_MAX_NUM_ITERS
Return type:: int

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

Default mutation function.

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

property NSGA._default_mutation_prob: float¶

Default mutation probability.

Returns:: DEFAULT_MUTATION_PROB
Return type:: float

property NSGA._default_nsga3_reference_points_p: int¶

Default NSGA-III’s p parameter.

Returns:: DEFAULT_NSGA3_REFERENCE_POINTS_P
Return type:: int

property NSGA._default_pop_size: int¶

Default population size.

Returns:: DEFAULT_POP_SIZE for NSGA-II or the number of reference points for NSGA-III
Return type:: int

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

Default selection function. self.nsga3_reference_points_p = nsga3_reference_points_p self.nsga3_reference_points_scaling = nsga3_reference_points_scaling

Returns:: DEFAULT_NSGA_SELECTION_FUNC
Return type:: Callable

property NSGA._default_selection_func_params: dict[str, Any]¶

Parameters of the default selection function.

Returns:: DEFAULT_NSGA_SELECTION_FUNC_PARAMS
Return type:: float

property NSGA._default_verbosity: bool¶

Default verbosity.

Returns:: DEFAULT_VERBOSITY
Return type:: bool

Methods¶

NSGA.train(state_proxy: DictProxy | None = None) → None¶

Perform the training process.

Parameters:: state_proxy (DictProxy) – dictionary proxy to copy the output state of the trainer procedure. Only used if train is executed within a multiprocess.Process. Defaults to None

NSGA.test(best_found: Sequence[HallOfFame], fitness_func: FitnessFunction | None = None, representatives: 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. If ommited, the default training fitness function (fitness_function) will be used
representatives (Sequence[Sequence[Solution]]) – Sequence of representatives of other species or None (if no representatives are needed). If omitted, the current value of representatives is used

Raises:

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

NSGA.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 search (with _reset_internals()).

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

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

Evaluate one solution.

Its fitness will be modified according with the fitness function results. Besides, if called during training, the number of evaluations will be also updated.

Parameters:

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

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

NSGA.best_solutions() → tuple[HallOfFame]¶

Get the best solutions found for each species.

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

NSGA.best_representatives() → list[list[Solution]] | None¶

Return a list of representatives from each species.

Only used for cooperative trainers.

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

Private methods¶

NSGA._default_termination_func() → bool¶

Default termination criterion.

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

NSGA._do_iteration() → None¶

Implement an iteration of the search process.

In this case, a generation of NSGA is implemented.

NSGA._do_iteration_stats() → None¶: Perform the iteration stats.

NSGA._evaluate_pop(pop: list[Individual]) → None¶

Evaluate the individuals of pop that have an invalid fitness.

Parameters:: pop (list[Individual]) – A population

NSGA._finish_iteration() → None¶

Finish an iteration.

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

NSGA._finish_search() → None¶

Finish the search process.

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

NSGA._generate_initial_pop() → None¶

Generate the initial population.

The population is filled with random generated individuals.

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

Return the state of this trainer.

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

Getter:: Return the state
Setter:: Set a new state
Return type:: dict

NSGA._init_internals() → None¶

Set up the trainer internal data structures to start searching.

Overridden to support the NSGA-III reference points.

NSGA._init_representatives() → None¶

Init the representatives of the other species.

Only used for cooperative approaches, which need representatives of all the species to form a complete solution for the problem. Cooperative subclasses of the Trainer class should override this method to get the representatives of the other species initialized.

NSGA._init_search() → None¶

Init the search process.

Initialize the state of the trainer (with _init_state()) and all the internal data structures needed (with _init_internals()) to perform the search.

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

NSGA._load_state() → None¶

Load the state of the last checkpoint.

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

NSGA._new_state() → None¶

Generate a new trainer state.

Overridden to fill the population with evaluated random individuals.

NSGA._postprocess_iteration() → None¶

Postprocess after doing the iteration.

Subclasses should override this method to make any postprocessment after performing an iteration.

NSGA._preprocess_iteration() → None¶

Preprocess before doing the iteration.

Subclasses should override this method to make any preprocessment before performing an iteration.

NSGA._reset_internals() → None¶

Reset the internal structures of the trainer.

Overridden to reset the NSGA-III reference points.

NSGA._reset_state() → None¶

Reset the trainer state.

Overridden to reset the initial population.

NSGA._save_state() → None¶

Save the state at a new checkpoint.

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

NSGA._search() → None¶

Apply the search algorithm.

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

NSGA._set_cooperative_fitness(sol: Solution, fitness_trials_values: [Sequence[tuple[float]]]) → None¶

Estimate a solution fitness from multiple evaluation trials.

Applies an average of the fitness trials values. Trainers requiring another estimation should override this method.

Parameters:

sol (Solution) – The solution
fitness_trials_values (Sequence[tuple[float]]) – Sequence of fitness trials values. Each trial should be obtained with a different context in a cooperative trainer approach.

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

Set the state of this trainer.

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

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

NSGA._start_iteration() → None¶

Start an iteration.

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

NSGA._termination_criterion() → bool¶

Control the search 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

culebra.trainer.ea.NSGA class¶

Class attributes¶

Class methods¶

Properties¶

Private properties¶

Methods¶

Private methods¶

`culebra.trainer.ea.NSGA` class¶