Skip to content

Commit

Permalink
Describe the basic building blocks (traits) defined in this crate.
Browse files Browse the repository at this point in the history
  • Loading branch information
@haraldmaida
haraldmaida committed Nov 6, 2017
1 parent a0af2e3 commit 78cef13
Show file tree
Hide file tree
Showing 3 changed files with 149 additions and 14 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,9 @@ All user visible changes to this project will be documented in this file.
This project adheres to [Semantic Versioning](http://semver.org/), as described
for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md)

## 0.1.1 : 2017-11-06 : First words
* Describe the basic building blocks (traits) defined in this crate.<br/>
(documentation only, no code changes)

## 0.1.0 : 2017-10-26 : Newborn
First release
84 changes: 78 additions & 6 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,80 @@ types for modelling the domain of genetic algorithms.

[Documentation](https://docs.rs/genevo)

## Features

This crate provides a default implementation of the genetic algorithm to be used
to find solutions for a wide variety of search and optimization problems.

The implementation is split into building blocks which are all represented by
traits. This crate provides most common implementation for all building blocks.
So it can be used for many problems out of the box.

Anyway if one wants to use different implementations for one or the other
building block it can be extended by implementing any of the traits in a more
sophisticated and customized way.

The building blocks (or traits) are:
* Simulation
* Algorithm
* Termination
* Operator
* Population
* Phenotype and Genotype
* FitnessFunction

The simulation can run an algorithm that is executed in a loop. An algorithm
implements the steps to be done for each iteration of the loop. The provided
implementation of the genetic algorithm implements the `Algorithm` trait and
can therefore be executed by the `Simulator` which is the provided
implementation of the `Simulation` trait.

The `Simulator` holds state about the simulation and tracks statistics about
the execution of the algorithm, such as number of iterations and processing
time.

The simulation runs until the termination criteria are met. The termination
criteria can be a single one such as max number of iterations or a logical
combination of multiple termination criteria, e.g. max number of iterations
OR a minimum fitness value has been reached. Of coarse `Termination` is a
trait as well and one can implement any termination criteria he/she can think
of.

The algorithm can make use of operators that perform different stages of the
algorithm. E.g. the basic genetic algorithm defines the stages: selection,
crossover, mutation and accepting. These stages are performed by the appropriate
operators: `SelectionOp`, `CrossoverOp`, `MutationOp`, `RecombinationOp` and
`ReinsertionOp`.

This crate provides multiple implementations for each one of those operators.
So one can experiment with combining the different implementations to compose
the best algorithm for a specific search or optimization problem. Now you may
have guessed that the defined operators are traits as well and you are free
to implement any of these operators in a way that suits best for your problem
and plug them into the provided implementation of the genetic algorithm.

The genetic algorithm needs a population that it evolves with each iteration.
One population represents a possible candidate solution for an optimization
problem for which the best solution is search for. This crate provides a
`PopulationBuilder` to build population of genomes. To run the population
builder it needs an implementation of the `GenomeBuilder` trait. A
`GenomeBuilder` defines how to create one individual (or genome) within the
population.

Last but maybe most important are the traits `Phenotype`, `Genotype` and
`FitnessFunction`. These are the traits which define the domain of the
optimization problem. They must be implemented individually for each application
of the genetic algorithm.

Enough words about the building blocks. Show me some concrete examples. Have
a look at the examples in the examples folder to find out how to use this crate:

* [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
* [queens](./examples/queens/main.rs): searches for solutions of the
[N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)


## Usage

Add this to your `Cargo.toml`:
Expand All @@ -54,13 +128,11 @@ And add this to your crate:
extern crate genevo;
```

Have a look at the examples to see how to use this crate:
* [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
* [queens](./examples/queens/main.rs): searches for solutions of the
[N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)
## References

## Research
I started this project mainly to learn about genetic algorithms (GAs). During
this journey I searched a lot for information about GA. Here are the links to
sources of information about GA that I found most useful for me.

[[JFGA]]: Jeremy Fisher: Genetic Algorithms

Expand Down
75 changes: 67 additions & 8 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,76 @@
//! `genevo` is a library for implementing and executing simulations of
//! optimization and search problems using a genetic algorithm (GA).
//!
//! ## Installation
//! It provides a default implementation of the genetic algorithm to be used
//! to find solutions for a wide variety of search and optimization problems.
//!
//! You can use this library by adding the following lines to your `Cargo.toml`
//! file:
//! The implementation is split into building blocks which are all represented by
//! traits. This crate provides most common implementation for all building blocks.
//! So it can be used for many problems out of the box.
//!
//! ```ignore
//! [dependencies]
//! genevo = "0.1"
//! ```
//! Anyway if one wants to use a different implementation for one or the other
//! building block it can be extended by implementing any of the traits in a more
//! sophisticated and customized way.
//!
//! and adding `extern crate genevo;` to your crate root.
//! The building blocks (or traits) are:
//! * Simulation
//! * Algorithm
//! * Termination
//! * Operator
//! * Population
//! * Phenotype and Genotype
//! * FitnessFunction
//!
//! The simulation can run an algorithm that is executed in a loop. An algorithm
//! implements the steps to be done for each iteration of the loop. The provided
//! implementation of the genetic algorithm implements the `Algorithm` trait and
//! can therefore be executed by the `Simulator` which is the provided
//! implementation of the `Simulation` trait.
//!
//! The `Simulator` holds state about the simulation and tracks statistics about
//! the execution of the algorithm, such as number of iterations and processing
//! time.
//!
//! The simulation runs until the termination criteria are met. The termination
//! criteria can be a single one such as max number of iterations or a logical
//! combination of multiple termination criteria, e.g. max number of iterations
//! OR a minimum fitness value has been reached. Of coarse `Termination` is a
//! trait as well and one can implement any termination criteria he/she can think
//! of.
//!
//! The algorithm can make use of operators that perform different stages of the
//! algorithm. E.g. the basic genetic algorithm defines the stages: selection,
//! crossover, mutation and accepting. These stages are performed by the appropriate
//! operators: `SelectionOp`, `CrossoverOp`, `MutationOp`, `RecombinationOp` and
//! `ReinsertionOp`.
//!
//! This crate provides multiple implementations for each one of those operators.
//! So one can experiment with combining the different implementations to compose
//! the best algorithm for a specific search or optimization problem. Now you may
//! have guessed that the defined operators are traits as well and you are free
//! to implement any of these operators in a way that suits best for your problem
//! and plug them into the provided implementation of the genetic algorithm.
//!
//! The genetic algorithm needs a population that it evolves with each iteration.
//! One population represents a possible candidate solution for an optimization
//! problem for which the best solution is search for. This crate provides a
//! `PopulationBuilder` to build population of genomes. To run the population
//! builder it needs an implementation of the `GenomeBuilder` trait. A
//! `GenomeBuilder` defines how to create one individual (or genome) within the
//! population.
//!
//! Last but maybe most important are the traits `Phenotype`, `Genotype` and
//! `FitnessFunction`. These are the traits which define the domain of the
//! optimization problem. They must be implemented individually for each application
//! of the genetic algorithm.
//!
//! Enough words about the building blocks. Show me some concrete examples. Have
//! a look at the examples in the examples folder to find out how to use this crate:
//!
//! * [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
//! as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
//! * [queens](./examples/queens/main.rs): searches for solutions of the
//! [N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)
#![warn(
missing_copy_implementations,
Expand Down

0 comments on commit 78cef13

Please sign in to comment.