GothMommy

A small genetic algorithm library in TypeScript. Two classes: GothMommy for searching good hyperparameters (numbers, integers, booleans, categories) and GothMommyPermutation for ordering problems (TSP, scheduling). You provide a starting point, or a size, plus a scoring function: the population evolves until it finds something better.

Zero dependencies. Works with Bun, or with Node (ESM).

Quick start

import { GothMommy, type HyperParams } from "goth-mommy";

// Find x such that x^2 + 2x + 1 = 0 (double root at x = -1)
const fx = (x: number) => x * x + 2 * x + 1;

// Higher is better: equals 1 when fx(x) = 0, tends to 0 otherwise
const score = (population: HyperParams[]) =>
	population.map((ind) => 1 / (1 + Math.abs(fx(ind.x as number))));

const ga = new GothMommy({ x: 5 }, 20, score);

for (const state of ga.iterator(2000, 1 / (1 + 1e-8))) {
	console.log(state.iteration, state.bestScore, state.best);
}

Repo examples live in examples/: bun run example runs the first one, bun run examples runs all of them.

File	What it shows
basic.ts	The quick start above
mixed-space.ts	Real, integer, category and boolean in one individual, with a learning rate searched on a log scale
knapsack.ts	Knapsack: one boolean gene per item, compared against the exact brute-force solution
tsp.ts	Traveling salesman over 20 cities with GothMommyPermutation
custom-brick.ts	Writing a custom selector (truncation) and a custom mutator

Encodings: the space

Each hyperparameter has a domain that controls how it is initialized, mutated and crossed over. Declare them in the space option:

import { GothMommy, bool, choice, int, real } from "goth-mommy";

const seed = { lr: 0.01, layers: 4, activation: "relu", batchNorm: true };

const ga = new GothMommy(seed, 30, score, {
	space: {
		lr: real(1e-5, 1),                         // bounded real
		layers: int(1, 8),                         // integer
		activation: choice(["relu", "tanh", "gelu"]), // category
		batchNorm: bool(),                         // boolean
	},
});

Domain	Value	Initialization	Mutation
real(min?, max?)	number	uniform in [min, max] if bounded, else +/-amplitude around the seed	noise, then clamped to bounds
int(min, max)	integer	uniform integer	rounded noise, always at least +/-1
bool()	boolean	coin flip	flip with probability flipRate
choice([...])	one value from the list	uniform draw	another value from the list with probability flipRate

Without space, domains are inferred from the seed: a number is an unbounded real, a boolean is a bool(), and a string is a constant (never mutated). The seed must satisfy its domain, otherwise the constructor throws an error.

The bricks

GothMommy combines interchangeable bricks, each a plain function. Everything is exported from the package.

Brick	Option	Available (default in bold)
Selection	selector	proportional() (roulette, scores >= 0), tournament(size = 3) (accepts negative scores)
Crossover	crossover	none by default, uniform(), arithmetic()
Mutation	mutator	perturb({ strength, flipRate }) (multi-scale uniform noise), gaussian({ sigma, flipRate })
Initialization	initializer	spread(amplitude = 10)

import { GothMommy, arithmetic, gaussian, tournament } from "goth-mommy";

new GothMommy(seed, 20, score, {
	selector: tournament(3),
	crossover: arithmetic(),
	mutator: gaussian({ sigma: 0.5 }),
});

Without crossover, each child comes from a single parent (selection + mutation). With a crossover, the selector picks two parents per child.

Writing your own brick

These are the contracts from types.ts. A brick must never mutate its arguments.

type Selector    = (scores: number[], k: number) => number[];                        // k parent indices
type Mutator     = (individual: HyperParams, space: Space) => HyperParams;
type Crossover   = (a: HyperParams, b: HyperParams, space: Space) => HyperParams;
type Initializer = (seed: HyperParams, size: number, space: Space) => HyperParams[];

Ordering problems: GothMommyPermutation

When the solution is an order (city tour, task sequence), an individual is a permutation of the integers 0..size-1. You map them to your cities or tasks. Classic operators (segment crossover, swap mutation) would create duplicates: this class has its own, which always keep a valid permutation.

import { GothMommyPermutation, inversion, pmx } from "goth-mommy";

const cities = [[0, 0], [3, 1], [6, 0], [6, 4], [3, 5], [0, 4]] as const;

// closed tour length
const length = (tour: number[]) =>
	tour.reduce((sum, city, i) => {
		const [x1, y1] = cities[city]!;
		const [x2, y2] = cities[tour[(i + 1) % tour.length]!]!;
		return sum + Math.hypot(x2 - x1, y2 - y1);
	}, 0);

const score = (population: number[][]) =>
	population.map((tour) => 1 / (1 + length(tour)));

const ga = new GothMommyPermutation(cities.length, 50, score, {
	crossover: pmx(),
	mutator: inversion(),
});

let last;
for (const state of ga.iterator(200)) last = state;
console.log(last.best, length(last.best)); // [5, 0, 1, 2, 3, 4] 20.65

new GothMommyPermutation(size, populationSize?, scoringFunction?, options?) has the same iterator as GothMommy. Its options: mutationRate (0.5), crossoverRate (0.9, set 0 to disable), elitism (1), selector, and the two bricks below.

Brick	Option	Available (default in bold)
Crossover	crossover	ox() (keeps relative order), pmx() (keeps positions)
Mutation	mutator	swap() (swaps two genes), inversion() (reverses a segment, the TSP "2-opt")
Selection	selector	tournament(3), proportional()

A permutation crossover has contract (a: number[], b: number[]) => number[], a mutation (p: number[]) => number[].

API

new GothMommy(hyperparams?, populationSize?, scoringFunction?, options?)

Parameter	Default	Role
hyperparams	{}	Starting individual (the seed).
populationSize	10	Individuals per generation.
scoringFunction	zero scores	Receives the whole population, returns one score per individual (same order).
options	{}	See below.

Option	Default	Role
space	inferred from seed	Domain of each hyperparameter.
mutationRate	0.5	Probability that a child is mutated (0 to 1).
crossoverRate	0.7	Probability of crossing two parents (no effect without crossover).
elitism	1	Number of best individuals copied as-is.
selector, crossover, mutator, initializer	see bricks

iterator(maxIterations?, threshold?)

Generator yielding one state per generation. It stops when the best score reaches threshold or after maxIterations (defaults: 1000 and Infinity).

Each state holds population, scores, iteration, bestScore and best (the best individual).

Writing a good scoring function

This is the most important part:

• Higher is better. To minimize an error, transform it, e.g. 1 / (1 + error).
• Scores >= 0 with proportional(), since selection is proportional to score. With tournament(), negative scores are accepted.
• Pick a realistic threshold for threshold, tied to the wanted precision rather than an arbitrary value.
• The function is called once per generation, with the whole population.

How it works

Each generation:

1. Evaluation: the scoring function is called once.
2. Elitism: the elitism best individuals pass through as-is.
3. Selection: the selector picks the parents of the remaining slots.
4. Crossover (if configured): two parents produce one child, with probability crossoverRate.
5. Mutation: each child is mutated with probability mutationRate, respecting each gene domain.

The initial population holds the seed as-is, plus individuals drawn from the gene domains for the rest.

API reference

Each function, type and option is documented with TSDoc, and the HTML reference is generated with TypeDoc:

bun run docs      # generates docs/ (open docs/index.html)

Development

bun install
bun test          # tests
bun run check     # lint + format (Biome)
bun run typecheck

Limits

• Only top-level numbers, booleans and strings are supported: no nested objects.
• No binary or Gray encodings yet, no constrained permutation (time windows, etc.).
• choice values are compared with ===: no objects in the lists.
• A genetic algorithm does not guarantee the global optimum. If results stall, raise populationSize or mutationRate, or try tournament().

License

MIT