`culebra.trainer.aco.MMAS` class¶

Bases: ReseteablePheromoneBasedACO, SingleObjACO

Create a new \({\small \mathcal{MAX}{-}\mathcal{MIN}}\) AS trainer.

Parameters:

fitness_func (FitnessFunction) – The training fitness function
solution_cls (type[Ant]) – The solution class
species (Species) – The species for the solutions
initial_pheromone (float | Sequence[float]) – Initial amount of pheromone for the paths of each pheromone matrix. Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the num_pheromone_matrices pheromone matrices.
heuristic (ndarray[float] | Sequence[ndarray[float], ...]) – Heuristic matrices. Both a single matrix or a sequence of matrices are allowed. If a single matrix is provided, it will be replicated for all the num_heuristic_matrices heuristic matrices. If omitted, _default_heuristic will be used. Defaults to None
pheromone_influence (float | Sequence[float]) – Relative influence of each pheromone matrix (\({\alpha}\)). Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the num_pheromone_matrices pheromone matrices. If omitted, _default_pheromone_influence will be used. Defaults to None
heuristic_influence (float | Sequence[float]) – Relative influence of each heuristic (\({\beta}\)). Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the num_heuristic_matrices heuristic matrices. If omitted, _default_heuristic_influence will be used. Defaults to None
exploitation_prob (float) – Probability to make the best possible move (\({q_0}\)). If omitted, _default_exploitation_prob will be used. Defaults to None
col_size (int) – The colony size. If omitted, _default_col_size will be used. Defaults to None
pheromone_evaporation_rate (float) – Pheromone evaluation rate (\({\rho}\)). If omitted, _default_pheromone_evaporation_rate will be used. Defaults to None
iter_best_use_limit (int) – Limit for the number of iterations to give up using the iteration-best ant to deposit pheromone. Iterations above this limit will use only the global-best ant. If omitted, _default_iter_best_use_limit will be used. Defaults to None
convergence_check_freq (int) – Convergence assessment frequency. If omitted, _default_convergence_check_freq 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 MMAS.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 MMAS.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 MMAS.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 MMAS.checkpoint_filename: str¶

Checkpoint file path.

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

property MMAS.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 MMAS.choice_info: ndarray[float] | None¶

Choice information for all the graph’s arcs.

The choice information is generated from both the pheromone and the heuristic matrices, modified by other parameters (depending on the ACO approach) and is used to obtain the probalility of following the next feasible arc for the node.

Returns:: The choice information or None if the training process has not begun
Return type:: ndarray[float]

property MMAS.col: list[Ant] | None¶

Colony.

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

property MMAS.col_size: int¶

Colony size.

Return type:

int

Setter:

Set a new value for the colony size

Parameters:

size (int) – The new colony size. If set to None, _default_col_size is chosen

Raises:

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

property MMAS.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 MMAS.convergence_check_freq: int¶

Convergence assessment frequency.

Return type:

int

Setter:

Set a value for the convergence assessment frequency

Parameters:

value (int) – New value for the convergence assessment frequency. If set to None, _default_convergence_check_freq is chosen

Raises:

TypeError – If value is not an integer number
ValueError – If value is non-positive

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

Current iteration.

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

property MMAS.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 MMAS.exploitation_prob: float¶

Exploitation probability (\({q_0}\)).

Return type:

float

Setter:

Set a new value for the exploitation probability

Parameters:

prob (float) – The new probability. If set to None, _default_exploitation_prob is chosen

Raises:

TypeError – If prob is not a real number
ValueError – If prob is not in [0, 1]

property MMAS.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 MMAS.heuristic: tuple[ndarray[float], ...]¶

Heuristic matrices.

Return type:

tuple[ndarray[float]]

Setter:

Set new heuristic matrices

Parameters:

values (ndarray[float] | Sequence[ndarray[float], ...]) – The new heuristic matrices. Both a single matrix or a sequence of matrices are allowed. If a single matrix is provided, it will be replicated for all the heuristic matrices. If set to None, _default_heuristic is chosen

Raises:

TypeError – If values is neither an numpy.ndarray nor a Sequence of numpy.ndarray
ValueError – If values is a sequence of numpy.ndarray and its length is not num_heuristic_matrices
ValueError – If any array has not the correct shape
ValueError – If any element in any array object is not a float number
ValueError – If any element in any array object is negative

property MMAS.heuristic_influence: tuple[float, ...]¶

Relative influence of heuristic (\({\beta}\)).

Returns:

One value for each heuristic matrix

Return type:

tuple[float]

Setter:

Set new values for the relative influence of each heuristic matrix

Parameters:

values (float | Sequence[float]) – New value for the relative influence of each heuristic matrix. Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the heuristic matrices. If set to None, _default_heuristic_influence is chosen

Raises:

TypeError – If values is neither a float nor a Sequence of float values
ValueError – If any element in values is negative
ValueError – If values is a sequence and it length is different from num_heuristic_matrices

abstract property MMAS.heuristic_shapes: tuple[tuple[int, int], ...]¶

Shape of the heuristic matrices.

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

Return type:: tuple[tuple[int]]
Raises:: NotImplementedError – If has not been overridden

property MMAS.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 MMAS.initial_pheromone: tuple[float, ...]¶

Initial value for each pheromone matrix.

Returns:

One initial value for each pheromone matrix

Return type:

tuple[float]

Setter:

Set the initial value for each pheromone matrix

Parameters:

values (float | Sequence[float]) – New initial value for each pheromone matrix. Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the pheromone matrices

Raises:

TypeError – If values is neither a float nor a Sequence of float values
ValueError – If any element in values is negative or zero
ValueError – If values is a sequence and it length is different from num_pheromone_matrices

property MMAS.iter_best_use_limit: int¶

Iteration-best use limit.

Iterations above this limit will use only the global-best ant.

Return type:

int

Setter:

Set a value for the iteration-best use limit

Parameters:

value (int) – New value for the iteration-best limit. If set to None, _default_iter_best_use_limit is chosen

Raises:

TypeError – If value is not an integer number
ValueError – If value is non-positive

property MMAS.iteration_metric_names: tuple(str)¶

Names of the metrics recorded each iteration.

Return type:: tuple[str]

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

Stats applied to each objective every iteration.

Return type:: dict

property MMAS.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 MMAS.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 MMAS.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 MMAS.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 MMAS.num_heuristic_matrices: int¶

Number of heuristic matrices used by this trainer.

Return type:: int

property MMAS.num_pheromone_matrices: int¶

Number of pheromone matrices used by this trainer.

Return type:: int

property MMAS.pheromone: list[ndarray[float], ...] | None¶

Pheromone matrices.

Returns:: The pheromone matrices or None if the training process has not begun
Return type:: list[ndarray[float]]

property MMAS.pheromone_evaporation_rate: float¶

Pheromone evaporation rate (\({\rho}\)).

Return type:

float

Setter:

Set a new value for the pheromone evaporation rate

Parameters:

value (float) – The new value for the pheromone evaporation rate. If set to None, _default_pheromone_evaporation_rate is chosen

Raises:

TypeError – If value is not a floating point number
ValueError – If value is outside (0, 1]

property MMAS.pheromone_influence: tuple[float, ...]¶

Relative influence of pheromone (\({\alpha}\)).

Returns:

One value for each pheromone matrix

Return type:

tuple[float]

Setter:

Set new values for the relative influence of each pheromone matrix

Parameters:

values (float | Sequence[float]) – New value for the relative influence of each pheromone matrix. Both a scalar value or a sequence of values are allowed. If a scalar value is provided, it will be used for all the pheromone matrices. If set to None, _default_pheromone_influence is chosen

Raises:

TypeError – If values is neither a float nor a Sequence of float values
ValueError – If any element in values is negative
ValueError – If values is a sequence and it length is different from num_pheromone_matrices

abstract property MMAS.pheromone_shapes: tuple[tuple[int, int], ...]¶

Shape of the pheromone matrices.

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

Return type:: tuple[tuple[int]]
Raises:: NotImplementedError – If has not been overridden

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

Training runtime.

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

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

Check if training has finished.

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

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

Default checkpointing activation.

Returns:: DEFAULT_CHECKPOINT_ACTIVATION
Return type:: bool

property MMAS._default_checkpoint_basename: str¶

Default checkpointing base file name.

Returns:: DEFAULT_CHECKPOINT_BASENAME
Return type:: str

property MMAS._default_checkpoint_freq: int¶

Default checkpointing frequency.

Returns:: DEFAULT_CHECKPOINT_FREQ
Return type:: int

abstract property MMAS._default_col_size: int¶

Default colony size.

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

Return type:: int
Raises:: NotImplementedError – If has not been overridden

property MMAS._default_convergence_check_freq: float¶

Default convergence assessment frequency.

Returns:: The DEFAULT_CONVERGENCE_CHECK_FREQ
Return type:: float

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

Default cooperative fitness estimation function.

Return the average of all fitness trials.

property MMAS._default_exploitation_prob: float¶

Default exploitation probability (\({q_0}\)).

Returns:: DEFAULT_AS_EXPLOITATION_PROB
Return type:: float

abstract property MMAS._default_heuristic: tuple[ndarray[float], ...]¶

Default heuristic matrices.

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

Return type:: tuple[ndarray[float]]
Raises:: NotImplementedError – If has not been overridden

property MMAS._default_heuristic_influence: tuple[float, ...]¶

Default relative influence of heuristic (\({\beta}\)).

Returns:: The DEFAULT_HEURISTIC_INFLUENCE for each pheromone matrix
Return type:: tuple[float]

property MMAS._default_index: int¶

Default index.

Returns:: DEFAULT_INDEX
Return type:: int

property MMAS._default_iter_best_use_limit: int¶

Default iteration-best use limit.

Returns:: DEFAULT_MMAS_ITER_BEST_USE_LIMIT
Return type:: int

property MMAS._default_max_num_iters: int¶

Default maximum number of iterations.

Returns:: DEFAULT_MAX_NUM_ITERS
Return type:: int

property MMAS._default_pheromone_evaporation_rate: float¶

Default pheromone evaporation rate (\({\rho}\)).

Returns:: The DEFAULT_PHEROMONE_EVAPORATION_RATE
Return type:: float

property MMAS._default_pheromone_influence: tuple[float, ...]¶

Default relative influence of pheromone (\({\alpha}\)).

Returns:: The DEFAULT_PHEROMONE_INFLUENCE for each pheromone matrix
Return type:: tuple[float]

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

Default implementation for the representatives reception function.

It does nothing.

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

Default implementation for the representatives sending function.

It does nothing.

property MMAS._default_verbosity: bool¶

Default verbosity.

Returns:: DEFAULT_VERBOSITY
Return type:: bool

property MMAS._global_best_freq: int¶

Use frequency of the global-best solution to deposit pheromone.

Implement the schedule to choose between the iteration-best and the global-best ant. The global-best use frequency will vary according to current_iter and iter_best_use_limit.

Return type:: int

Methods¶

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

MMAS.best_solutions() → tuple[HallOfFame]¶

Get the best solutions found for each species.

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

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

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

MMAS.integrate_representatives(representatives: list[Ant]) → None¶

Integrate representative solutions.

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

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

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

MMAS.select_representatives() → list[Ant]¶

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[Ant]

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

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

Private methods¶

abstract MMAS._ant_choice_info(ant: Ant) → ndarray[float]¶

Return the choice info to obtain the next node the ant will visit.

Parameters:: ant (Ant) – The ant
Return type:: ndarray[float]

This method should be overridden by subclasses.

Raises:: NotImplementedError – If has not been overridden

abstract MMAS._calculate_choice_info() → None¶

Calculate the choice information.

This method should be overridden by subclasses.

Raises:: NotImplementedError – If has not been overridden

MMAS._decrease_pheromone() → None¶

Decrease the amount of pheromone.

Apply pheromone evaporation.

MMAS._default_termination_func() → bool¶

Default termination criterion.

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

MMAS._deposit_pheromone(ants: Sequence[Ant], weight: float = 1.0) → None¶

Make some ants deposit weighted pheromone.

This method must be overridden by subclasses to take into account the correct number and shape of the pheromone matrices.

Parameters:

ants (Sequence[Ant]) – The ants
weight (float) – Weight for the pheromone. Defaults to DEFAULT_PHEROMONE_DEPOSIT_WEIGHT

Raises:

NotImplementedError – If has not been overridden

MMAS._do_iteration() → None¶: Implement an iteration of the training process.

MMAS._do_training() → None¶

Apply the training algorithm.

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

MMAS._finish_iteration() → None¶

Finish an iteration.

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

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

MMAS._generate_ant() → Ant¶

Generate a new ant.

The ant makes its path and gets evaluated.

Returns:: The new ant
Return type:: Ant

MMAS._generate_col() → None¶: Fill the colony with evaluated ants.

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

Generate cooperators from other species.

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

MMAS._get_iteration_metrics() → dict¶

Collect the iteration metrics.

Returns:: The metrics
Return type:: dict

MMAS._get_objective_stats() → dict¶

Gather the objective stats.

Returns:: The stats
Return type:: dict

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

Return the state of this trainer.

Overridden to add the pheromone limits and the last iteration number when the elite was updated to the trainer’s state.

Return type:: dict

MMAS._has_converged() → bool¶

Detect if the trainer has converged.

Returns:: True if the trainer has converged
Return type:: bool

MMAS._increase_pheromone() → None¶

Increase the amount of pheromone.

Overridden to choose between the iteration-best and global-best ant depending on the _global_best_freq frequency.

MMAS._init_internals() → None¶

Set up the trainer internal data structures to start training.

Create all the internal objects, functions and data structures needed to run the training process. For the ACO class, the colony, the choice_info matrix and the node list are created. Subclasses which need more objects or data structures should override this method.

MMAS._init_pheromone() → None¶: Init the pheromone matrix.

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

MMAS._init_training() → None¶

Init the training process.

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

MMAS._load_state() → None¶

Load the state of the last checkpoint.

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

MMAS._new_state() → None¶

Generate a new trainer state.

Overridden to initialize the pheromone limits and the last iteration number when the elite was updated.

MMAS._next_choice(ant: Ant) → int | None¶

Choose the next node for an ant.

The election is made from the feasible neighborhood of the current node, which is composed of those nodes neither discarded nor visited yet by the ant and connected to its current node. Any node forbidden by the constraints of the :class:~culebra.abc.Species defining the problem is also unfeasible.

The best possible node is selected with probability exploitation_prob. In case the best node is not chosen, the next node is selected probabilistically according to the choice_info matrix.

Parameters:: ant (Ant) – The ant
Returns:: The index of the chosen node or None if there isn’t any feasible node
Return type:: int

MMAS._pheromone_amount(ant: Ant) → tuple[float, ...]¶

Return the amount of pheromone to be deposited by an ant.

The reciprocal of an objective fitness value will be used for minimization objectives, while the objective’s fitness value is used for maximization objectives.

Parameters:: ant (Ant) – The ant
Returns:: The amount of pheromone to be deposited for each objective
Return type:: tuple[float]

MMAS._reset_internals() → None¶

Reset the internal structures of the trainer.

Overridden to reset the colony, the choice_info matrix and the node list. If subclasses overwrite the _init_internals() method to add any new internal object, this method should also be overridden to reset all the internal objects of the trainer.

MMAS._reset_state() → None¶

Reset the trainer state.

Overridden to reset the pheromone limits and the last iteration number when the elite was updated.

MMAS._save_state() → None¶

Save the state at a new checkpoint.

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

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

Set the state of this trainer.

Overridden to add the pheromone limits and the last iteration number when the elite was updated to the trainer’s state.

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

MMAS._should_reset_pheromone() → bool¶

Detect if the trainer should be reseted.

Returns:: True if pheromone should be reset
Return type:: bool

MMAS._start_iteration() → None¶

Start an iteration.

Prepare the iteration metrics (number of evaluations, execution time) before each iteration is run and create an empty ant colony. Overridden to calculate the choice information before executing the next iteration.

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

MMAS._unfeasible_nodes(ant: Ant) → ndarray[float]¶

Return the indices of all unfeasible nodes.

Subclasses should also filter out any node forbidden by the constraints of the :class:~culebra.abc.Species defining the problem.

Parameters:: ant (Ant) – The ant
Returns:: All nodes visited by the ant, whether selected or discarded
Return type:: ndarray[float]

MMAS._update_elite() → None¶

Update the elite (best-so-far) ant.

The pheromone limits and the elite updation iteration number are modified accordingly.

MMAS._update_logbook() → None¶

Append the iteration dato to the logbook.

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

MMAS._update_pheromone() → None¶

Update the pheromone trails.

First, the pheromone are evaporated. Then ants deposit pheromone according to their fitness. Finally, the max and min limits for the pheromone are checked.

culebra.trainer.aco.MMAS class¶

Class methods¶

Properties¶

Private properties¶

Methods¶

Private methods¶

`culebra.trainer.aco.MMAS` class¶