export class GaIsland<G> {
  options: FullOptions<G>
  constructor(options: RequiredOptions<G>)
  evolve(): void
}

export type RequiredOptions<G> = Options<G> &
  (
    | {
        population: G[]
      }
    | {
        randomIndividual: () => G
      }
  )

export type FullOptions<G> = Required<Options<G>>

export type Options<G> = {
  /**
   * The output should be updated in-place.
   * This design can reduce GC pressure with object pooling.
   *  */
  mutate: (input: G, output: G) => void
  /**
   * default 0.5
   * chance of doing mutation, otherwise will do crossover
   * */
  mutationRate?: number
  /**
   * The child should be updated in-place.
   * This design can reduce GC pressure with object pooling.
   *  */
  crossover: (aParent: G, bParent: G, child: G) => void
  /**
   * higher is better
   * */
  fitness: (gene: G) => number
  /**
   * default only compare the fitness
   * custom function should consider both distance and fitness
   * */
  doesABeatB?: (a: G, b: G) => boolean
  population?: G[]
  /**
   * default 100
   * should be even number
   * */
  populationSize?: number
  /**
   * default randomly pick a gene from the population than mutate
   * */
  randomIndividual?: () => G
  /**
   * return floating number from 0 to 1 inclusively
   * default Math.random()
   * */
  random?: () => number
}

/**
 * inplace populate the options.population gene pool
 * */
export function populate<G>(options: FullOptions<G>): void

/**
 * Apply default options and populate when needed
 * */
export function populateOptions<G>(_options: RequiredOptions<G>): FullOptions<G>

/**
 * generate a not-bad doesABeatB() function for kick-starter
 * should use custom implement according to the context
 * */
export function genDoesABeatB<G>(options: {
  /**
   * higher is better,
   * zero or negative is failed gene
   * */
  fitness: (gene: G) => number
  distance: (a: G, b: G) => number
  min_distance: number
  /**
   * return float value from 0 to 1 inclusively
   * as chance to change the Math.random() implementation
   * */
  random?: Random
}): (a: G, b: G) => boolean

export function best<G>(options: {
  population: G[]
  fitness: (gene: G) => number
}): {
  gene: G
  fitness: number
}

export function maxIndex(scores: number[]): number

/**
 * return float value from 0 to 1 inclusively
 * */
export type Random = () => number

/**
 * @param random  custom implementation of Math.random()
 * @param min     inclusive lower bound
 * @param max     inclusive upper bound
 * @param step    interval between each value
 * */
export function randomNumber(
  random: Random,
  min: number,
  max: number,
  step: number,
): number

export function randomElement<T>(random: Random, xs: T[]): T
/**
 * @param random        custom implementation of Math.random()
 * @param probability   change of getting true
 * */
export function randomBoolean(random: Random, probability?: number): boolean

/**
 * in-place shuffle the order of elements in the array
 * */
export function shuffleArray<T>(random: Random, xs: T[]): void

import { Worker } from 'worker_threads'

export type WeightedWorker = {
  weight: number
  worker: Worker
}

/**
 * only support request-response batch-by-batch
 * DO NOT support multiple interlaced concurrent batches
 * */
export class ThreadPool {
  totalWeights: number

  workers: WeightedWorker[]

  dispatch<T, R>(inputs: T[]): Promise<R[]>
  dispatch<T, R>(inputs: T[], cb: (err: any, outputs: R[]) => void): void

  constructor(
    options:
      | {
          modulePath: string
          /**
           * workload for each worker, default to 1.0 for all workers
           * */
          weights?: number[]
          /**
           * number of worker = (number of core / weights) * overload
           * default to 1.0
           * */
          overload?: number
        }
      | {
          workers: WeightedWorker[]
        },
  )

  close(): void
}

Experiment setup:

Fitness function: sha256 hash
Population Size: 20,000
Max Generation: 100 * [num of process/thread]

Testing machine:

Architecture:                    x86_64
CPU op-mode(s):                  32-bit, 64-bit
CPU(s):                          8
Thread(s) per core:              2
Core(s) per socket:              4
Model name:                      Intel(R) Xeon(R) CPU E3-1230 V2 @ 3.30GHz
CPU MHz:                         1615.729
CPU max MHz:                     3700.0000
CPU min MHz:                     1600.0000

Node Version:                    v14.17.0

source code: speed-test.ts

Single-core baseline: 2.378 gen/sec

*: Generation per second, higher better