evolvable 0.1.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 046213e8982bac4913f713e33942e9ef5ead7bd655871f995cbbe36797ce64f9
-  data.tar.gz: 2980cf144a9ed46e3abea9d0d395ee582a1207002fa2ab88bb2c967580f3bd6e
+  metadata.gz: 7f1a067e6b2b71bbbfb1ddd936a14401262a6ec59dce36305500fcabebcde47e
+  data.tar.gz: 943d7a9efe2f50a387efac9f3f48115beacc0a9550d6ec14f0765f4a17d4e2a4
 SHA512:
-  metadata.gz: 934eb04d489153638b00c002a2315e35140867f36ebfd9ecd8b3eb30fc0b6f249991a7b5f7b8f83a848bc3de9c36d9e060a89e16e7492bdf7d59f18d63aff405
-  data.tar.gz: ed1cac7f1c24265c29488d2e58304fc81b57be1a2891b87ab4b229218da63f3961cc1ea9dfda926df7226b083db0f2262cbb343ec667f3aa603831887b70e0bd
+  metadata.gz: 64db467632fdfedbc7671229a80e8bad20ac8c5495ec731ec1111991bdbf50616e12091886c142fc44eaac5de1a5c4073e1c5f1ff8e5a304bc6272632e85411f
+  data.tar.gz: 3d8fd1aee8c638e521e6d5535cb3f00a5ca85064dec909790827dffad21ec9d9a13658b99d1ec0078e61d113356c2b950caefa84ffd86737f42f4ed8d71ee2a9

data/.gitignore

@@ -9,5 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
-
 .byebug_history

data/.rubocop.yml

@@ -17,4 +17,4 @@ Naming/VariableNumber:
   EnforcedStyle: 'snake_case'
 
 Metrics/LineLength:
-  Max: 90
+  Max: 90

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Release 1.0.0
+
+Hello 🌎 🌍 🌏
+
+Check out the [README](https://github.com/mattruzicka/evolvable/blob/master/README.md) for everything
+
+___
+
+
+🧬 🧬 🧬
+
+Please [open an issue](https://github.com/mattruzicka/evolvable/issues/new) if you cannot find what you're looking for
+
+🧬 🧬 🧬

data/Gemfile.lock

@@ -1,34 +1,19 @@
 PATH
   remote: .
   specs:
-    evolvable (0.1.0)
+    evolvable (1.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.0)
-    byebug (11.0.0)
-    diff-lcs (1.3)
-    jaro_winkler (1.5.2)
-    parallel (1.13.0)
-    parser (2.6.0.0)
-      ast (~> 2.4.0)
+    ast (2.4.1)
+    byebug (11.1.3)
+    jaro_winkler (1.5.4)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
     powerpack (0.1.2)
     rainbow (3.0.0)
-    rake (10.5.0)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
     rubocop (0.64.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
@@ -37,7 +22,7 @@ GEM
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.4.0)
-    ruby-progressbar (1.10.0)
+    ruby-progressbar (1.10.1)
     unicode-display_width (1.4.1)
 
 PLATFORMS
@@ -47,9 +32,7 @@ DEPENDENCIES
   bundler (~> 2.0)
   byebug (~> 11.0)
   evolvable!
-  rake (~> 10.0)
-  rspec (~> 3.0)
   rubocop (~> 0.64.0)
 
 BUNDLED WITH
-   2.0.1
+   2.1.4

data/README.md

@@ -1,373 +1,286 @@
 # Evolvable
 
-Genetic algorithms mimic biological processes such as natural selection, crossover, and mutation to model evolutionary behaviors in code. This gem can add evolutionary behaviors to any Ruby object.
+A framework for building evolutionary behaviors in Ruby.
 
-## Demos
+[Evolutionary algorithms](https://en.wikipedia.org/wiki/Evolutionary_algorithm) build upon ideas such as natural selection, crossover, and mutation to construct relatively simple solutions to complex problems. This gem has been used to implement evolutionary behaviors for [visual, textual, and auditory experiences](https://projectpag.es/evolvable) as well as a variety of AI agents.
 
-- [Evolvable Sentence](https://github.com/mattruzicka/evolvable_sentence) - An interactive version of the evolvable sentence example in "Getting Started"
-- [Evolvable Equation](https://github.com/mattruzicka/evolvable_equation) - Evolves an equation of a specified length to evaluate to a given number
+With a straightforward and extensible API, Evolvable aims to make building simple as well as complex evolutionary algorithms fun and relatively easy.
 
-## Usage
+### The Evolvable Abstraction
+Population objects are composed of instances that include the `Evolvable` module. Instances are composed of gene objects that include the `Evolvable::Gene` module. Evaluation and evolution objects are used by population objects to evolve your instances. An evaluation object has one goal object and the evolution object is composed of selection, crossover, and mutation objects by default.
 
-- [Getting Started](#Getting-Started)
-- [The Gene Pool](#The-Gene-Pool)
-- [Fitness](#Fitness)
-- [Evolvable Population](#Evolvable-Population)
-- [Monitoring Progress](#Monitoring-Progress)
-- [Hooks](#Hooks)
-- [Mutation Objects](#Mutation-Objects)
-- [Crossover Objects](#Crossover-Objects)
-- [Helper Methods](#Helper-Methods)
-- [Configuration](#Configuration)
+All classes exposed by Evolvable are prefixed with `Evolvable::` and can be configured, inherited, removed, and extended. You can also choose between various Evolvable implementations documented below or substitute your own. Don't worry if none of this made sense, this will become clearer as you continue reading.
 
-### Getting Started
+## Installation
 
-To build an object with evolvable behavior, do the following:
+Add `gem 'evolvable'` to your application's Gemfile and run `bundle install` or install it yourself with `gem install evolvable`
 
-1. Add ```include Evolvable``` to your class
-2. Define ```.evolvable_gene_pool``` ([documentation](#The-Gene-Pool))
-3. Define ```#fitness``` ([documentation](#Fitness))
+## Getting Started
 
-As an example, let's make a text-to-speech command evolve from saying random nonsense to whatever you desire. We'll start by defining a Sentence class and doing the three steps above:
+After installing and requiring the "evolvable" Ruby gem:
 
-```Ruby
-require 'evolvable'
+1. Include the `Evolvable` module in the class for the instances you want to evolve. (See [Configuration](#Configuration)).
+2. Implement `.gene_space`, define any gene classes referenced by it, and include the `Evolvable::Gene` module for each. (See [Genes](#Genes)).
+3. Implement `#value`. (See [Evaluation](#Evaluation)).
+4. Initialize a population and start evolving. (See [Populations](#Populations)).
 
-class Sentence
-  include Evolvable
+Visit the [Evolvable Strings Tutorial](https://github.com/mattruzicka/evolvable/wiki/Evolvable-Strings-Tutorial) to see these steps in action. It walks through a simplified implementation of the [evolve string](https://github.com/mattruzicka/evolve_string) command-line program. Here's the [example source code](https://github.com/mattruzicka/evolvable/blob/master/examples/evolvable_string.rb) for the tutorial.
 
-  DICTIONARY = ('a'..'z').to_a << ' '
-  DESIRED_WORDS = 'colorless green ideas sleep furiously'
+If you’d like to quickly play around with an evolvable string Population object, you can do so by cloning this repo and running the command `bin/console` in this project's directory.
 
-  def self.evolvable_gene_pool
-    Array.new(DESIRED_WORDS.length) { |index| [index, DICTIONARY] }
+## Usage
+- [Configuration](#Configuration)
+- [Genes](#Genes)
+- [Evaluation](#Evaluation)
+- [Populations](#Populations)
+- [Evolution](#Evolution)
+- [Selection](#Selection)
+- [Crossover](#Crossover)
+- [Mutation](#Mutation)
+
+## Configuration
+
+You'll need to define a class for the instances you want to evolve and include the `Evolvable` module. Let's say you want to evolve a melody. You might do something like this:
+
+```ruby
+class Melody
+  include Evolvable
+
+  def self.gene_space
+    # Expected
   end
 
-  def fitness
-    score = 0
-    @genes.values.each_with_index do |value, index|
-      score += 1 if value == DESIRED_WORDS[index]
-    end
-    score
+  def value
+    # Required
   end
 end
 ```
 
-Now let's listen to our computer evolve its speech. The following code assumes your system has a text-to-speech command named "say" installed. Run this code in irb:
+The `Evolvable` module exposes the following class and instance methods for you.
 
-```ruby
-# To play with a more interactive version, check out https://github.com/mattruzicka/evolvable_sentence
+#### .gene_space
 
-population = Sentence.evolvable_population
-object = population.strongest_object
+You're expected to override this and return a gene space configuration hash or GeneSpace object.
 
-until object.fitness == Sentence::DESIRED_WORDS.length
-  words = object.genes.values.join
-  puts words
-  system("say #{words}")
-  population.evolve!(fitness_goal: Sentence::DESIRED_WORDS.length)
-  object = population.strongest_object
-end
+Here's a sample definition for the melody class defined above. It configures each instance to have 16 note genes and 1 instrument gene.
 
+```ruby
+def self.gene_space
+  { instrument: { type: 'InstrumentGene', count: 1 },
+    notes: { type: 'NoteGene', count: 16 } }
+end
 ```
 
-The ```Evolvable::Population#evolve!``` method evolves the population from one generation to the next. It accepts two optional keyword arguments:
+See the section on [Genes](#genes) for more details.
 
-```ruby
-{ generations_count: 1, fitness_goal: nil }
-```
+#### .new_population(keyword_args = {})
 
-Specifying the **fitness_goal** is useful when there's a known fitness you're trying to achieve. We use it in the evolvable sentence example above. If you want your population to keep evolving until it hits a particular fitness goal, set **generations_count** to a large number. The **generations_count** keyword argument tells ```#evolve!``` how many times to run.
+Initializes a new population. Example: `population = Melody.new_population(size: 100)`
 
-If you're interested in seeing exactly how ```Evolvable::Population#evolve!``` works, Open up the [Population](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/population.rb) class and check out the following methods:
+Accepts the same arguments as `Population.new`
 
-- ```evaluate_objects!```
-- ```select_objects!```
-- ```crossover_objects!```
-- ```mutate_objects!```
+#### .new_instance(population: nil, genes: [], population_index: nil)
 
-### The Gene Pool
+Initializes a new instance. Accepts a population object, an array of gene objects, and the instance's population index.
 
-Currently, the gene pool needs to be an array of arrays. Each inner array contains a gene name and an array of possible values for the gene. Expect future releases to make defining the gene pool more straightforward. Check out [Development](#Development) below for details. Until then, here's an example of a simple ```.evolvable_gene_pool``` definition for evolvable dueling pianos:
+This method is useful for re-initializing instances and populations that have been saved.
 
-```ruby
-class DualingPianos
-  NOTES = ['C', 'C♯', 'D', 'D♯', 'E', 'F', 'F♯', 'G', 'G♯', 'A', 'A♯', 'B']
+_It is not recommended that you override this method_ as it is used by Evolvable internals. If you need to customize how your instances are initialized you can override either of the following two "initialize_instance" methods.
 
-  def self.evolvable_gene_pool
-    [[:piano_1, NOTES],
-     [:piano_2, NOTES]]
-  end
-end
-```
+#### .initialize_instance
 
-The number of potential genes in the gene pool can be extremely large. For these cases, "Evolvable" makes it possible for objects to contain only a subset of genes with the ```.evolvable_genes_count``` method. Any gene defined in the ```.evolvable_gene_pool``` can still manifest during mutations. In this way, we can limit the gene size of particular objects without limiting the genes available to a population.
+The default implementation simply delegates to `.new` and is useful for instances with custom initialize methods.
 
-```ruby
-require 'evolvable'
+#### #initialize_instance
 
-class ComplexBot
-  include Evolvable
+Runs after Evolvable finishes building your instance. It's useful for stuff like implementing custom gene initialization logic. For example, the Evolvable Strings web demo (coming soon) uses it to read from a "length gene" and add or remove "char genes" accordingly.
 
-  def self.evolvable_gene_pool
-    potential_gene_values = (1..10_000).to_a
-    Array.new(1_000_000) { |n| [n, potential_gene_values] }
-  end
+#### #population, #population=
 
-  def self.evolvable_genes_count
-    5_000
-  end
-end
+The population object being used to evolve this instance.
 
-ComplexBot.evolvable_gene_pool.size # => 1_000_000
-population = ComplexBot.evolvable_population
-complex_bot = population.objects.first
-complex_bot.genes.count # => 10_000
-```
+#### #genes, #genes=
 
-### Fitness
+An array of all an instance's genes. You can find specific types of genes with the following two methods.
 
-The ```#fitness``` method is responsible for measuring how well an object performs. It returns a value or "score" which influences whether an object will be selected to "breed" the next generation of objects. How fitness is defined depends on what you're trying to achieve. If you're trying to break a high score record in Tetris, for example, then the fitness function for your tetris bot might simply return its tetris score:
+#### #find_genes(key)
 
-```ruby
-class TetrisBot
-  alias fitness tetris_score
-end
-```
+Returns an array of genes that have the given key. Gene keys are defined in the [.gene_space](####.gene_space) method. In the Melody example above, the key for the note genes would be `:notes`. The following would return an array of them: `note_genes = melody.find_genes(:notes)`
 
-If, however, your aim is to construct a bot that plays Tetris in an aesthetically pleasing way, maybe you'd define fitness by surveying your artist friends.
+#### #find_gene(key)
 
-```ruby
-class TetrisArtBot
-  def fitness
-    artist_friend_ratings.sum / artist_friend_ratings.count
-  end
-end
-```
+Returns the first gene with the given key. In the Melody example above, the instrument gene has the key `:instrument` so we might write something like: `instrument_gene = melody.find_gene(instrument)`
 
-The result of ```#fitness``` can be any object that includes the ([Comparable](https://ruby-doc.org/core-2.6.1/Comparable.html)) mixin from Ruby and implements the ```<=>``` method. Many Ruby classes such as String and Integer have default implementations.
+#### #population_index, #population_index=
 
-You may want to evaluate a whole generation of objects at once. For example, maybe you want each of your bots to play a game against each other and base your fitness score off their win records. For this case, use ```.evolvable_evaluate!(objects)``` like so: 
+Returns an instance's population index - an integer representing the order in which it was initialized in a population. It's the most basic way to distinguish instances in a population.
 
-```ruby
-class GamerBot
-  def self.evolvable_evaluate!(objects)
-    objects.combination(2).each do |player_1, player_2|
-      winner = Game.play(player_1, player_2)
-      winner.win_count += 1
-    end
-  end
+#### #value
 
-  alias fitness win_count
-end
-```
+It is required that you implement this method. It is used when evaluating instances before undergoing evolution.
 
-### Evolvable Population
+Technically, this method can return any object that implements Ruby's [Comparable](https://ruby-doc.org/core-2.7.1/Comparable.html). See the section on [Evaluation](#Evaluation) for details.
 
-The Evolvable::Population class can be initialized in two ways
+#### Evolvable Hooks
 
-1. ```EvolvableBot.evolvable_population```
-2. ```Evolvable::Population.new(evolvable_class: EvolvableBot)```
+The following class methods can be overridden in order to hook into a population's evolutions. The hooks run for each evolution in the following order:
 
+**.before_evaluation(population)**
 
-Both ways accept the following keyword arguments as defined by ```Evolvable::Population#initialize```
-```ruby
-{ evolvable_class:, # Required. Inferred if you use the .evolvable_population method
-  size: 20, # The number of objects in each generation
-  selection_count: 2, # The number of objects to be selected as parents for crossover
-  crossover: Crossover.new, # Any object that implements #call
-  mutation: Mutation.new, # Any object that implements #call!
-  generation_count: 0, # Useful when you want to re-initialize a previously saved population of objects
-  objects: [], # Ditto
-  log_progress: false } # See the "Monitoring Progress" section for details
-```
+**.before_evolution(population)**
 
-```.evolvable_population(args = {})``` merges any given args with with any keyword arguments defined in ```.evolvable_population_attrs``` Example:
+**.after_evolution(population)**
 
-```ruby
-class Plant
-  include Evolvable
+To use our Melody example from above, you could override the `.before_evolution` method to play the best melody from each generation with something like this:
 
-  def self.evolvable_population_attrs
-  { size: 100,
-    selection_count: 5,
-    mutation: Evolvable::Mutation.new(rate: 0.3),
-    log_progress: false }
+```ruby
+class Melody
+  def self.before_evolution(population)
+    best_melody = population.best_instance
+    best_melody.play
   end
 
-  def self.evolvable_gene_pool
-    [[:leaf_count, (1..100).to_a],
-     [:root_type, ['fibrous', 'taproot']]]
+  def play
+    note_genes = melody.find_genes(:notes)
+    note_values = note_genes.map(&:value)
+    find_gene(:instrument).play(note_values)
   end
 end
-
-population = Plant.evolvable_population(log_progress: true)
-population.size # => 100
-population.selection_count # => 5
-population.mutation.rate # => 0.3
-population.log_progress # => true
 ```
 
-The ```.evolvable_initialize(genes, population, object_index)``` is used by Evolvable::Population to initialize new objects. You can override it to control how your objects are initialized. Make sure to assign the passed in **genes** to your initialized objects. Here's an example implementation for when you want your imaginary friends to have names:
+## Genes
+
+Instances rely on gene objects to compose behaviors. In other words, a gene can be thought of as an object that in some way affects the behavior of an instance. They are used to encapsulate a "sample space" and return a sample outcome when accessed.
+
+#### The Evolvable::Gene module
+
+Gene objects must include the `Evolvable::Gene` module which enables them to undergo evolutionary operations such as crossover and mutation.
+
+To continue with the melody example, we might encode a NoteGene like so:
 
 ```ruby
-class ImaginaryFriend
-  def self.evolvable_initialize(genes, population, object_index)
-    friend = new(name: BABY_NAMES.sample)
-    friend.genes = genes
-    friend.population = population
-    friend
+class NoteGene
+  include Evolvable::Gene
+
+  NOTES = ['C', 'C♯', 'D', 'D♯', 'E', 'F', 'F♯', 'G', 'G♯', 'A', 'A♯', 'B']
+
+  def value
+    @value ||= NOTES.sample
   end
 end
 ```
+Here, the "sample space" for the NoteGene class has twelve notes, but each individual object will have only one note. The note is randomly chosen when the "value" method is invoked for the first time.
 
-The third argument to ```.evolvable_initialize``` is the index of the object in the population before being evaluated. It is useful when you what to give your objects more utilitarian names:
-
-```ruby
-friend.name == "#{name} #{population.generation_count}.#{object_index}" # => "ImaginaryFriend 0.11"
-```
+_It is important that the data for a particular gene never change._ Ruby's or-equals operator `||=` is super useful for memoizing gene attributes like this. It is used above to randomly pick a note only once and return the same note for the lifetime of the object.
 
-A time when you'd want to use Evolvable::Population initializer instead of ```EvolvableBot.evolvable_population``` is when you're re-initializing a population. For example, maybe you want to continue evolving a population of chat bots that you had previously saved to a database:
+A melody instance with multiple note genes might use the `NoteGene#value` method to compose the notes of its melody like so: `melody.find_genes(:note).map(&:value)`. Let's keep going with this example and implement the `InstrumentGene` too:
 
 ```ruby
-population = load_chat_bot_population
-Evolvable::Population.new(evolvable_class: population.evolvable_class,
-                          size: population.size,
-                          selection_count: population.selection_count,
-                          crossover: population.crossover,
-                          mutation: population.mutation,
-                          generation_count: population.generation_count,
-                          objects: population.objects)
-```
-
-### Monitoring Progress
+class InstrumentGene
+  include Evolvable::Gene
 
-```#evolvable_progress``` is used by ```Evolvable::Population#evolve!``` to log the progress of the "strongest object" in each generation. That is, the object with the best fitness score. It runs just after objects are evaluated and the ```Evolvable::Population#strongest_object``` can be determined. ```Evolvable::Population#log_progress``` must equal true in order for the result of the ```#evolvable_progress``` to be logged.
+  def instrument_class
+    @instrument_class ||= [Guitar, Synth, Trumpet].sample
+  end
 
-In the [evolvable sentence demo](https://github.com/mattruzicka/evolvable_sentence), ```evolvable_progress``` is implemented in order to output the strongest object's generation count, fitness score, and words. In this example, we also use the "say" text-to-speech command to pronounce the words. 
+  def volume
+    @volume ||= rand(1..100)
+  end
 
-```Ruby
-  class Sentence
-    def evolvable_progress
-      words = @genes.values.join
-      puts "Generation: #{population.generation_count} | Fitness: #{fitness} | #{words}"
-      system("say #{words}") if say?
-    end
+  def play(notes)
+    instrument_class.play(notes: notes, volume: volume)
   end
-  population.log_progress = true
+end
 ```
 
-Hooks can also be used to monitor progress.
+You can model your sample space however you like. Ruby's [Array](https://ruby-doc.org/core-2.7.1/Array.html), [Hash](https://ruby-doc.org/core-2.7.1/Hash.html), [Range](https://ruby-doc.org/core-2.7.1/Range.html), and [Random](https://ruby-doc.org/core-2.7.1/Random.html) classes may be useful. This InstrumentGene implementation has 300 possible outcomes (3 instruments * 100 volumes) and uses Ruby's Array, Range, and Random classes.
 
-### Hooks
+Now that its genes are implemented, a melody instance can use them:
 
-You can define any the following class method hooks on any Evolvable class. They run during the evolution of each generation in ```Evolvable::Population#evolve!```
+```ruby
+class Melody
+  include Evolvable
 
-```.evolvable_before_evolution(population)```
+  # ...
 
-```.evolvable_after_select(population)```
+  def play
+    note_genes = melody.find_genes(:notes)
+    note_values = note_genes.map(&:value)
+    find_gene(:instrument).play(note_values)
+  end
+end
+```
 
-```.evolvable_after_evolution(population)```
+In this way, instances can express behaviors via genes and even orchestrate interactions between them. Genes can also interact with each other during an instance's initialization process via the [#initialize_instance](#initialize_instance-1) method
 
-### Mutation Objects
+#### The Evolvable::GeneSpace object
 
-The [Evolvable::Mutation](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/mutation.rb) class defines the default mutation implementation with a default mutation rate of 0.03. It can be initialized with a custom mutation rate like so:
+TODO
 
-```ruby
-mutation = Evolvable::Mutation.new(rate: 0.05)
-population = Evolvable::Population.new(mutation: mutation)
-population.evolve!
-```
+## Evaluation
 
-Any Ruby object that implements ```#call!(objects)``` can be used as a mutation object. The default implementation is specialized to work with evolvable objects that define a ```evolvable_genes_count``` that is less than ```evolvable_gene_pool.size```. For more information on this, see [The Gene Pool](#The-Gene-Pool)
+TODO
 
-### Crossover Objects
+#### The Evolvable::Evaluation object
 
-The [Evolvable::Crossover](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/crossover.rb) class defines the default crossover implementation.
+TODO
 
-```ruby
-crossover = Evolvable::Crossover.new
-population = Evolvable::Population.new(crossover: crossover)
-population.evolve!
-```
+#### The Evolvable::Goal::Maximize object
 
-Any Ruby object that implements ```#call(parent_genes, offspring_count)``` can be used as a crossover object. The default implementation is specialized to work with evolvable objects that define a ```evolvable_genes_count``` that is less than ```evolvable_gene_pool.size```. For more information on this, see [The Gene Pool](#The-Gene-Pool)
+TODO
 
-### Helper Methods
+#### The Evolvable::Goal::Minimize object
 
-```Evolvable.combine_dimensions(dimensions)```
+TODO
 
-This is helpful when you want to create, for lack of a better word, "multidimensional genes". In the following example, we want our fortune cookie to evolve fortunes based on its eater's hair and eye color because fortune cookies understand things that we aren't capable of knowing.
+#### The Evolvable::Goal::Equalize object
 
-```ruby
-class FortuneCookie
-  include Evolvable
+TODO
 
-  HAIR_COLORS = ['black', 'blond', 'brown', 'gray', 'red', 'white']
-  EYE_COLORS = ['blue', 'brown', 'gray', 'green']
- 
-  FORTUNES = ['You will prosper',
-              'You will endure hardship',
-              'You are about to eat a crisp and sugary cookie']
+## Populations
 
-  def self.evolvable_gene_pool
-    gene_names_array = Evolvable.combine_dimensions([HAIR_COLORS, EYE_COLORS])
-    gene_names_array.map! { |gene_name| [gene_name, FORTUNES] }
-  end
+TODO
 
-  def fitness
-    hair_color = find_eater_hair_color
-    eye_color = find_eater_eye_color
-    fortune = @genes[[hair_color, eye_color]]
-    eater.give_fortune(fortune)
-    sleep 2.weeks
-    eater.how_true?(fortune)
-  end
-end
-```
+#### The Evolvable::Population object
 
-In this not-at-all-contrived example, ```Evolvable.combine_dimensions([HAIR_COLOR, EYE_COLORS])``` returns
+TODO
 
-```ruby
-[["auburn", "blue"], ["auburn", "brown"], ["auburn", "gray"], ["auburn", "green"], ["black", "blue"], ["black", "brown"], ["black", "gray"], ["black", "green"], ["blond", "blue"], ["blond", "brown"], ["blond", "gray"], ["blond", "green"], ["brown", "blue"], ["brown", "brown"], ["brown", "gray"], ["brown", "green"], ["gray", "blue"], ["gray", "brown"], ["gray", "gray"], ["gray", "green"], ["red", "blue"], ["red", "brown"], ["red", "gray"], ["red", "green"], ["white", "blue"], ["white", "brown"], ["white", "gray"], ["white", "green"]]
-```
+## Evolution
 
-which is useful for composing genes made up of various dimensions and accessing gene values by these dimensions in the ```#fitness``` and ```.evolvable_evaluate!(objects)``` methods.
+TODO
 
-```Evolvable.combine_dimensions(dimensions)``` can take an array containing any number of arrays as an argument. One item from each given array will be in each output array and the item's index will be the same as the index of the argument array it belongs to. All combinations of items from the various arrays that follow this rule will be returned as arrays. The number of output arrays is equal to the product of multiplying the sizes of each given array. This method was difficult to write as was this description. I'd be really interested to see other people's implementations :)
+#### The Evolvable::Evolution object
 
-### Configuration
+TODO
 
-TODO: Make logger configurable and make it smarter about picking a default
+## Selection
 
-## Installation
+TODO
 
-Add this line to your application's Gemfile:
+#### The Evolvable::Selection object
 
-```ruby
-gem 'evolvable'
-```
+TODO
 
-And then execute:
+## Crossover
 
-    $ bundle
+TODO
 
-Or install it yourself as:
+#### The Evolvable::GeneCrossover object
 
-    $ gem install evolvable
+TODO
 
-## Development
+#### The Evolvable::UniformCrossover object
 
-After checking out the repo, run `bundle install` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+TODO
 
-I am looking to both simplify how genes are defined as well as support more complex gene types by way of a new Gene class. Currently, genes are represented as an array of arrays or hashes depending on the context. This will likely change.
+#### The Evolvable::PointCrossover object
 
-I would also like to make more obvious how an evolvable object's genes can influence its behavior/fitness with well-defined pattern for gene expression, probably via an instance method on a gene called "express".
+TODO
 
-I have a general sense of how I want to move forward on these features, but feel free to message me with ideas or implementations.
+## Mutation
 
-If you see a TODO in this README, feel free to do it :)
+TODO
 
-## Contributing
+#### The Evolvable::Mutation object
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/evolvable.
+TODO