evolvable 0.1.3 → 1.1.0

data/README.md

@@ -1,373 +1,359 @@
-# Evolvable
+# 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.
+[![Gem Version](https://badge.fury.io/rb/evolvable.svg)](https://badge.fury.io/rb/evolvable) [![Maintainability](https://api.codeclimate.com/v1/badges/7faf84a6d467718b33c0/maintainability)](https://codeclimate.com/github/mattruzicka/evolvable/maintainability)
 
-## Demos
+An evolutionary framework for writing programs that use operations such as selection, crossover, and mutation. Explore ideas generatively in any domain, discover novel solutions to complex problems, and build intuitions about intelligence, complexity, and the natural world.
 
-- [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
+Subscribe to the [Evolvable Newsletter](https://www.evolvable.site/newsletter) to slowly learn more, or keep reading this contextualization of the [full documentation](https://rubydoc.info/github/mattruzicka/evolvable).
 
-## Usage
 
-- [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)
+## Table of Contents
+* [Installation](#installation)
+* [Getting Started](#getting-started)
+* [Concepts](#concepts)
+* [Genes](#genes)
+* [Populations](#populations)
+* [Evaluation](#evaluation)
+* [Evolution](#evolution)
+* [Selection](#selection)
+* [Combination](#combination)
+* [Mutation](#mutation)
+* [Search Space](#search-space)
 
-### Getting Started
 
-To build an object with evolvable behavior, do the following:
+## Installation
 
-1. Add ```include Evolvable``` to your class
-2. Define ```.evolvable_gene_pool``` ([documentation](#The-Gene-Pool))
-3. Define ```#fitness``` ([documentation](#Fitness))
+Add [gem "evolvable"](https://rubygems.org/gems/evolvable) to your Gemfile and run `bundle install` or install it yourself with: `gem install evolvable`
 
-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:
+## Getting Started
 
-```Ruby
-require 'evolvable'
+The `Evolvable` module makes it possible to implement evolutionary behaviors for
+any class by defining a `.search_space` class method and `#value` instance method.
+Then to evolve instances, initialize a population with `.new_population` and invoke
+the `#evolve` method on the resulting population object.
 
-class Sentence
-  include Evolvable
+### Implementation Steps
 
-  DICTIONARY = ('a'..'z').to_a << ' '
-  DESIRED_WORDS = 'colorless green ideas sleep furiously'
+1. [Include the `Evolvable` module in the class you want to evolve.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable)
+2. [Define `.search_space` and any gene classes that you reference.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
+3. [Define `#value`.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
+4. [Initialize a population with `.new_population` and use `#evolve`.](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
 
-  def self.evolvable_gene_pool
-    Array.new(DESIRED_WORDS.length) { |index| [index, DICTIONARY] }
-  end
-
-  def fitness
-    score = 0
-    @genes.values.each_with_index do |value, index|
-      score += 1 if value == DESIRED_WORDS[index]
-    end
-    score
-  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:
+To demonstrate these steps, we'll look at the [Hello World](#) example program.
 
-```ruby
-# To play with a more interactive version, check out https://github.com/mattruzicka/evolvable_sentence
+### Hello World
 
-population = Sentence.evolvable_population
-object = population.strongest_object
+Let's build the evolvable hello world program using the above steps. It'll evolve a population of arbitrary strings to be more like a given target string. After installing this gem, run `evolvable hello` at the command line to see it in action.
 
-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
+Below is example output from evolving a population of randomly initialized string objects to match "Hello World!", then "Hello Evolvable World".
 
 ```
-
-The ```Evolvable::Population#evolve!``` method evolves the population from one generation to the next. It accepts two optional keyword arguments:
-
-```ruby
-{ generations_count: 1, fitness_goal: nil }
+❯ Enter a string to evolve: Hello World!
+
+pp`W^jXG'_N`%              Generation 0
+H-OQXZ\a~{H*               Generation 1 ...
+HRv9X WorlNi               Generation 50 ...
+HRl6W World#               Generation 100 ...
+Hello World!               Generation 165
+
+❯ Enter a string to evolve: Hello Evolvable World
+
+Helgo World!b+=1}3         Generation 165
+Helgo Worlv!}:c(SoV        Generation 166
+Helgo WorlvsC`X(Joqs       Generation 167
+Helgo WorlvsC`X(So1RE      Generation 168 ...
+Hello Evolv#"l{ Wor*5      Generation 300 ...
+Hello Evolvable World      Generation 388
 ```
 
-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.
+### Step 1
 
-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:
+Let's begin by defining a `HelloWorld` class and have it **include the `Evolvable` module**.
 
-- ```evaluate_objects!```
-- ```select_objects!```
-- ```crossover_objects!```
-- ```mutate_objects!```
+```ruby
+class HelloWorld
+  include Evolvable
+end
+```
 
-### The Gene Pool
+### Step 2
 
-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:
+Now we can **define the `.search_space`** class method with the types of [genes](#genes) that we want our our evolvable "hello world" instances to be able to have. We'll use `CharGene` instances to represent single characters within strings. So an instance with the string value of "Hello" would be composed of five `CharGene` instances.
 
 ```ruby
-class DualingPianos
-  NOTES = ['C', 'C♯', 'D', 'D♯', 'E', 'F', 'F♯', 'G', 'G♯', 'A', 'A♯', 'B']
+class HelloWorld
+  include Evolvable
 
-  def self.evolvable_gene_pool
-    [[:piano_1, NOTES],
-     [:piano_2, NOTES]]
+  def self.search_space
+    ["CharGene", 1..40]
   end
 end
 ```
 
-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 [Search Space](#search-space) can be defined in a variety of ways. The above is shorthand that's useful for when there's only one type of gene. This method can also return an array of arrays or hash.
 
-```ruby
-require 'evolvable'
+The `1..40` specifies the range of possible genes for a particular HelloWorld instance. Evolvable translates this range or integer value into a `Evolvable::CountGene` object.
 
-class ComplexBot
-  include Evolvable
+By specifying a range, an `Evolvable::CountGene` instance can change the number of genes that are present in an evovlable instance. Count genes undergo evolutionary operations like any other gene. Their effects can be seen in the letter changes from Generation 165 to 168 in the above example output.
+
+To finish step 2, we'll **define the gene class** that we referenced in the above `.search_space` method. Gene classes should include the `Evolvable::Gene` module.
 
-  def self.evolvable_gene_pool
-    potential_gene_values = (1..10_000).to_a
-    Array.new(1_000_000) { |n| [n, potential_gene_values] }
+```ruby
+class CharGene
+  include Evolvable::Gene
+
+  def self.chars
+    @chars ||= 32.upto(126).map(&:chr)
   end
 
-  def self.evolvable_genes_count
-    5_000
+  def to_s
+    @to_s ||= self.class.chars.sample
   end
 end
-
-ComplexBot.evolvable_gene_pool.size # => 1_000_000
-population = ComplexBot.evolvable_population
-complex_bot = population.objects.first
-complex_bot.genes.count # => 10_000
 ```
 
-### Fitness
+It's important that, once accessed, the data for a particular gene never change. When the `#to_s` method first runs, Ruby's `||=` operator memoizes the result of randomly picking a char, enabling this method to sample a char only once per gene.
 
-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:
+After defining the search space, we can now initialize `HelloWorld` instances with random genes, but to actually evolve them, we need to **define the `#value` instance method**. It provides the basis for comparing different evolvable instances.
 
-```ruby
-class TetrisBot
-  alias fitness tetris_score
-end
-```
+### Step 3
 
-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.
+In the next step, we'll set the goal value to 0, so that evolution favors evolvable HelloWorld instances with `#value` methods that return numbers closer to 0. That means we want instances that more closely match their targets to return scores nearer to 0. As an example, if our target is "hello world", an instance that returns "jello world" would have a value of 1 and "hello world" would have a value of 0.
 
-```ruby
-class TetrisArtBot
-  def fitness
-    artist_friend_ratings.sum / artist_friend_ratings.count
-  end
-end
-```
+For a working implementation, see the `#value` method in [examples/hello_world.rb](https://github.com/mattruzicka/evolvable/blob/main/examples/hello_world.rb)
 
-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.
+### Step 4
 
-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: 
+Now it's time to **initialize a population with `.new_population`**. By default, evolvable populations seek to maximize numeric values. In this program, we always know the best possible value, so setting the goal to a concrete number makes sense. This is done by passing the evaluation params with equalize set to 0.
 
-```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
+We'll also specify the number of instances in a population using the population's `size` parameter and change the mutation porbability from 0.03 (3%) to 0.6 (60%).
 
-  alias fitness win_count
-end
+Experimentation has suggested that a large mutation probability tends to decrease the time it takes to evolve matches with short strings and has the opposite effect for long strings. This is demonstrated in the example output above by how many generations it took to go from "Hello World!" to "Hello Evolvable World". As an optimization, we could dynamically change the mutation probability using a population hook detailed below, but doing so will be left as an exercise for the reader. [Pull requests are welcome.](#contributing)
+
+```ruby
+population = HelloWorld.new_population(size: 100,
+                                       evaluation: { equalize: 0 },
+                                       mutation: { probability: 0.6 }
 ```
 
-### Evolvable Population
 
-The Evolvable::Population class can be initialized in two ways
+At this point, everything should work when we run `population.evolve`, but it'll look like nothing is happening. The next section will allow us to gain instight by hooking into the evolutionary process.
 
-1. ```EvolvableBot.evolvable_population```
-2. ```Evolvable::Population.new(evolvable_class: EvolvableBot)```
+### Evolvable Population Hooks
 
+The following class methods can be implemented on your Evolvable class, e.g. HelloWorld, to hook into the Population#evolve lifecycle. This is useful for logging evolutionary progress, optimizing parameters, and creating interactions with and between evolvable instances.
 
-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
-```
+1. `.before_evaluation(population)` - Runs before evaluation.
+
+2. `.before_evolution(population)`- Runs after evaluation and before evolution.
+
+3. `.after_evolution(population)` - Runs after evolution.
 
-```.evolvable_population(args = {})``` merges any given args with with any keyword arguments defined in ```.evolvable_population_attrs``` Example:
+
+Let's define `.before_evolution` to print the best value for each generation. We'll also define `HelloWorld#to_s`, which implicitly delegates to `CharGene#to_s` during the string interpolation that happens.
 
 ```ruby
-class Plant
+class HelloWorld
   include Evolvable
 
-  def self.evolvable_population_attrs
-  { size: 100,
-    selection_count: 5,
-    mutation: Evolvable::Mutation.new(rate: 0.3),
-    log_progress: false }
+  def self.before_evolution(population)
+    best_evolvable = population.best_evolvable
+    evolutions_count = population.evolutions_count
+    puts "#{best_evolvable} - Generation #{evolutions_count}"
   end
 
-  def self.evolvable_gene_pool
-    [[:leaf_count, (1..100).to_a],
-     [:root_type, ['fibrous', 'taproot']]]
+  # ...
+
+  def to_s
+    @to_s ||= genes.join
   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
+  # ...
+end
 ```
 
-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:
+Finally we can **evolve the population with the `Evolvable::Population#evolve` instance method**.
 
 ```ruby
-class ImaginaryFriend
-  def self.evolvable_initialize(genes, population, object_index)
-    friend = new(name: BABY_NAMES.sample)
-    friend.genes = genes
-    friend.population = population
-    friend
-  end
-end
+population.evolve
 ```
 
-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:
+**You now know the fundamental steps to building evolvable programs of endless complexity in any domain!** 🐸 The exact implementation for the command line demo can be found in [exe/hello](https://github.com/mattruzicka/evolvable/blob/main/exe/hello) and [examples/hello_world.rb](https://github.com/mattruzicka/evolvable/blob/main/examples/hello_world.rb).
 
-```ruby
-friend.name == "#{name} #{population.generation_count}.#{object_index}" # => "ImaginaryFriend 0.11"
-```
+## Concepts
 
-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:
+[Populations](#populations) are composed of evolvables which are composed of genes. Evolvables orchestrate behaviors by delegating to gene objects. Collections of genes are organized into genomes and constitute the [search space](#search-space). [Evaluation](#evaluation) and [evolution](#evolution) objects are used to evolve populations. By default, evolution is composed of [selection](#selection), [combination](#combination), and [mutation](#mutation).
 
-```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)
-```
+The following concept map depicts how genes flow through populations.
 
-### Monitoring Progress
+![Concept Map](https://github.com/mattruzicka/evolvable/raw/main/examples/images/diagram.png)
 
-```#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.
+Evolvable is designed with extensibility in mind. Evolvable objects such as [evaluation](#evaluation), [evolution](#evolution), [selection](#selection), [combination](#combination), and [mutation](#mutation) can be extended and swapped, potentially in ways that alter the above graph.
 
-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. 
+## Genes
+For evolution to be effective, an evolvable's genes must be able to influence
+its behavior. Evolvables are composed of genes that can be used to run simple
+functions or orchestrate complex interactions. The level of abstraction is up
+to you.
 
-```Ruby
-  class Sentence
-    def evolvable_progress
-      words = @genes.values.join
-      puts "Generation: #{population.generation_count} | Fitness: #{fitness} | #{words}"
-      system("say #{words}") if say?
-    end
-  end
-  population.log_progress = true
-```
+Defining gene classes requires encapsulating some "sample space" and returning
+a sample outcome when a gene attribute is accessed. For evolution to proceed
+in a non-random way, the same sample outcome should be returned every time
+a particular gene is accessed with a particular set of parameters.
+Memoization is a useful technique for doing just this. The
+[memo_wise](https://github.com/panorama-ed/memo_wise) gem may be useful for
+more complex memoizations.
 
-Hooks can also be used to monitor progress.
 
-### Hooks
+```ruby
+# This gene generates a random hexidecimal color code for use by evolvables.
 
-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!```
+require 'securerandom'
 
-```.evolvable_before_evolution(population)```
+class ColorGene
+  include Evolvable::Gene
+
+  def hex_code
+    @hex_code ||= SecureRandom.hex(3)
+  end
+end
+```
 
-```.evolvable_after_select(population)```
 
-```.evolvable_after_evolution(population)```
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Gene)
 
-### Mutation Objects
+## Populations
+Population objects are responsible for generating and evolving instances.
+They orchestrate all the other Evolvable objects to do so.
+
+Populations can be initialized and re-initialized with a number of useful
+parameters.
 
-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:
 
 ```ruby
-mutation = Evolvable::Mutation.new(rate: 0.05)
-population = Evolvable::Population.new(mutation: mutation)
-population.evolve!
+# TODO: initialize a population with all supported parameters
 ```
 
-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)
 
-### Crossover Objects
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
+
+## Evaluation
+For selection to be effective in the context of evolution, there needs to be
+a way to compare evolvables. In the genetic algorithm, this is often
+referred to as the "fitness function".
+
+The `Evolvable::Evaluation` object expects evolvable instances to define a `#value` method that
+returns some numeric value. Values are used to evaluate instances relative to each
+other and with regards to some goal. Out of the box, the goal can be set
+to maximize, minimize, or equalize numeric values.
 
-The [Evolvable::Crossover](https://github.com/mattruzicka/evolvable/blob/master/lib/evolvable/crossover.rb) class defines the default crossover implementation.
 
 ```ruby
-crossover = Evolvable::Crossover.new
-population = Evolvable::Population.new(crossover: crossover)
-population.evolve!
-```
+# TODO: Show how to add/change population's evaluation 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)
+# The goal value can also be assigned via as argument to `Evolvable::Population#evolve`
+population.evolve(goal_value: 1000)
+```
 
-### Helper Methods
 
-```Evolvable.combine_dimensions(dimensions)```
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
 
-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.
+## Evolution
+After a population's instances are evaluated, they undergo evolution.
+The default evolution object is composed of selection,
+crossover, and mutation objects and applies them as operations to
+a population's evolvables in that order.
 
-```ruby
-class FortuneCookie
-  include Evolvable
 
-  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']
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evolution)
 
-  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
+## Selection
+The selection object assumes that a population's evolvables have already
+been sorted by the evaluation object. It selects "parent" evolvables to
+undergo combination and thereby produce the next generation of evolvables.
 
-  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
-```
+Only two evolvables are selected as parents for each generation by default.
+The selection size is configurable.
 
-In this not-at-all-contrived example, ```Evolvable.combine_dimensions([HAIR_COLOR, EYE_COLORS])``` returns
 
 ```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"]]
+# TODO: Show how to add/change population's selection object
 ```
 
-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.
 
-```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 :)
 
-### Configuration
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Selection)
 
-TODO: Make logger configurable and make it smarter about picking a default
+## Combination
+Combination generates new evolvable instances by combining the genes of selected instances.
+You can think of it as a mixing of parent genes from one generation to
+produce the next generation.
 
-## Installation
+You may choose from a selection of combination objects or implement your own.
+The default combination object is `Evolvable::GeneCombination`.
 
-Add this line to your application's Gemfile:
 
-```ruby
-gem 'evolvable'
-```
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Combination)
 
-And then execute:
+## Mutation
+Mutation serves the role of increasing genetic variation. When an evolvable
+undergoes a mutation, one or more of its genes are replaced by newly
+initialized ones. In effect, a gene mutation invokes a new random outcome
+from the genetic search space.
 
-    $ bundle
+Mutation frequency is configurable using the `probability` and `rate`
+parameters.
 
-Or install it yourself as:
 
-    $ gem install evolvable
+```ruby
+# Show how to initialize/assign population with a specific mutation object
+```
 
-## Development
 
-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.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Mutation)
 
-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.
+## Search Space
+The search space encapsulates the range of possible genes
+for a particular evolvable. You can think of it as the boundaries of
+genetic variation. It is configured via the
+[.search_space](#evolvableclasssearch_space) method that you define
+on your evolvable class. It's used by populations to initialize
+new evolvables.
 
-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".
+Evolvable provides flexibility in how you define your search space.
+The below example implementations for `.search_space` produce the
+exact same search space for the
+[Hello World](https://github.com/mattruzicka/evolvable#hello-world)
+demo program. The different styles arguably vary in suitability for
+different contexts, perhaps depending on how programs are loaded and
+the number of different gene types.
 
-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.
 
-If you see a TODO in this README, feel free to do it :)
+```ruby
+# All 9 of these example definitions are equivalent
+
+# Hash syntax
+{ chars: { type: 'CharGene', max_count: 100 } }
+{ chars: { type: 'CharGene', min_count: 1, max_count: 100 } }
+{ chars: { type: 'CharGene', count: 1..100 } }
+
+# Array of arrays syntax
+[[:chars, 'CharGene', 1..100]]
+[['chars', 'CharGene',  1..100]]
+[['CharGene', 1..100]]
+
+# A single array works when there's only one type of gene
+['CharGene', 1..100]
+[:chars, 'CharGene', 1..100]
+['chars', 'CharGene', 1..100]
+```
+
+
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/evolvable.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/evolvable.
+
+If you're interested in contributing, but don't know where to get started, message me on twitter at [@mattruzicka](https://twitter.com/mattruzicka).