evolvable 1.0.2 → 1.1.0

data/README.md

@@ -1,422 +1,359 @@
-# Evolvable
+# Evolvable 🦎
+
 [![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)
 
-A framework for building evolutionary behaviors in Ruby.
+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.
+
+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).
 
-[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.
 
-With a straightforward and extensible API, Evolvable aims to make building simple as well as complex evolutionary algorithms fun and relatively easy.
+## 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)
 
-### 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. All classes exposed by Evolvable are prefixed with `Evolvable::` and can be configured, inherited, removed, and extended.
 
 ## Installation
 
-Add `gem 'evolvable'` to your application's Gemfile and run `bundle install` or install it yourself with `gem install evolvable`
+Add [gem "evolvable"](https://rubygems.org/gems/evolvable) to your Gemfile and run `bundle install` or install it yourself with: `gem install evolvable`
 
 ## Getting Started
 
-After installing and requiring the "evolvable" Ruby gem:
+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.
 
-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-1)).
-4. Initialize a population and start evolving. (See [Populations](#Populations)).
+### Implementation Steps
 
-Visit the [Evolving Strings](https://github.com/mattruzicka/evolvable/wiki/Evolving-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.
+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)
 
-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.
 
-## Usage
-- [Configuration](#Configuration)
-- [Genes](#Genes)
-- [Populations](#Populations)
-- [Evaluation](#evaluation-1)
-- [Evolution](#evolution-1)
-- [Selection](#selection-1)
-- [Crossover](#Crossover)
-- [Mutation](#mutation-1)
+To demonstrate these steps, we'll look at the [Hello World](#) example program.
 
-## Configuration
+### Hello World
 
-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:
+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.
 
-```ruby
-class Melody
-  include Evolvable
+Below is example output from evolving a population of randomly initialized string objects to match "Hello World!", then "Hello Evolvable World".
 
-  def self.gene_space
-    { instrument: { type: 'InstrumentGene', count: 1 },
-      notes: { type: 'NoteGene', count: 16 } }
-  end
-
-  def value
-    average_rating # ...
-  end
-end
+```
+❯ 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
 ```
 
-The `Evolvable` module expects the [".gene_space" class method](#evolvableclassgene_space) and requires the ["#value" instance method](#evolvableclassvalue) to be defined as documented below. Other methods exposed by `Evolvable` have also been documented below.
-
-### EvolvableClass.gene_space
-
-You're expected to override this and return a gene space configuration hash or GeneSpace object. It defines the mapping for a hyperdimensional "gene space" so to speak. The above sample definition for the melody class configures each instance to have 16 note genes and 1 instrument gene.
-
-See the section on [Genes](#genes) for more details.
-
-### EvolvableClass.new_population(keyword_args = {})
-
-Initializes a new population. Example: `population = Melody.new_population(size: 100)`
-
-Accepts the same arguments as [Population.new](#evolvablepopulationnew)
-
-### EvolvableClass.new_instance(population: nil, genes: [], population_index: nil)
-
-Initializes a new instance. Accepts a population object, an array of gene objects, and the instance's population index. This method is useful for re-initializing instances and populations that have been saved.
-
-_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.
-
-### EvolvableClass.initialize_instance
-
-The default implementation simply delegates to `.new` and is useful for instances with custom initialize methods.
-
-### EvolvableClass#initialize_instance
-
-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.
-
-### EvolvableClass#population, #population=
-
-The population object being used to evolve this instance.
-
-### EvolvableClass#genes, #genes=
-
-An array of all an instance's genes. You can find specific types of genes with the following two methods.
-
-### EvolvableClass#find_genes(key)
-
-Returns an array of genes that have the given key. Gene keys are defined in the [EvolvableClass.gene_space](#evolvableclassgene_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)`
-
-### EvolvableClass#find_gene(key)
-
-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)`
-
-### EvolvableClass#population_index, #population_index=
-
-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.
-
-### EvolvableClass#value
-
-You must implement this method. It is used when evaluating instances before undergoing evolution. The above melody example imagines that the melodies have ratings and uses them as the basis for evaluation and selection.
-
-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-1) for details.
-
-### Evolvable Hooks
-
-The following class method hooks can be overridden. The hooks run for each evolution in the following order:
+### Step 1
 
-**.before_evaluation(population)**
+Let's begin by defining a `HelloWorld` class and have it **include the `Evolvable` module**.
 
-**.before_evolution(population)**
+```ruby
+class HelloWorld
+  include Evolvable
+end
+```
 
-**.after_evolution(population)**
+### Step 2
 
-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:
+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 Melody
-  def self.before_evolution(population)
-    best_melody = population.best_instance
-    best_melody.play
-  end
+class HelloWorld
+  include Evolvable
 
-  def play
-    note_genes = melody.find_genes(:notes)
-    note_values = note_genes.map(&:value)
-    find_gene(:instrument).play(note_values)
+  def self.search_space
+    ["CharGene", 1..40]
   end
 end
 ```
 
-## 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 [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.
 
-### The Evolvable::Gene module
+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.
 
-Gene objects must include the `Evolvable::Gene` module which enables them to undergo evolutionary operations such as crossover and mutation.
+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 continue with the melody example, we might encode a NoteGene like so:
+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.
 
 ```ruby
-class NoteGene
+class CharGene
   include Evolvable::Gene
 
-  NOTES = ['C', 'C♯', 'D', 'D♯', 'E', 'F', 'F♯', 'G', 'G♯', 'A', 'A♯', 'B']
+  def self.chars
+    @chars ||= 32.upto(126).map(&:chr)
+  end
 
-  def value
-    @value ||= NOTES.sample
+  def to_s
+    @to_s ||= self.class.chars.sample
   end
 end
 ```
-Here, the "sample space" for the NoteGene class has twelve notes, but each object will have only one note which is randomly chosen when the "value" method is invoked for the first time. _It is important that the data for a particular gene never change._ Ruby's or-equals operator `||=` is super useful for memoizing gene attributes. It is used above to randomly pick a note only once and return the same note for the lifetime of the object.
 
-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 humming with the melody example and implement the `InstrumentGene` too:
+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.
 
-```ruby
-class InstrumentGene
-  include Evolvable::Gene
+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.
 
-  def instrument_class
-    @instrument_class ||= [Guitar, Synth, Trumpet].sample
-  end
+### Step 3
 
-  def volume
-    @volume ||= rand(1..100)
-  end
+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.
 
-  def play(notes)
-    instrument_class.play(notes: notes, volume: volume)
-  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)
 
-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.
+### Step 4
 
-Now that its genes are implemented, a melody instance can use them:
+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 Melody
-  include Evolvable
+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%).
 
-  # ...
+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)
 
-  def play
-    note_genes = melody.find_genes(:notes)
-    note_values = note_genes.map(&:value)
-    find_gene(:instrument).play(note_values)
-  end
-end
+```ruby
+population = HelloWorld.new_population(size: 100,
+                                       evaluation: { equalize: 0 },
+                                       mutation: { probability: 0.6 }
 ```
 
-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 [EvolvableClass#initialize_instance](#evolvableclassinitialize_instance-1) method
-
-### The Evolvable::GeneSpace object
-
-The `Evolvable::GeneSpace` object is responsible for initializing the full set of genes for a particular instance according to the configuration returned by the [EvolvableClass.gene_space](#evolvableclassgene_space) method. It is used by the `Evolvable::Population` to initialize new instances.
 
-Technically, any object that responds to a `new_genes` method which returns an array of genes for a particular instance can function as a GeneSpace object. Custom implementations will be used if returned by the `.gene_space` method.
+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.
 
+### Evolvable Population Hooks
 
-## Populations
-
-The `Evolvable::Population` object is responsible for generating and evolving instances. It orchestrates all the other Evolvable objects to do so.
+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.
 
-### Evolvable::Population.new
+1. `.before_evaluation(population)` - Runs before evaluation.
 
-Initializes an Evolvable::Population.
+2. `.before_evolution(population)`- Runs after evaluation and before evolution.
 
-Keyword arguments:
+3. `.after_evolution(population)` - Runs after evolution.
 
-#### evolvable_class
-Required. Implicitly specified when using EvolvableClass.new_population.
-#### id, name
-Both default to `nil`. Not used by Evolvable, but convenient when working with multiple populations.
-#### size
-Defaults to `40`. Specifies the number of instances in the population.
-#### evolutions_count
-Defaults to `0`. Useful when re-initializing a saved population with instances.
-#### gene_space
-Defaults to `evolvable_class.new_gene_space` which uses the [EvolvableClass.gene_space](#evolvableclassgene_space) method
-#### evolution
-Defaults to `Evolvable::Evolution.new`. See [evolution](#evolution-1)
-#### evaluation
-Defaults to `Evolvable::Evaluation.new`, with a goal of maximizing towards Float::INFINITY. See [evaluation](#evaluation-1)
-#### instances
-Defaults to initializing a `size` number of `evolvable_class` instances using the `gene_space` object. Any given instances are assigned, but if given less than `size`, more will be initialized.
 
-### Evolvable::Population#evolve
+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.
 
-Keyword arguments:
-
-#### count
-The number of evolutions to run. Expects a positive integer and Defaults to Float::INFINITY and will therefore run indefinitely unless a `goal_value` is specified.
-#### goal_value
-Assigns the goal object's value. Will continue running until any instance's value reaches it. See [evaluation](#evaluation-1)
+```ruby
+class HelloWorld
+  include Evolvable
 
-### Evolvable::Population#best_instance
-Returns an instance with the value that is nearest to the goal value.
+  def self.before_evolution(population)
+    best_evolvable = population.best_evolvable
+    evolutions_count = population.evolutions_count
+    puts "#{best_evolvable} - Generation #{evolutions_count}"
+  end
 
-### Evolvable::Population#met_goal?
-Returns true if any instance's value matches the goal value, otherwise false.
+  # ...
 
-### Evolvable::Population#new_instance
-Initializes an instance for the population. Note that this method does not add the new instance to its array of instances.
+  def to_s
+    @to_s ||= genes.join
+  end
 
-Keyword arguments:
+  # ...
+end
+```
 
-#### genes
-An array of initialized gene objects. Defaults to `[]`
-#### population_index
-Defaults to `nil` and expects an integer. See (EvolvableClass#population_index)[#evolvableclasspopulation_index-population_index]
+Finally we can **evolve the population with the `Evolvable::Population#evolve` instance method**.
 
+```ruby
+population.evolve
+```
 
-### Population#selection, #selection=
-The [selection](#selection-1) object.
+**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).
 
-### Population#crossover, #crossover=
-The [crossover](#crossover) object.
+## Concepts
 
-### Population#mutation, #mutation=
-The [mutation](#mutation-1) object.
+[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).
 
-### Population#goal, #goal=
-The [evaluation](#evaluation-1)'s goal object.
+The following concept map depicts how genes flow through populations.
 
-## Evaluation
+![Concept Map](https://github.com/mattruzicka/evolvable/raw/main/examples/images/diagram.png)
 
-For selection to be effective in the context of progressive evolution, there needs to be some way of comparing various instances with each other. In traditional genetic algorithms, this is referred to as the "fitness function". The `Evolvable::Evaluation` object expects instances to define a [EvolvableClass#value](#evolvableclassvalue) method that it uses to evaluate them relative to each other and against a definable goal.
+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.
 
-A goal object has a value that can be most easily assigned via an argument to `Evolvable::Population#evolve` like this: `population.evolve(goal_value: 1000)`. Evolvable provides the following goal object implementations and goal value defaults.
+## 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.
 
-### The Evolvable::Goal::Maximize object
+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.
 
-Prioritizes instances with greater values. This is the default.
 
-The default goal value is `Float::INFINITY`, but it can be reassigned as anything that implements the Ruby [Comparable](https://ruby-doc.org/core-2.7.1/Comparable.html) module.
+```ruby
+# This gene generates a random hexidecimal color code for use by evolvables.
 
-### The Evolvable::Goal::Minimize object
+require 'securerandom'
 
-Prioritizes instances with lesser values.
+class ColorGene
+  include Evolvable::Gene
 
-The default goal value is `-Float::INFINITY`, but it can be reassigned as anything that implements the Ruby [Comparable](https://ruby-doc.org/core-2.7.1/Comparable.html) module.
+  def hex_code
+    @hex_code ||= SecureRandom.hex(3)
+  end
+end
+```
 
-### The Evolvable::Goal::Equalize object
 
-Prioritizes instances that equal the goal value.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Gene)
 
-The default goal value is `0`, but it can be reassigned as anything that implements the Ruby [Comparable](https://ruby-doc.org/core-2.7.1/Comparable.html) module.
+## Populations
+Population objects are responsible for generating and evolving instances.
+They orchestrate all the other Evolvable objects to do so.
 
-### Custom Goal Objects
+Populations can be initialized and re-initialized with a number of useful
+parameters.
 
-You can implement custom goal object like so:
 
 ```ruby
-class CustomGoal
-  include Evolvable::Goal
-
-  def evaluate(instance)
-    # Required by Evolvable::Evaluation in order to sort instances in preparation for selection.
-  end
-
-  def met?(instance)
-    # Used by Evolvable::Population#evolve to stop evolving when the goal value has been reached.
-  end
-end
+# TODO: initialize a population with all supported parameters
 ```
 
-The goal for a population can be specified via assignment - `population.goal = Evolvable::Goal::Equalize.new` - or by passing an evaluation object when [initializing a population](#evolvablepopulationnew).
 
-You can intialize the `Evolvable::Evaluation` object with any goal object like this:
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
 
-```ruby
-goal_object = SomeGoal.new(value: 100)
-Evolvable::Evaluation.new(goal_object)
-```
+## 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.
 
-or more succinctly like this:
 
 ```ruby
-Evolvable::Evaluation.new(:maximize) # Uses default goal value of Float::INFINITY
-Evolvable::Evaluation.new(maximize: 50) # Sets goal value to 50
-Evolvable::Evaluation.new(:minimize) # Uses default goal value of -Float::INFINITY
-Evolvable::Evaluation.new(minimize: 100) # Sets goal value to 100
-Evolvable::Evaluation.new(:equalize) # Uses default goal value of 0
-Evolvable::Evaluation.new(equalize: 1000) # Sets goal value to 1000
+# TODO: Show how to add/change population's evaluation object
 
+# The goal value can also be assigned via as argument to `Evolvable::Population#evolve`
+population.evolve(goal_value: 1000)
 ```
 
-## Evolution
 
-After a population's instances are evaluated, they undergo evolution. The default `Evolvable::Evolution` object is composed of selection, crossover, and mutation objects and applies them as operations to the population in that order.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
 
-Populations can be assigned with custom evolution objects. The only necessary dependency for evolution objects is that they implement the `#call` method which accepts a population as the first argument. Population objects also expect evolution objects to define a getter and setter for selection, crossover, and mutation, but these methods are simply for ease-of-use and not necessary.
+## 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.
 
-### Evolvable::Evolution.new
 
-Initializes a new evolution object.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evolution)
 
-Keyword arguments:
+## 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.
 
-#### selection
-The default is `Selection.new`
-#### crossover
-The default is `GeneCrossover.new`
-#### mutation
-The default is `Mutation.new`
+Only two evolvables are selected as parents for each generation by default.
+The selection size is configurable.
 
-## Selection
 
-The selection process assumes that the population's instances have already been sorted by the `Evaluation` object. It leaves only a select number of instances in a given population's instances array.
+```ruby
+# TODO: Show how to add/change population's selection object
+```
 
-Custom selection objects must implement the `#call` method which accepts the population as the first object.
 
-### Evolvable::Selection.new
 
-Initializes a new selection object.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Selection)
 
-Keyword arguments:
+## 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.
 
-#### size
-The number of instances to select from each generation from which to perform crossover and generate or "breed" the next generation. The number of parents The default is 2.
+You may choose from a selection of combination objects or implement your own.
+The default combination object is `Evolvable::GeneCombination`.
 
-## Crossover
 
-Generates new instances by combining the genes of selected instances. You can think of it as a mixing of parent genes from one generation to produce a next generation.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Combination)
 
-Custom crossover objects must implement the `#call` method which accepts the population as the first object.
+## 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.
 
-### The Evolvable::GeneCrossover object
+Mutation frequency is configurable using the `probability` and `rate`
+parameters.
 
-Enables gene types to define crossover behaviors. Each gene class can implement a unique behavior for crossover by overriding the following default implementation which mirrors the behavior of `Evolvable::UniformCrossover`
 
 ```ruby
-def self.crossover(gene_a, gene_b)
-  [gene_a, gene_b].sample
-end
+# Show how to initialize/assign population with a specific mutation object
 ```
 
-### The Evolvable::UniformCrossover object
-
-Randomly chooses a gene from one of the parents for each gene position.
 
-### The Evolvable::PointCrossover object
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Mutation)
 
-Supports single and multi-point crossover. The default is single-point crossover via a `points_count` of 1 which can be changed on an existing population (`population.crossover.points_count = 5`) or during initialization (`Evolvable::PointCrossover.new(5)`)
+## 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.
 
-## Mutation
+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.
 
-Mutation serves the role of increasing genetic variation, especially when a population's instances are small in number and mostly homogeneous. When an instance undergoes a mutation, it means that one of its existing genes is replaced with a newly initialized gene. Using the language from the [section on genes](genes), a gene mutation invokes a new outcome from the gene's sample space.
 
-### Evolvable::Mutation.new
-
-Initializes a new mutation object.
-
-Keyword arguments:
+```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]
+```
 
-#### probability
-The probability that a particular instance undergoes a mutation. By default, the probability is 0.03 which translates to 3%. If initialized with a `rate`, the probability will be 1 which means all genes _can_ undergo mutation, but actual gene mutations will be subject to the given mutation rate.
-#### rate
-the rate at which individual genes mutate. The default rate is 0 which, when combined with a non-zero `probability` (the default), means that one gene for each instance that undergoes mutation will change. If a rate is given, but no `probability` is given, then the `probability` will bet set to 1 which always defers to the mutation rate.
 
-To summarize, the `probability` represents the chance of mutation on the instance level and the `rate` represents the chance on the gene level. The `probability` and `rate` can be any number from 0 to 1. When the `probability` is 0, no mutation will ever happen. When the `probability` is not 0 but the rate is 0, then any instance that undergoes mutation will only receive one mutant gene. If the rate is not 0, then if an instance has been chosen to undergo mutation, each of its genes will mutate with a probability as defined by the `rate`.
+[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
 
-Example Initializations:
+## Contributing
 
-```ruby
-Evolvable::Mutation.new # Approximately 3% of instances will receive one mutant gene
-Evolvable::Mutation.new(probability: 0.5) # Approximately 50% of instances will receive one mutant gene
-Evolvable::Mutation.new(rate: 0.03) # Approximately  3% of all genes in the population will mutate.
-Evolvable::Mutation.new(probability: 0.3, rate: 0.03) # Approximately 30% of instances will have approximately 3% of their genes mutated.
-```
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/evolvable.
 
-Custom mutation objects must implement the `#call` method which accepts the population as the first object.
+If you're interested in contributing, but don't know where to get started, message me on twitter at [@mattruzicka](https://twitter.com/mattruzicka).