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_enable: bool | None = None, checkpoint_freq: int | None = None, checkpoint_filename: str | None = None, verbose: bool | None = None, random_seed: int | None = None)

Create a new trainer.

Parameters:
Raises:

  • TypeError – If any argument is not of the appropriate type

  • ValueError – If any argument has an incorrect value

Class attributes

NSGA.stats_names = ('Iter', 'NEvals')

Statistics calculated each iteration.

NSGA.objective_stats = {'Avg': <function mean>, 'Max': <function max>, 'Min': <function min>, 'Std': <function std>}

Statistics calculated for each objective.

Class methods

classmethod NSGA.load_pickle(filename: str) → Base

Load a pickled object from a file.

Parameters:

filename (str) – The file name.

Raises:

Properties

property NSGA.solution_cls: Type[Individual]

Get and set the individual class.

Getter:

Return the individual class

Setter:

Set a new individual class

Type:

An Individual subclass

Raises:

TypeError – If set to a value which is not an Individual subclass

property NSGA.species: Species

Get and set the species.

Getter:

Return the species

Setter:

Set a new species

Type:

Species

Raises:

TypeError – If set to a value which is not a Species instance

property NSGA.fitness_function: FitnessFunction

Get and set the training fitness function.

Getter:

Return the fitness function

Setter:

Set a new fitness function

Type:

FitnessFunction

Raises:

TypeError – If set to a value which is not a fitness function

property NSGA.max_num_iters: int

Get and set the maximum number of iterations.

Getter:

Return the current maximum number of iterations

Setter:

Set a new value for the maximum number of iterations. If set to None, the default maximum number of iterations, DEFAULT_MAX_NUM_ITERS, is chosen

Type:

int

Raises:

  • TypeError – If set to a value which is not an integer

  • ValueError – If set to a value which is not a positive number

property NSGA.current_iter: int

Return the current iteration.

Type:

int

property NSGA.custom_termination_func: Callable[[Trainer], bool]

Get and set the custom termination criterion.

The 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 termniation 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)
Getter:

Return the current custom termination criterion

Setter:

Set a new custom termination criterion. If set to None, the default termination criterion is used. Defaults to None

Type:

Callable

Raises:

TypeError – If set to a value which is not callable

property NSGA.pop_size: int

Get and set the population size.

Getter:

Return the current population size

Setter:

Set a new value for the population size. If set to None, DEFAULT_POP_SIZE is used for NSGA-II or the number of reference points is chosen for NSGA-III

Type:

int

Raises:

  • TypeError – If set to a value which is not an int

  • ValueError – If set to a value which is not greater than zero

property NSGA.crossover_func: Callable[[Individual, Individual], Tuple[Individual, Individual]]

Get and set the crossover function.

Getter:

Return the current crossover function

Setter:

Set a new crossover function. If set to None, the crossover() method of the individual class evolved by the trainer is chosen

Type:

Callable

Raises:

TypeError – If set to a value which is not callable

property NSGA.mutation_func: Callable[[Individual, float], Tuple[Individual]]

Get and set the mutation function.

Getter:

Return the current mutation function

Setter:

Set a new mutation function. If set to None, the mutate() method of the individual class evolved by the trainer is chosen

Type:

Callable

Raises:

TypeError – If set to a value which is not callable

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

Get and set the selection function.

Getter:

Return the current selection function

Setter:

Set the new selection function. If set to None, DEFAULT_NSGA_SELECTION_FUNC is chosen

Type:

Callable

Raises:

TypeError – If set to a value which is not callable

property NSGA.crossover_prob: float

Get and set the crossover probability.

Getter:

Return the current crossover probability

Setter:

Set the new crossover probability. If set to None, DEFAULT_CROSSOVER_PROB is chosen

Type:

float in (0, 1)

Raises:

  • TypeError – If set to a value which is not a real number

  • ValueError – If set to a value which is not in (0, 1)

property NSGA.mutation_prob: float

Get and set the mutation probability.

Getter:

Return the current mutation probability

Setter:

Set the new mutation probability. If set to None, DEFAULT_MUTATION_PROB is chosen

Type:

float in (0, 1)

Raises:

  • TypeError – If set to a value which is not a real number

  • ValueError – If set to a value which is not in (0, 1)

property NSGA.gene_ind_mutation_prob: float

Get and set the gene independent mutation probability.

Getter:

Return the current gene independent mutation probability

Setter:

Set the new gene independent mutation probability. If set to None, DEFAULT_GENE_IND_MUTATION_PROB is chosen

Type:

float in (0, 1)

Raises:

  • TypeError – If set to a value which is not a real number

  • ValueError – If set to a value which is not in (0, 1)

property NSGA.selection_func_params: Dict[str, Any]

Get and set the parameters of the selection function.

Getter:

Return the current parameters for the selection function

Setter:

Set new parameters. If set to None, DEFAULT_NSGA_SELECTION_FUNC_PARAMS is chosen

Type:

A dict

Raises:

TypeError – If set to a value which is not a dict

property NSGA.nsga3_reference_points: Sequence

Get the set of reference points for NSGA-III.

Type:

Sequence

property NSGA.nsga3_reference_points_p: int

Get and set the p parameter for NSGA-III.

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

Getter:

Return the number of divisions

Setter:

Set a new number of divisions. If set to None, DEFAULT_NSGA3_REFERENCE_POINTS_P is chosen

Type:

int

Raises:

  • TypeError – If set to a value which is not an integer

  • ValueError – If set to a value lower than 1

property NSGA.nsga3_reference_points_scaling: float | None

Get and set the scaling factor for the reference points of NSGA-III.

Getter:

Return the scaling factor

Setter:

Set a new scaling factor

Type:

float or None

Raises:

TypeError – If set to a value which is not a float number

property NSGA.checkpoint_enable: bool

Enable or disable checkpointing.

Getter:

Return True if checkpoinitng is enabled, or False otherwise

Setter:

New value for the checkpoint enablement. If set to None, DEFAULT_CHECKPOINT_ENABLE is chosen

Type:

bool

Raises:

TypeError – If set to a value which is not boolean

property NSGA.checkpoint_freq: int

Get and set the checkpoint frequency.

Getter:

Return the checkpoint frequency

Setter:

Set a value for the checkpoint frequency. If set to None, DEFAULT_CHECKPOINT_FREQ is chosen

Type:

int

Raises:

  • TypeError – If set to a value which is not an integer

  • ValueError – If set to a value which is not a positive number

property NSGA.checkpoint_filename: str

Get and set the checkpoint file path.

Getter:

Return the checkpoint file path

Setter:

Set a new value for the checkpoint file path. If set to None, DEFAULT_CHECKPOINT_FILENAME is chosen

Type:

str

Raises:
property NSGA.verbose: bool

Get and set the verbosity of this trainer.

Getter:

Return the verbosity

Setter:

Set a new value for the verbosity. If set to None, __debug__ is chosen

Type:

bool

Raises:

TypeError – If set to a value which is not boolean

property NSGA.random_seed: int

Get and set the initial random seed used by this trainer.

Getter:

Return the seed

Setter:

Set a new value for the random seed

Type:

int

property NSGA.logbook: Logbook | None

Get the training logbook.

Return a logbook with the statistics of the search or None if the search has not been done yet.

Type:

Logbook

property NSGA.num_evals: int | None

Get the number of evaluations performed while training.

Return the number of evaluations or None if the search has not been done yet.

Type:

int

property NSGA.runtime: float | None

Get the training runtime.

Return the training runtime or None if the search has not been done yet.

Type:

float

property NSGA.index: int

Get and set the trainer index.

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

Getter:

Return the trainer index

Setter:

Set a new value for trainer index. If set to None, DEFAULT_INDEX is chosen

Type:

int

Raises:

  • TypeError – If set to a value which is not an integer

  • ValueError – If set to a value which is a negative number

property NSGA.container: Trainer | None

Get and set the container of this trainer.

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

Getter:

Return the container

Setter:

Set a new value for container of this trainer

Type:

Trainer

Raises:

TypeError – If set to a value which is not a valid trainer

property NSGA.representatives: Sequence[Sequence[Solution | None]] | None

Return the representatives of the other species.

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

property NSGA.pop: List[Individual] | None

Get the population.

Type:

list of Solution

Methods

NSGA.save_pickle(filename: str) → None

Pickle this object and save it to a file.

Parameters:

filename (str) – The file name.

Raises:
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, optional) – The fitness function. If omitted, the default training fitness function (fitness_function) is used

  • index (int, optional) – 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 of Sequence of Solution or None, optional) – 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.best_solutions() → Sequence[HallOfFame]

Get the best solutions found for each species.

Return the best single solution found for each species

Returns:

A list containing HallOfFame of solutions. One hof for each species

Return type:

list of 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 of list of Solution or None

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

Perform the training process.

Parameters:

state_proxy (DictProxy, optional) – Dictionary proxy to copy the output state of the trainer procedure. Only used if train is executed within a multiprocessing.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:
Raises:

  • TypeError – If any parameter has a wrong type

  • ValueError – If any parameter has an invalid value.

Private methods

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

Type:

dict

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._save_state() → None

Save the state at a new checkpoint.

Raises:

Exception – If the checkpoint file can’t be written

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._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._reset_state() → None

Reset the trainer state.

Overridden to reset the initial population.

NSGA._init_internals() → None

Set up the trainer internal data structures to start searching.

Overridden to support the NSGA-III reference points.

NSGA._reset_internals() → None

Reset the internal structures of the trainer.

Overridden to reset the NSGA-III reference points.

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.

Apply the search algorithm.

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

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._start_iteration() → None

Start an iteration.

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

NSGA._preprocess_iteration() → None

Preprocess before doing the iteration.

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

NSGA._do_iteration() → None

Implement an iteration of the search process.

In this case, a generation of NSGA is implemented.

NSGA._postprocess_iteration() → None

Postprocess after doing the iteration.

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

NSGA._finish_iteration() → None

Finish an iteration.

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

NSGA._do_iteration_stats() → None

Perform the iteration stats.

NSGA._default_termination_func() → bool

Set the default termination criterion.

Return True if max_num_iters iterations have been run.

NSGA._termination_criterion() → bool

Return true if the search should terminate.

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.

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._generate_initial_pop() → None

Generate the initial population.

The population is filled with random generated individuals.

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

Evaluate the individuals of pop that have an invalid fitness.

Parameters:

pop (list of Individual) – A population