propulate.propulator

Module Contents

Classes

Propulator

Initialize Propulator with given parameters.

Attributes

log

SURROGATE_KEY

propulate.propulator.log
propulate.propulator.SURROGATE_KEY: Final[str] = '_s'
class propulate.propulator.Propulator(loss_fn: Callable | Generator[float, None, None], propagator: propulate.propagators.Propagator, rng: random.Random, island_idx: int = 0, island_comm: mpi4py.MPI.Comm = MPI.COMM_WORLD, propulate_comm: mpi4py.MPI.Comm = MPI.COMM_WORLD, worker_sub_comm: mpi4py.MPI.Comm = MPI.COMM_SELF, generations: int = -1, checkpoint_path: str | pathlib.Path = Path('./'), migration_topology: numpy.ndarray | None = None, migration_prob: float = 0.0, emigration_propagator: Type[propulate.propagators.Propagator] = SelectMin, island_displs: numpy.ndarray | None = None, island_counts: numpy.ndarray | None = None, surrogate_factory: Callable[[], propulate.surrogate.Surrogate] | None = None)

Initialize Propulator with given parameters.

Parameters:

  • loss_fn (Union[Callable, Generator[float, None, None]]) – The loss function to be minimized.

  • propagator (propulate.propagators.Propagator) – The propagator to apply for breeding.

  • rng (random.Random) – The separate random number generator for the Propulate optimization.

  • island_idx (int, optional) – The island’s index. Default is 0.

  • island_comm (MPI.Comm, optional) – The intra-island communicator. Default is MPI.COMM_WORLD.

  • propulate_comm (MPI.Comm, optional) – The Propulate world communicator, consisting of rank 0 of each worker’s sub communicator. Default is MPI.COMM_WORLD.

  • worker_sub_comm (MPI.Comm, optional) – The sub communicator for each (multi rank) worker. Default is MPI.COMM_SELF.

  • generations (int, optional) – The number of generations to run. Default is -1, i.e., run into wall-clock time limit.

  • checkpoint_path (pathlib.Path | str, optional) – The path where checkpoints are loaded from and stored. Default is current working directory.

  • migration_topology (numpy.ndarray, optional) – The migration topology, i.e., a 2D matrix where entry (i,j) specifies how many individuals are sent by island i to island j.

  • migration_prob (float, optional) – The per-worker migration probability. Default is 0.0.

  • emigration_propagator (Type[propulate.propagators.Propagator], optional) – The emigration propagator, i.e., how to choose individuals for emigration that are sent to destination island. Should be some kind of selection operator. Default is SelectMin.

  • island_displs (numpy.ndarray, optional) – An array with propulate_comm rank of each island’s worker 0. Element i specifies the rank of worker 0 on island with index i in the Propulate communicator.

  • island_counts (numpy.ndarray, optional) – An array with the number of workers per island. Element i specifies the number of workers on island with index i.

  • surrogate_factory (Callable[[], propulate.surrogate.Surrogate], optional) – Function that returns a new instance of a Surrogate model. Only used when loss_fn is a generator function.

_get_active_individuals() → Tuple[List[propulate.population.Individual], int]

Get active individuals in current population list.

Returns:

  • List[propulate.population.Individual] – All active individuals in the current population.

  • int – The number of currently active individuals.

_breed() → propulate.population.Individual

Apply propagator to current population of active individuals to breed new individual.

Returns:

The newly bred individual.

Return type:

propulate.population.Individual

_evaluate_individual() → None

Breed and evaluate individual.

_receive_intra_island_individuals() → None

Check for and possibly receive incoming individuals evaluated by other workers within own island.

abstract _send_emigrants() → None

Perform migration, i.e., island sends individuals out to other islands.

Raises:

NotImplementedError – Not implemented in Propulator base class. Exact migration and pollination behavior is defined in the Migrator and Pollinator classes, respectively.

abstract _receive_immigrants() → None

Check for and possibly receive immigrants send by other islands.

Raises:

NotImplementedError – Not implemented in Propulator base class. Exact migration and pollination behavior is defined in the Migrator and Pollinator classes, respectively.

_get_unique_individuals() → List[propulate.population.Individual]

Get unique individuals in terms of traits and loss in current population.

Returns:

All unique individuals in the current population.

Return type:

List[propulate.population.Individual]

_check_intra_island_synchronization(populations: List[List[propulate.population.Individual]]) → bool

Check synchronization of populations of workers within one island.

Parameters:

populations (List[List[propulate.population.Individual]]) – A list of all islands’ sorted population lists.

Returns:

True if populations are synchronized, False if not.

Return type:

bool

propulate(logging_interval: int = 10, debug: int = -1) → None

Execute evolutionary algorithm in parallel.

Parameters:

  • logging_interval (int, optional) – Print each worker’s progress every logging_interval-th generation. Default is 10.

  • debug (int, optional) – The debug level; 0 - silent; 1 - moderate, 2 - noisy (debug mode). Default is 1.

Raises:

ValueError – If any individuals are left that should have been deactivated before (only for debug > 0).

_dump_checkpoint() → None

Dump checkpoint to file.

_determine_worker_dumping_next() → bool

Determine the worker who dumps the checkpoint in the next generation.

_dump_final_checkpoint() → None

Dump final checkpoint.

_check_for_duplicates(active: bool, debug: int = 1) → Tuple[List[List[propulate.population.Individual | int]], List[propulate.population.Individual]]

Check for duplicates in current population.

For pollination, duplicates are allowed as emigrants are sent as copies and not deactivated on sending island.

Parameters:

  • active (bool) – Whether to consider active individuals (True) or all individuals (False).

  • debug (int, optional) – The debug level; 0 - silent; 1 - moderate, 2 - noisy (debug mode). Default is 1.

Returns:

  • List[List[propulate.population.Individual | int]] – The individuals and their occurrences.

  • List[propulate.population.Individual] – The unique individuals in the population.

summarize(top_n: int = 1, debug: int = 1) → List[List[propulate.population.Individual] | propulate.population.Individual] | None

Get top-n results from Propulate optimization.

Parameters:

  • top_n (int, optional) – The number of best results to report. Default is 1.

  • debug (int, optional) – The debug level; 0 - silent; 1 - moderate, 2 - noisy (debug mode). Default is 1.

Returns:

The top-n best individuals on each island.

Return type:

List[List[propulate.population.Individual] | propulate.population.Individual]