… _api-design:

API Design

API design principles

Modules

Short introduction to modules:

  • meta: Metaclasses

  • mixin: Mixin Classes

  • base: The base classes, esp. for creating GAs

  • population: populations to implement classical GAs

  • chromosome: some type of chromosomes

  • multipopulation: multi-population GAs

  • individual: individuals for GA or other EA

  • es,de,ep,gpa...: Evolutionary algorithms

  • pso: Swarm intelligent algorithms

  • misc/ba,fa..: Swarm intelligent algorithms, Bionic intelligent algorithm

  • deco: Decorators

  • utils: Helpers

  • errors: Exceptions

  • local_search/*: Local search algorithms

  • learn/*: Machine learning implemented by GAs

Metaclasses

The metaclass System is defined to simulate abstract algebraic systems, which are instantiated as a set containing a set of elements, as well as operators and functions on them.

MetaContainer is the super-metaclass of System for creating container classes.

  1. ParamType --> MetaContainer --> System

  2. ParamType --> MetaArray

MetaArray is a compact version of MetaContainer

Mixin Classes

Metaclasses define what the algorithm is, while mixin classes specify what the algorithm does.

The inheritance of metaclasses:

IterativeMixin  --->  CollectiveMixin
    |                      |
    |                      |
    v                      v
 FitnessMixin   --->  PopulationMixin

If you want to create novel algorithm different from GAs, it is recommended to inherit from the mixin classes. The base classes are designed for GA-like algorithms. It is not coercive. One can override the methods in the base classes.

Iterative models/algorithms

An iterative model is a mixin class implementing iterative algorithms, mainly repeating to call transition method.

Following is the core (pseudo-)code of the class.

class IterativeMixin:

    def evolve(self):
        self.init()
        looping by k:
            self.transition(k)

Users could override transition to implement own iteration algorithms.

Fitness models

Fitness Models (FitnessMixin) are iterative models with fitness. The iteration in such models would be influenced by fitness.

Indiviudal is a fitness model in GA.

Population models

Population Models (PopulationMixin) are collective algorithms with fitness.

Basic Classes

Individuals

An individual is defined as a container of chromosomes.

The individual classes are inherited from BaseIndividual. For instance, BinaryIndividual is a subclass encoded by several binary chromosomes.

See Examples section for a simple example of binary individuals — Knapsack Problem.

Chromosomes

The chromosomes as an array of genes, could be regarded as the unit of genetic operations. The subclass used most frequently isBinaryChromosome.

A chromosome is equivalent to an individual with only one chromosome, mathematically.

Populations

The population classes are inherited from BasePopulation. StandardPopulation is the standard population for GA. It is recommended to use HOFPopulation in most cases.

A population is a container of individuals, in original meaning. But It is possible to be a container of chromosomes in the view of algebra.

Multi-populations

It is useful for multi-populations GA. It is regarded as a container of populations.

Environment

It is designed to be the context for evolution of individuals. The aim of the class is not for numerical computing, instead for “the Skeuomorphic Design”.

Methods

About fitness

Calculating the fintess is the most frequent task in the algorithms.

  • _fitness(): the basic method to calculate the fitness of the individual. The methods whose names are started with _ always do the most dirty task.

  • fitness: decorated by property, get the fitness of the individual/population (from the cache first then call - _fitness if there is a cache). The fitness of a population is the maximal fitness of the individuals in the population.

  • best/mean/std_fitness: the maximum/mean/std of the fitnesses of the individuals in a population.

  • get_all_fitness: get the all fitnesses

About elements(individuals in a population or populations in a multi-population/community)

  • best_element: wrapped by property, equiv. to get_best_element

  • get_best_element: get the element with maximal fitness

  • get_best_elements: get some elements

  • sort/argsort: sort the elements by fitness

  • solution: decoding the best element

Basic operation

  • copy: copy an object

  • random: class method to generate an object randomly

  • decode: decode an individual to the real solution

Genetic operation

  • clone: chromosome-level

  • mutate: chromosome-level

  • cross: chromosome-level

  • select: population-level

  • mate: population-level, cross the elements, invalid in solution-level.

  • migrate: population-level, crossover of the populations

  • dual: chromosome-level

  • replicate: copy then mutate

  • local_search: population-level

Some operators defined in solution-level, i.e. only valid for individuals/populations (or chromosomes as the individuals), such as _fitness, some could be defined under solution-level, i.e. valid for chromosomes in an individual, such as dual, cross, mutate.

List-like operation

append, extend, pop, remove to operate the list of the elements

Side-effect and pure

Here side-effect means the method will change the fitness of the individual or the population. It could be ignored if you do not use the cache (to get the fitness).

Others

  • set_*/get_*: set/get methods, for instance, get_all the attributes of all individuals in a population.

  • set: set attributes/methods for a class

  • save/load: serialization/deserialization for populations/individuals

Arguments/Parameters/Attributions

  • n_*: number of …, such as n_chromosomes represents the number of the chromosomes in an individual.

  • *_prob: probability

  • *_rate: e.g. learning_rate

params/alias

params is a dictionary of parameters for the algorithm, it could be inherited from super class by meta-programming.

alias is a dictionary for alias to attributes.