Petri

A genetic algorithm library for Elixir.

What's a genetic algorithm?

A genetic algorithm is a form of evolutionary optimization for problems with too many combinations to brute force. For example: the shortest route through 52 cities, the best hyperparameters for a model, or the most useful features in a dataset. A dataset of 50 features has a quadrillion combinations. At a million checks per second you're waiting 36 years. A GA gets a good answer before you've dropped programming and taken up farming.

A GA works like natural selection. Generate a population of candidate solutions, score them with a fitness function you write, pick the best, cross them to create new candidates, mutate a few to explore. Repeat for a few hundred generations. The result is rarely the mathematical optimum, but it gets there while brute force is just getting started.

Petri handles the selection, crossover, mutation, and generational loop. You pick a chromosome encoding that fits your problem, write a fitness function, and run it.

Quick start

Below is the traveling salesman problem on Berlin52: 52 cities, find the shortest tour that visits each once.

alias Petri.Chromosome.Permutation

# Fitness: shorter tours score higher (a GA maximizes, so invert distance)
fitness = fn %Permutation{genes: tour} ->
  1.0 / tour_distance(tour)
end

result =
  Petri.run(fitness, [
    encoding: :permutation,
    n: 52,
    population_size: 400,
    max_generations: 1000,
    seed: 67,
    selection: :tournament,
    tournament_size: 5,
    elite_count: 8,
    crossover: :ox,
    mutation: :inversion
  ])

{best_tour, _best_fitness} = result.best

See examples/tsp.exs for the full runnable script with city coordinates and distance calculation.

Capabilities

Four chromosome encodings, each with operators tuned for that representation.

Encoding	Shape
`:real`	`[0.001, 0.5, 120.0]`
`:integer`	`[3, 17, 255]`
`:permutation`	`[4, 0, 7, 2, 5, 1, 3, 6]`
`:binary`	`[1, 0, 1, 1, 0]`

Config validation catches operator/encoding mismatches up front so you won't get surprises mid-run.

Engine features:

Parallel evaluation with per-task timeout
Constraint handling: soft penalty functions or death-penalty retries on invalid offspring
Adaptive crossover/mutation rates with built-in decay strategies
Generational or steady-state replacement
Termination by generation count, fitness threshold, stagnation, time budget, or evaluation budget

Running the examples

Standalone scripts that pull in Petri via Mix.install. Run from the repo root with elixir (not mix):

elixir examples/tsp.exs
elixir examples/ml_hyperparams.exs
elixir examples/feature_selection.exs
elixir examples/ring_inscription.exs

Example	Encoding	What it does
`tsp.exs`	permutation	Find the shortest tour through the 52 cities of Berlin52
`ml_hyperparams.exs`	real	Tune learning rate, regularization, and epochs for a regression model
`feature_selection.exs`	binary	Pick the 4 predictive features out of 20 before training
`ring_inscription.exs`	integer	Evolve an arbitrary string toward a target quote character by character

Documentation

Full API docs at hexdocs.pm/petri.

License

LGPL-3.0-or-later. See LICENSE.