Skip to content

Latest commit

 

History

History
272 lines (211 loc) · 13.4 KB

API.md

File metadata and controls

272 lines (211 loc) · 13.4 KB
Raw

API Reference

Types

To make this API reference more concise and readable, a few "types" have been introduced. Those "types" are just aliases for some plain JavaScript structures.

Type Translates to Description
Individual Any Represents a single individual/chromosome.
Population Array<Individual> Array of individuals makes a population.
EvaluatedPopulation Array<{ fitness: number, indvidual: Individual }> Array of objects containing an individual and its fitness.
Rng () => number Function, which returns random values between 0 and 1 (inclusive of 0, but not 1).

Available Properties/Functions

Genemo.run(options)

Runs a genetic algorithm. Returns a promise, which resolves to an object:

{
  evaluatedPopulation: EvaluatedPopulation,
  iteration: number,
  logs: object,
  getLowestFitnessIndividual: () => ({ fitness: number, indvidual: Individual }),
  getHighestFitnessIndividual: () => ({ fitness: number, indvidual: Individual })
}

Genemo.run takes a single argument - options. It is an object with the following properties:

  • generateInitialPopulation - Generates initial population of individuals (chromosomes).
    Type: (Rng) => Population
    Required: Yes
    Available values: Genemo.generateInitialPopulation()

  • selection - Selects individuals for breeding.
    Type: (EvaluatedPopulation, Rng) => EvaluatedPopulation
    Required: Yes
    Available values: Genemo.selection.tournament(), Genemo.selection.rank(), Genemo.selection.roulette()

  • reproduce - Creates new population from the selected individuals.
    Type: (EvaluatedPopulation, Rng, collectLog) => Population
    Required: Yes
    Available values: Genemo.reproduce()

  • evaluatePopulation - Maps an array of individuals to an array of fitness values.
    Type: (Population, Rng) => Array<number>
    Required: Yes
    Available values: Genemo.evaluatePopulation()

  • stopCondition - Returning true terminates the algorithm.
    Type: ({ evaluatedPopulation, iteration }, Rng) => boolean
    Required: Yes
    Available values: Genemo.stopCondition()

  • succession - Creates a new population based on previous (evaluated) population and current (also evaluated) children population (result of reproduce function).
    Type: ({ prevPopulation, childrenPopulation }, Rng) => EvaluatedPopulation
    Required: No
    Default: ({ childrenPopulation }) => childrenPopulation
    Available values: Genemo.elitism()

  • iterationCallback - Callback, which is called in every iteration.
    Type: ({ evaluatedPopulation, iteration, logs, getLowestFitnessIndividual, getHighestFitnessIndividual }) => undefined
    Required: No
    Default: () => {}
    Available values: Genemo.logIterationData()

  • random - Custom random number generator. Should return values between 0 and 1 (inclusive of 0, but not 1).
    Type: () => number
    Required: No
    Default: Math.random

  • maxBlockingTime - Time in milliseconds, after which the next iteration is called asynchronously (as a macrotask).
    Type: number
    Required: No
    Default: Infinity

  • collectLogs - Indicates if the logs about performance should be collected.
    Type: boolean
    Required: No
    Default: true

Genemo.generateInitialPopulation({ generateIndividual, size })

Returned function is applicable to: Genemo.run's generateInitialPopulation parameter.
Takes an object with the following properties:

  • generateIndividual - Function which takes a random number generator as an argument and returns a random individual.
    Type: (Rng) => Individual

  • size - Number of individuals in the population.
    Type: number

Genemo.evaluatePopulation({ fitnessFunction })

Returned function is applicable to: Genemo.run's evaluatePopulation parameter.
Due to performance reasons, this function doesn't support promises. fitnessFunction must be a synchronous.
evaluatePopulation takes an object with the following properties:

  • fitnessFunction - Function which takes an individual as a parameter and returns its fitness.
    Type: (Individual) => number

Genemo.reproduce({ crossover, mutate, mutationProbability })

Returned function is applicable to: Genemo.run's reproduce parameter.
Takes an object with the following properties:

  • crossover - Function which takes a pair of parents and a random number generator and returns a pair of children.
    Type: ([Individual, Individual], Rng) => [Individual, Individual]

  • mutate - Function which maps an individual to a new individual modified by mutation
    Type: (Individual, Rng) => Individual

  • mutationProbability - Mutation probability for a single individual.
    Type: number
    Default value: 0.01

Genemo.reproduceBatch({ crossoverAll, mutateAll, mutationProbability })

Returned function is applicable to: Genemo.run's reproduce parameter.
Takes an object with the following properties:

  • crossoverAll - Function which takes an array of pairs of parents and a random number generator and returns an array of pairs of children.
    Type: (Array<[Individual, Individual]>, Rng) => Array<[Individual, Individual]>

  • mutateAll - Function which maps an array of individuals to a new array of individuals modified by mutation. Only individuals selected for mutation will be passed to this function.
    Type: (Individual, Rng) => Individual

  • mutationProbability - Mutation probability for a single individual.
    Type: number
    Default value: 0.01

Genemo.stopCondition({ minFitness, maxFitness, maxIterations })

Returned function is applicable to: Genemo.run's stopCondition parameter.
Takes an object with the following properties:

  • minFitness - stop when one of the individuals has fitness higher or equal minFitness
    Type: number
    Optional

  • maxFitness - stop when one of the individuals has fitness lower or equal minFitness.
    Type: number
    Optional

  • maxIterations - stop after maxIterations iterations.
    Type: number
    Optional

Returns a function with a signature matching that of stopCondition property of Genemo.run options object. Use minFitness for maximization problems and maxFitness for minimization.

Genemo.logIterationData({ include, customLogger })

Returns a function which logs iteration data (mostly performance data). Returned function is applicable to: Genemo.run's iterationCallback parameter.
Takes an object with the following properties:

  • include - object indicating what should be logged
    Type: object
    Properties (all optional):

    • iteration
      • Signature: { show: boolean, formatter: (key, value) => string }
    • minFitness
      • Signature: { show: boolean, formatter: (key, value) => string }
    • maxFitness
      • Signature: { show: boolean, formatter: (key, value) => string }
    • avgFitness
      • Signature: { show: boolean, formatter: (key, value) => string }
    • logsKeys
      • Signature: Array<{ key: string, formatter: (key, value) => string }>
      • Available keys for Genemo.run: lastIteration, selection, reproduce, evaluatePopulation, succession, stopCondition, iterationCallback
      • Available keys for Genemo.reproduce: reproduce.crossover, reproduce.mutation

    Formatters are optional.

  • customLogger - logs provided string value
    Type: (string) => undefined
    Optional
    Default value: console.log

Genemo.selection.roulette({ minimizeFitness })

Returned function is applicable to: Genemo.run's selection parameter.
Takes an object with the following properties:

  • minimizeFitness - if true, selection's purpose will be to minimize fitness.
    Type: boolean

Genemo.selection.rank({ minimizeFitness })

Returned function is applicable to: Genemo.run's selection parameter.
Takes an object with the following properties:

  • minimizeFitness - if true, selection's purpose will be to minimize fitness.
    Type: boolean

Genemo.selection.tournament({ size, minimizeFitness })

Returned function is applicable to: Genemo.run's selection parameter.
Takes an object with the following properties:

  • size - tournament size
    Type: number

  • minimizeFitness - if true, selection's purpose will be to minimize fitness.
    Type: boolean

Genemo.randomSequenceOf(valuesSet, length)

Returns a function which takes a random number generator and returns an array of random elements from valuesSet of length equal to length.
Returned function is applicable to: Genemo.generateInitialPopulation's generateIndividual parameter.

Genemo.randomPermutationOf(valuesSet)

Returns a function which takes a random number generator and returns a random permutation of elements from valuesSet.
Returned function is applicable to: Genemo.generateInitialPopulation's generateIndividual parameter.

Genemo.elitism({ keepFactor, minimizeFitness })

Succession strategy, which keeps best individuals regerdless of reproduce's outcome. Returned function is applicable to: Genemo.run's succession parameter.
Takes an object with the following properties:

  • keepFactor - tournament size
    Type: number

  • minimizeFitness - if true, succession's purpose will be to minimize fitness.
    Type: boolean

Genemo.crossover.singlePoint()

Single-point crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.

Genemo.crossover.twoPoint()

Two-point crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.

Genemo.crossover.kPoint(k)

K-point crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.
Takes one argument:

  • k - number of crosover points.
    Type: number

Genemo.crossover.orderOne()

Order 1 crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.

Genemo.crossover.PMX()

Partially-mapped crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.

Genemo.crossover.uniform()

Uniform crossover. Offsprings are created by selecting each gene from one of the parents with equal probability.
Returned function is applicable to: Genemo.reproduce's crossover parameter.

Genemo.crossover.edgeRecombination({ hashGene })

Edge recombination crossover. It is an order-based crossover.
Returned function is applicable to: Genemo.reproduce's crossover parameter.
Takes an optional object with a single property:

  • hashGene - Function which returns an identificator of a given gene for comparison purposes. It is used to distinguish genes when using === comparison and structures like Map and Set. If you represent a gene by a value of a simple type (for example string or number), then the default value of hashGene will work just fine.
    Type: gene => geneHash
    Optional
    Default value: gene => gene

Genemo.mutation.transformRandomGene(transformFunc)

Transforms random gene from individual. Individual must be represented as an array of genes. Returned function is applicable to: Genemo.reproduce's mutate parameter.
Takes one argument:

  • transformFunc - function which transforms one gene.
    Type: (gene, Rng) => mutatedGene

Genemo.mutation.flipBit()

Negates value of a random gene (array element) of an individual.
Returned function is applicable to: Genemo.reproduce's transformRandomGene parameter.

Genemo.mutation.swapTwoGenes()

Swaps places of two randomly chosen genes (array elements) of an individual.
Returned function is applicable to: Genemo.reproduce's transformRandomGene parameter.