`culebra.trainer.abc.CentralizedTrainer` class¶

class CentralizedTrainer(fitness_func: FitnessFunction, solution_cls: type[Solution], species: Species, custom_termination_func: Callable[[CentralizedTrainer], 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: Trainer

Create a new trainer.

Parameters:

fitness_func (FitnessFunction) – The training fitness function
solution_cls (type[Solution]) – The solution class
species (Species) – The species for the solutions
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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.checkpoint_filename: str¶

Checkpoint file path.

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

property CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.current_iter: int | None¶

Current iteration.

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

property CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.iteration_metric_names: tuple(str)¶

Names of the metrics recorded each iteration.

Return type:: tuple[str]

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

Stats applied to each objective every iteration.

Return type:: dict

property CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.runtime: float | None¶

Training runtime.

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

property CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.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 CentralizedTrainer.training_finished: bool¶

Check if training has finished.

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

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

Default checkpointing activation.

Returns:: DEFAULT_CHECKPOINT_ACTIVATION
Return type:: bool

property CentralizedTrainer._default_checkpoint_basename: str¶

Default checkpointing base file name.

Returns:: DEFAULT_CHECKPOINT_BASENAME
Return type:: str

property CentralizedTrainer._default_checkpoint_freq: int¶

Default checkpointing frequency.

Returns:: DEFAULT_CHECKPOINT_FREQ
Return type:: int

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

Default cooperative fitness estimation function.

Return the average of all fitness trials.

property CentralizedTrainer._default_index: int¶

Default index.

Returns:: DEFAULT_INDEX
Return type:: int

property CentralizedTrainer._default_max_num_iters: int¶

Default maximum number of iterations.

Returns:: DEFAULT_MAX_NUM_ITERS
Return type:: int

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

Default implementation for the representatives reception function.

It does nothing.

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

Default implementation for the representatives sending function.

It does nothing.

property CentralizedTrainer._default_verbosity: bool¶

Default verbosity.

Returns:: DEFAULT_VERBOSITY
Return type:: bool

Methods¶

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

abstract CentralizedTrainer.best_solutions() → tuple[HallOfFame]¶

Get the best solutions found for each species.

This method must be overridden by subclasses to return a correct value.

Returns:: One Hall of Fame for each species
Return type:: tuple[HallOfFame]
Raises:: NotImplementedError – If has not been overridden

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

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

abstract CentralizedTrainer.integrate_representatives(representatives: list[Solution]) → None¶

Integrate representative solutions.

This abtract method is intended to be called within distributed trainers to make the implementation of migrations easier. It should be implemented by subclasses in order to achieve the desired behavior.

Parameters:: representatives (list[Solution]) – A list of solutions
Raises:: NotImplementedError – If has not been overridden

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

abstract CentralizedTrainer.select_representatives() → list[Solution]¶

Select representative solutions.

Returns:: A list of solutions
Return type:: list[Solution]
Raises:: NotImplementedError – If has not been overridden

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

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

Private methods¶

CentralizedTrainer._default_termination_func() → bool¶

Default termination criterion.

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

abstract CentralizedTrainer._do_iteration() → None¶

Implement an iteration of the training process.

This abstract method should be implemented by subclasses in order to implement the desired behavior. :raises NotImplementedError: If has not been overridden

CentralizedTrainer._do_training() → None¶

Apply the training algorithm.

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

_start_iteration()
receive_representatives_func()
_do_iteration()
send_representatives_func()
_finish_iteration()
_update_logbook()

CentralizedTrainer._finish_iteration() → None¶

Finish an iteration.

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

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

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

Generate cooperators from other species.

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

CentralizedTrainer._get_iteration_metrics() → dict¶

Collect the iteration metrics.

Returns:: The metrics
Return type:: dict

abstract CentralizedTrainer._get_objective_stats() → dict¶

Gather the objective stats.

This method should be implemented by subclasses in order to perform the adequate stats each iteration.

Returns:: The stats
Return type:: dict
Raises:: NotImplementedError – If has not been overridden

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

Return the state of this trainer.

Overridden to add the cooperators, the logbook, and the current number of evaluations, runtime, iteration and random state.

Return type:: dict

CentralizedTrainer._init_internals() → None¶

Set up the trainer internal data structures to start training.

Init the statistics and the number of evaluations and start time of the current iteration.

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

CentralizedTrainer._init_training() → None¶

Init the training process.

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

CentralizedTrainer._load_state() → None¶

Load the state of the last checkpoint.

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

CentralizedTrainer._new_state() → None¶

Generate a new trainer state.

Init the cooperators, the logbook, and the current iteration, number of evaluations and runtime.

CentralizedTrainer._reset_internals() → None¶

Reset the internal structures of the trainer.

Reset the statistics and the number of evaluations and start time of the current iteration.

CentralizedTrainer._reset_state() → None¶

Reset the trainer state.

Reset the cooperators, the logbook, and the current iteration, number of evaluations and runtime.

CentralizedTrainer._save_state() → None¶

Save the state at a new checkpoint.

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

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

Set the state of this trainer.

Overridden to add the cooperators, the logbook, and the current number of evaluations, runtime, iteration and random state.

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

CentralizedTrainer._start_iteration() → None¶

Start an iteration.

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

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

CentralizedTrainer._update_logbook() → None¶

Append the iteration dato to the logbook.

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

culebra.trainer.abc.CentralizedTrainer class¶

Class methods¶

Properties¶

Private properties¶

Methods¶

Private methods¶

`culebra.trainer.abc.CentralizedTrainer` class¶