Revolver is a framework for building fast genetic algorithms in Swift 3.0.

Features

• Chromosomes: strings, trees
• Genetic operators: reproduction, mutation, crossover (1-point, 2-point, tree crossover)
• Selections: roulette, rank, tournament, random, best/worst
• Terminations: fixed number of generations, fitness threshold, date scheduling
• Evaluators: sequential, parallel, aggregate
• Random generators: Mersenne Twister, arc4random, drand48
• Everything listed above is ready-to-run, yet easily extensible. By subclassing base classes and conforming to protocols, you can customize almost anything.
• Well-documented API and many usage examples.
• Unit tests.

Compatibility

Revolver was built with the open-source implementation of Swift in mind. For that reason, a great deal of effort was put into making it compile on Linux.

Revolver is dependent on:

• Swift 3.0 standard library
• Foundation
• libdispatch
• SwiftyJSON

Revolver can run on:

• macOS
• iOS
• Linux (any distro capable of supporting the Swift runtime)

Revolver can be compiled on:

• macOS
• Linux (any distro capable of supporting the Swift runtime)

If you for some reason need Swift 2 compatibility, check out the swift-2.2 branch. Fair warning though, the branch has been frozen and remains unmaintained.

Documentation

Revolver is primarily documented with inline comments and Swift docstrings. If you prefer external documentation, check out the beautiful HTML documentation generated by jazzy. You may also be interested in reviewing a my thesis, which is sort of a guide to using Revolver in practice.

Bundled Examples

Apart from conventional documentation, Revolver comes with various usage examples.

Listed in the increasing order of difficulty:

1. MAX-ONE: In which Revolver is introduced and configured to create the longest string of 1's.
2. Parallel Evaluation: In which Revolver is shown to utilize multiple CPU cores to speed up fitness evaluation.
3. Knapsack Problem: In which Revolver is applied to solve an instance of a meaningful combinatorial problem.
4. Self-driving Car: In which a simple 2D simulation is set up to drive a robot car with the help of neural networks.
5. QWOP: In which Revolver produces human-competitive results, playing an online game.

Minimal Working Example

struct MyChromosome: RangeInitializedArray {
    typealias Element = Bool
    static let initializationRange = 26...42
    
    let array: [Element]    
    init(array: [Element]) { self.array = array }    
}

class MyEvaluator: SequentialEvaluator<MyChromosome> {
    typealias Chromosome = MyChromosome
    
    override func evaluateChromosome(individual: Chromosome) -> Fitness {
        // TODO: Fill in the fitness function here.
        // You can return any Double between 0 and 1.
        return 1.0 
    }    
}

let elitism = Reproduction<MyChromosome>(BestSelection(), numberOfIndividuals: 5)
let reproduction = Reproduction<MyChromosome>(RouletteSelection())
let mutation = Mutation<MyChromosome>(RankSelection())
let crossover = OnePointCrossover<MyChromosome>(TournamentSelection(order: 10))

let alg = GeneticAlgorithm<MyChromosome>(
    generator: ArcGenerator(),
    populationSize: 200,
    executeEveryGeneration: elitism,
    executeInLoop: (Choice(reproduction, p: 0.50) ||| Choice(mutation, p: 0.25) ||| Choice(crossover, p: 0.25)),
    evaluator: MyEvaluator(),
    termination: (MaxNumberOfGenerations(60) || FitnessThreshold(0.5))
)

alg.run()

Credits

This repository was created by Petr Mánek in 2016. Its contents are distributed under MIT License, unless specified otherwise.

BibTeX

If you use Revolver for your work, please reference it. For your convenience, here's the preferred BibTeX:

@mastersthesis{Manek2016,
  document_type     = {Bachelor's Thesis},
  timestamp         = {20160527},
  author            = {Petr Mánek},
  title             = {Genetic programming in Swift for human-competitive evolution},
  school            = {Charles University in Prague},
  year              = {2016},
  type              = {Bachelor Thesis},
  month             = {May},
  pdf               = {http://www.ms.mff.cuni.cz/~manekp/publications/20160527-bachelor-thesis.pdf}
}

Contributions

All contributions to the framework are welcome.

If you'd like to contribute, let me first say thank you, you are made of awesome! Secondly, you may want to check out the issue tracker for some bugs to fix and features to implement.

At the moment, there are no rules for contributing. However, before creating pull requests, please take some time to review previous pull requests.