evokit.core package

Subpackages

• evokit.core.accelerator package
  • Submodules
  • evokit.core.accelerator.parallelisers module
    • parallelise_task()
    • __getstate__()
    • __deepcopy__()
  • Module contents
    • parallelise_task()

Submodules

evokit.core.algorithm module

class evokit.core.algorithm.Algorithm

Bases: ABC

Base class for all evolutionary algorithms.

Derive this class to create custom algorithms.

Tutorial: Making a Custom Algorithm.

static __new__(cls: Type[Self], *_: Any, **__: Any) → Self

Machinery.

Implement managed attributes.

abstract __init__(*args: Any, **kwargs: Any) → None

Subclasses should override this method.

Initialise the state of an algorithm, including operators, the initial population(s), truncation strategy, and other parameters associated with the learning process as a whole.

events: list[str] = []

automatic_events: list[str] = ['STEP_BEGIN', 'STEP_END']

abstract step(*args: Any, **kwargs: Any) → None

Advance the population by one generation.

Subclasses should override this method. Use operators to update the population (or populations). Call update() to fire events for data collection mechanisms such as accountant.Accountant.

Note

The generation attribute increments by 1 _after_ step() is called. Do not manually increment generation. This property is automatically managed.

Calling step() automatically fires two events via update(): “STEP_BEGIN” before and “STEP_END” after. This behaviour cannot be suppressed. For more on events, see accountant.Accountant. Be advised that these automatic events are fired just like any other event – nothing prevents you from firing them inside step(). The automatic_events class attribute reports these events, like how events reports regular events.

register(accountant: Accountant[Any, Any]) → None

Attach an Accountant to this algorithm.

Parameters:

accountant – The accountant to attach.

update(event: str) → None

Report an event to all attached Accountant objects.

If the event is not in events, raise an exception.

Parameters:

event – The event to report.

Raises:

ValueError – if an reported event is not declared in events and is not an automatically reported event in automatic_events.

evokit.core.evaluator module

class evokit.core.evaluator.Evaluator

Bases: ABC, Generic[D]

Base class for all evaluators.

Derive this class to create custom evaluators.

Tutorial: Getting Started with OneMax.

static __new__(cls, *args: Any, **kwargs: Any) → Self

Machinery.

Implement managed attributes.

__init__(*args, processes: int | ProcessPoolExecutor | None = None, share_self: bool = False, **kwargs) → None

See Variator for parameters processes and share_self.

retain_fitness: bool

If this evaluator should re-evaluate an Individual whose fitness is already set.

abstract evaluate(individual: D, *args: Any, **kwargs: Any) → tuple[float, ...]

Evaluation strategy. Return the fitness of an individual.

Subclasses should override this method.

Note

“Better” individuals should have higher fitness.

Selector should prefer individuals with higher fitness.

Parameters:

individual – individual to evaluate

evaluate_population(pop: Population[D], *args: Any, **kwargs: Any) → None

Context of evaluate().

Iterate individuals in a population. For each individual, compute its fitness with evaluate(), then assign that value to its Individual.fitness.

A subclass may override this method to implement behaviours that require access to the entire population.

Effect:

For each item in pop, set its Individual.fitness.

Note

This method must never return a value. It must assign to fitness for each Individual in the Population.

evokit.core.population module

class evokit.core.population.Individual

Bases: ABC, Generic[R]

Base class for all individuals.

Derive this class to create custom representations.

The individual stores the encoding (genome) and fitness (fitness) of a representation.

The individual can information outside of the genotype, such as a

.fitness, a reference to the parent, and strategy parameter(s).

Note

Implementation should store the genotype in genome.

Tutorial: Getting Started with OneMax.

static __new__(cls: Type[Self], *args: Any, **kwargs: Any) → Self

Machinery.

Implement managed attributes.

abstract __init__() → None

genome: R

Genotype of the individual.

property fitness: tuple[float, ...]

Fitness of an individual.

Writing to this property changes the fitness of the individual. If this individual has yet to be assigned a fitness, reading from this property raises an exception.

To determine if the individual has a fitness, call has_fitness().

Returns:

Fitness of the individual

Warning

If the current fitness is None, return (nan,). This may happen when, for example, an offspring has just been produced.

reset_fitness() → None

Reset the fitness of the individual.

Effect:

The fitness of this individual becomes None.

has_fitness() → bool

Return True if fitness is not None. Otherwise, return False.

abstract copy() → Self

Return an identical copy of the individual.

Subclasses should override this method.

Operations on in this individual should not affect the new individual. In addition to duplicating genome, the implementation should decide whether to retain other fields such as fitness.

Note

Ensure that changes made to the returned value do not affect the original value.

class evokit.core.population.Population

Bases: UserList[D], Generic[D]

A flat collection of individuals.

__init__(initlist: Sequence[D] | None | Iterable[D] = None)

Parameters:

args – Initial items in the population

copy() → Self

Return an independent population.

Changes made to items in the new population should not affect items in this population. This behaviour depends on correct implementation of Individual.copy() in each item.

Call Individual.copy() for each Individual in this population. Collect the results, then create a new population with these values.

reset_fitness() → None

Remove fitness values of all Individuals in the population.

Effect:

For each item in this population, set its fitness Individual.fitness to None.

best() → D

Return the highest-fitness individual in this population.

evokit.core.selector module

class evokit.core.selector.Selector

Bases: ABC, Generic[D]

Base class for all selectors.

Derive this class to create custom selectors.

Tutorial: Making a Custom Selector.

__init__(budget: int, *args: Any, **kwargs: Any)

Parameters:

budget – Number of individuals to select.

Note

Implementations that select a variable number of individuals may ignore budget.

budget

Declared size of the output population

select_population(from_population: Population[D], *args: Any, **kwargs: Any) → Population[D]

Select from a population to a population.

The default implementation calls select() on from_population and collects the results.

All subclasses should override either this method or select(). Consider overriding this method if selection requires information about the whole population. Example: fitness proportionate selection.

Parameters:

from_population – population to select from.

Warning

The default implementation calls select() as long as the number of selected individuals is less than budget.

As such, if select() can return multiple individuals, then the last call may return more individuals than what the budget permits.

select(from_pool: Sequence[D], *args: Any, **kwargs: Any) → tuple[D, ...]

Select individuals from a sequence of individuals.

All subclasses should override either this method or select_population().

Parameters:

from_pool – tuple of individuals to select from.

Note

Each item in the returned tuple must be in from_pool.

The selector should treat higher fitness as “better”.

Evaluator should assign higher fitness to

“better” individuals.

Raises:

NotImplementedError – If the subclass does not override this method.

evokit.core.variator module

class evokit.core.variator.Variator

Bases: ABC, Generic[D]

Base class for all selectors.

Derive this class to create custom selectors.

Tutorial: Getting Started with OneMax.

static __new__(cls: Type[Self], *args: Any, **kwargs: Any) → Self

Machinery.

__init__(*args: Any, processes: int | ProcessPoolExecutor | None = None, share_self: bool = False, **kwargs: Any) → None

See Variator for parameters processes and share_self.

arity: int | None

Size of input to vary()

processes

If attributes of this object will be shared when multiprocessing. See __init__().

abstract vary(parents: Sequence[D], *args: Any, **kwargs: Any) → tuple[D, ...]

Apply the variator to a tuple of parents

Produce a tuple of individuals from a sequence of individuals.

The length of .parents is at most arity.

vary_population(population: Population[D], *args: Any, **kwargs: Any) → Population[D]

Vary the population.

The default implementation separates population into groups of size .arity, call .vary with each group as argument, then collect and returns the result.

Parameters:

population – Population to vary.

Note

The default implementation calls Individual.reset_fitness() on each offspring to clear its fitness. Any implementation that overrides this method should do the same.

class evokit.core.variator.NullVariator

Bases: Variator[D]

Variator that does not change anything

__init__() → None

vary(parents: Sequence[D]) → tuple[D, ...]

Module contents

Export modules from core.