culebra.trainer.aco.abc.SingleObjACO class

class SingleObjACO(solution_cls: Type[Ant], species: Species, fitness_function: FitnessFunction, initial_pheromone: float | Sequence[float, ...], heuristic: Sequence[Sequence[float], ...] | Sequence[Sequence[Sequence[float], ...], ...] | None = None, pheromone_influence: float | Sequence[float, ...] | None = None, heuristic_influence: float | Sequence[float, ...] | None = None, max_num_iters: int | None = None, custom_termination_func: Callable[[SingleColACO], bool] | None = None, col_size: int | 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 single-colony ACO trainer.

Parameters:

  • solution_cls (An Ant subclass) – The ant class

  • species (Species) – The species for all the ants

  • fitness_function (FitnessFunction) – The training fitness function

  • initial_pheromone (float or Sequence of 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 (A two-dimensional array-like object or a Sequence of two-dimensional array-like objects, optional) – 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, the default heuristic matrices provided by fitness_function are assumed. Defaults to None

  • pheromone_influence (float or Sequence of float, optional) – 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 for all the pheromone matrices. Defaults to None

  • heuristic_influence (float or Sequence of float, optional) – 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 for all the heuristic matrices. Defaults to None

  • max_num_iters (int, optional) – Maximum number of iterations. If set to None, DEFAULT_MAX_NUM_ITERS will be used. Defaults to None

  • custom_termination_func (Callable, optional) – Custom termination criterion. If set to None, the default termination criterion is used. Defaults to None

  • col_size (int, greater than zero, optional) – The colony size. If set to None, fitness_function’s num_nodes will be used. Defaults to None

  • checkpoint_enable (bool, optional) – Enable/disable checkpoining. If set to None, DEFAULT_CHECKPOINT_ENABLE will be used. Defaults to None

  • checkpoint_freq (int, optional) – The checkpoint frequency. If set to None, DEFAULT_CHECKPOINT_FREQ will be used. Defaults to None

  • checkpoint_filename (str, optional) – The checkpoint file path. If set to None, DEFAULT_CHECKPOINT_FILENAME will be used. Defaults to None

  • verbose (bool, optional) – The verbosity. If set to None, __debug__ will be used. Defaults to None

  • random_seed (int, optional) – 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

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

Statistics calculated each iteration.

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

Statistics calculated for each objective.

Class methods

classmethod SingleObjACO.load_pickle(filename: str) → Base

Load a pickled object from a file.

Parameters:

filename (str) – The file name.

Raises:

Properties

property SingleObjACO.num_pheromone_matrices: int

Get the number of pheromone matrices used by this trainer.

Type:

int

property SingleObjACO.num_heuristic_matrices: int

Get the number of heuristic matrices used by this trainer.

Type:

int

property SingleObjACO.solution_cls: Type[Ant]

Get and set the ant class.

Getter:

Return the ant class

Setter:

Set a new ant class

Type:

An Ant subclass

Raises:

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

property SingleObjACO.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 SingleObjACO.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

  • ValueError – If set to a fitness function with more than one objective

property SingleObjACO.initial_pheromone: Sequence[float, ...]

Get and set the initial value for each pheromone matrix.

Getter:

Return the initial value for each pheromone matrix.

Setter:

Set a 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 num_pheromone_matrices pheromone matrices.

Type:

Sequence of float

Raises:
property SingleObjACO.heuristic: Sequence[np.ndarray, ...]

Get and set the heuristic matrices.

Getter:

Return the heuristic matrices

Setter:

Set 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 num_heuristic_matrices heuristic matrices. If set to None, the default heuristic (provided by the fitness_function property) are assumed.

Type:

Sequence of ndarray

Raises:

  • TypeError – If neither an array-like object nor a Sequence of array-like objects is provided

  • ValueError – If any element in any array-like object is not a float number

  • ValueError – If any array-like object has not an homogeneous shape

  • ValueError – If any array-like object has not two dimensions

  • ValueError – If any array-like object is not square

  • ValueError – If any element in any array-like object is negative

  • ValueError – If a sequence is provided and it length is different from num_heuristic_matrices

  • ValueError – If the array-like objects have different shapes

property SingleObjACO.pheromone_influence: Sequence[float, ...]

Get and set the influence of pheromone (\({\alpha}\)).

Getter:

Return the relative influence of each pheromone matrix.

Setter:

Set a 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 num_pheromone_matrices pheromone matrices. If set to None, DEFAULT_PHEROMONE_INFLUENCE is chosen.

Type:

Sequence of float

Raises:
property SingleObjACO.heuristic_influence: Sequence[float, ...]

Get and set the relative influence of heuristic (\({\beta}\)).

Getter:

Return the relative influence of each heuristic matrix.

Setter:

Set a 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 num_heuristic_matrices heuristic matrices. If set to None, DEFAULT_HEURISTIC_INFLUENCE is chosen.

Type:

Sequence of float

Raises:
property SingleObjACO.pheromone: Sequence[np.ndarray, ...] | None

Get the pheromone matrices.

If the search process has not begun, None is returned.

Type:

Sequence of ndarray

property SingleObjACO.choice_info: ndarray | None

Get the 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.

If the search process has not begun, None is returned.

Type:

ndarray

property SingleObjACO.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 SingleObjACO.current_iter: int

Return the current iteration.

Type:

int

property SingleObjACO.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 SingleObjACO.col_size: int

Get and set the colony size.

Getter:

Return the current colony size

Setter:

Set a new value for the colony size. If set to None, fitness_function’s num_nodes is chosen

Type:

int, greater than zero

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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.runtime: float | None

Get the training runtime.

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

Type:

float

property SingleObjACO.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 SingleObjACO.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 SingleObjACO.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 SingleObjACO.col: List[Ant] | None

Get the colony.

Type:

list of Solution

Methods

SingleObjACO.save_pickle(filename: str) → None

Pickle this object and save it to a file.

Parameters:

filename (str) – The file name.

Raises:
SingleObjACO.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.

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

abstract SingleObjACO.best_solutions() → Sequence[HallOfFame]

Get the best solutions found for each species.

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

Returns:

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

Return type:

list of HallOfFame

Raises:

NotImplementedError – If has not been overridden

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

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

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

SingleObjACO._get_state() → Dict[str, Any]

Return the state of this trainer.

Default state is a dictionary composed of the values of the logbook, num_evals, runtime, current_iter, and representatives trainer properties, along with a private boolean attribute that informs if the search has finished and also the states of the random and numpy.random modules.

If subclasses use any more properties to keep their state, the _get_state() and _set_state() methods must be overridden to take into account such properties.

Type:

dict

SingleObjACO._set_state(state: Dict[str, Any]) → None

Set the state of this trainer.

If subclasses use any more properties to keep their state, the _get_state() and _set_state() methods must be overridden to take into account such properties.

Parameters:

state (dict) – The last loaded state

SingleObjACO._save_state() → None

Save the state at a new checkpoint.

Raises:

Exception – If the checkpoint file can’t be written

SingleObjACO._load_state() → None

Load the state of the last checkpoint.

Raises:

Exception – If the checkpoint file can’t be loaded

SingleObjACO._new_state() → None

Generate a new trainer state.

If subclasses add any new property to keep their state, this method should be overridden to initialize the full state of the trainer.

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

SingleObjACO._reset_state() → None

Reset the trainer state.

If subclasses overwrite the _new_state() method to add any new property to keep their state, this method should also be overridden to reset the full state of the trainer.

SingleObjACO._init_internals() → None

Set up the trainer internal data structures to start searching.

Create all the internal objects, functions and data structures needed to run the search process. For the SingleColACO 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.

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

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.

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

SingleObjACO._preprocess_iteration() → None

Preprocess before doing the iteration.

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

SingleObjACO._do_iteration() → None

Implement an iteration of the search process.

SingleObjACO._postprocess_iteration() → None

Postprocess after doing the iteration.

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

SingleObjACO._finish_iteration() → None

Finish an iteration.

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

SingleObjACO._do_iteration_stats() → None

Perform the iteration stats.

SingleObjACO._default_termination_func() → bool

Set the default termination criterion.

Return True if max_num_iters iterations have been run.

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

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

SingleObjACO._calculate_choice_info() → None

Calculate the choice info matrix.

SingleObjACO._initial_choice(ant: Ant) → int | None

Choose the initial node for an ant.

The selection is made randomly among all connected nodes, avoiding already discarded nodes.

Parameters:

ant (Ant) – The ant

Returns:

The index of the chosen node or None if there isn’t any feasible node

Return type:

int or None

SingleObjACO._next_choice(ant: Ant) → int | None

Choose the next node for an ant.

The election is based on the feasible neighborhood probabilities of the ant’s current node. If the ant’s path is empty, the _initial_choice() method is called.

Parameters:

ant (Ant) – The ant

Returns:

The index of the chosen node or None if there isn’t any feasible node

Return type:

int or None

SingleObjACO._feasible_neighborhood_probs(ant: Ant) → ndarray

Return the probabilities of the feasible neighborhood of an ant.

The feasible neighborhood is composed of those nodes not visited yet by the ant and connected to its current node. Each of these nodes has a probability of being visited from the current node, which is calculated from the choice_info matrix.

Parameters:

ant (Ant) – The ant

Raises:

ValueError – If ant has not a current node.

Returns:

An array with the probability of following each feasible node from the current node of ant

Return type:

ndarray

SingleObjACO._generate_ant() → Ant

Generate a new ant.

The ant makes its path and gets evaluated.

SingleObjACO._generate_col() → None

Fill the colony with evaluated ants.

SingleObjACO._init_pheromone() → None

Init the pheromone matrix(ces) according to the initial value(s).

SingleObjACO._deposit_pheromone(ants: Sequence[Ant], weight: float | None = 1) → None

Make some ants deposit weighted pheromone.

A symmetric problem is assumed. Thus if (i, j) is an arc in an ant’s path, arc (j, i) is also incremented the by same amount.

Parameters:

  • ants (Sequence of Ant) – The ants

  • weight (float, optional) – Weight for the pheromone. Defaults to 1

abstract SingleObjACO._increase_pheromone() → None

Increase the amount of pheromone.

This method should be overridden by subclasses.

abstract SingleObjACO._decrease_pheromone() → None

Decrease the amount of pheromone.

This method should be overridden by subclasses.

SingleObjACO._update_pheromone() → None

Update the pheromone trails.

First, the pheromone are evaporated. Then ants deposit pheromone according to their fitness.