evolvable 1.2.0 → 2.0.0

data/README.md

@@ -1,11 +1,36 @@
-# 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)
+[![Gem Version](https://badge.fury.io/rb/evolvable.svg)](https://badge.fury.io/rb/evolvable)
 
-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.
+**Code Version: 2.0.0**
 
-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).
+Evolvable is a Ruby gem that brings genetic algorithms to Ruby objects through simple, flexible APIs. Define genes, implement fitness criteria, and let evolution discover optimal solutions through selection, combination, and mutation.
 
+Perfect for optimization problems, creative content generation, machine learning, and simulating complex systems.
+
+## Why Evolvable?
+
+Evolvable is ideal when the solution space is too large or complex for brute-force methods. Instead of hardcoding solutions, you define constraints and let evolution discover optimal configurations over time.
+
+**The Evolvable Approach:**
+- Explore vast solution spaces efficiently without examining every possibility
+- Discover novel solutions that might not be obvious to human designers
+- Adapt to changing conditions through continuous evolution
+- Balance diverse objectives with communities of different populations
+- Integrate evolutionary concepts directly into your Ruby object model
+- Generate creative content like music, art, and text, not just numerical optimization
+
+Whether you're optimizing parameters, generating creative content, or simulating complex systems, Evolvable provides a natural, object-oriented approach to evolutionary algorithms.
+
+**Creative Applications**
+
+Evolvable treats creative, object-oriented representations as first-class citizens. The same API that optimizes numeric parameters can evolve music compositions, UI layouts, or game content with equal fluency. Examples include:
+
+- **Generative art**: Evolve visual compositions based on aesthetic criteria
+- **Music composition**: Create melodies, chord progressions, and rhythms
+- **Game design**: Generate levels, characters, or game mechanics
+- **Natural language**: Evolve text with specific tones, styles, or constraints
+- **UI/UX design**: Discover intuitive layouts and color schemes
 
 ## Table of Contents
 * [Installation](#installation)
@@ -18,342 +43,625 @@ Subscribe to the [Evolvable Newsletter](https://www.evolvable.site/newsletter) t
 * [Selection](#selection)
 * [Combination](#combination)
 * [Mutation](#mutation)
-* [Search Space](#search-space)
+* [Gene Clusters](#gene-clusters)
+* [Community](#community)
+* [Serialization](#serialization)
+* [Documentation](https://mattruzicka.github.io/evolvable)
 
 
 ## Installation
 
 Add [gem "evolvable"](https://rubygems.org/gems/evolvable) to your Gemfile and run `bundle install` or install it yourself with: `gem install evolvable`
 
+**Ruby Compatibility:** Evolvable officially supports Ruby 3.0 and higher.
+
 ## Getting Started
 
-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.
+**Quick start**:
+  1. Include `Evolvable` in your Ruby class
+  2. Define genes with the macro-style `gene` method
+  3. Have the `#fitness` method return a numeric value
+  4. Initialize a population and evolve it
+
+Example population of "shirts" with various colors, buttons, and collars.
 
-### Implementation Steps
+```ruby
+# Step 1
+class Shirt
+  include Evolvable
 
-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)
+  # Step 2
+  gene :color, type: ColorGene # count: 1 default
+  gene :buttons, type: ButtonGene, count: 0..10 # Builds an array of genes that can vary in size
+  gene :collar, type: CollarGene, count: 0..1 # Collar optional
 
+  # Step 3
+  attr_accessor :fitness
+end
 
-To demonstrate these steps, we'll look at the [Hello World](#) example program.
+# Step 4
+population = Shirt.new_population(size: 10)
+population.evolvables.each { |shirt| shirt.fitness = style_rating }
+```
 
-### Hello World
+You are free to tailor the genes to your needs and find a style that suits you.
 
-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.
+The `ColorGene` could be as simple as this:
 
-Below is example output from evolving a population of randomly initialized string objects to match "Hello World!", then "Hello Evolvable World".
+```ruby
+class ColorGene
+  include Evolvable::Gene
 
+  def to_s
+    @to_s ||= %w[red green blue].sample
+  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
+Shirts aren't your style?
 
-❯ Enter a string to evolve: Hello Evolvable World
+Here's a [Hello World](https://github.com/mattruzicka/evolvable/blob/main/exe/hello_evolvable_world)
+command line demo.
 
-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
-```
 
-### Step 1
+## Concepts
+
+Evolvable is built on these core concepts:
+- **Genes**: Ruby objects that represent traits or behaviors and are passed down during evolution.
+- **Evolvables**: Your Ruby classes that include "Evolvable" and delegate to genes
+- **Populations**: Groups of evolvables instances that evolve together
+- **Evaluation**: Sorts evolvables by fitness
+- **Evolution**: Selection → Combination → Mutation to generate new evolvables
+- **Communities**: Encapsulate evolvable populations
 
-Let's begin by defining a `HelloWorld` class and have it **include the `Evolvable` module**.
+The framework offers built-in implementations while allowing domain-specific customization through its extensible and swapable components.
+
+## Genes
+
+Genes are the building blocks of evolvable objects, encapsulating individual characteristics
+that can be combined and mutated during evolution. Each gene represents a trait or behavior
+that can influence an evolvable's performance.
+
+**To define a gene class:**
+1. Include the `Evolvable::Gene` module
+2. Define how the gene's value is determined
 
 ```ruby
-class HelloWorld
-  include Evolvable
+class BehaviorGene
+  include Evolvable::Gene
+
+  def value
+    @value ||= %w[explore gather attack defend build].sample
+  end
 end
 ```
 
-### Step 2
-
-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.
+Then use it in an evolvable class:
 
 ```ruby
-class HelloWorld
+class Robot
   include Evolvable
 
-  def self.search_space
-    ["CharGene", 1..40]
+  gene :behaviors, type: BehaviorGene, count: 3..5
+  gene :speed, type: SpeedGene, count: 1
+
+  def fitness
+    run_simulation(behaviors: behaviors.map(&:value), speed: speed.value)
   end
 end
 ```
 
-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.
+**Gene Count**
 
-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.
+You can control how many copies of a gene are created using the `count:` parameter:
 
-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.
+- `count: 1` (default) creates a single instance.
+- A numeric value (e.g. `count: 5`) creates a fixed number of genes using `RigidCountGene`.
+- A range (e.g. `count: 2..8`) creates a variable number of genes using `CountGene`, allowing the count to evolve over time.
 
-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.
+Evolves melody length:
 
 ```ruby
-class CharGene
+gene :notes, type: NoteGene, count: 4..12
+```
+
+**Custom Combination**
+
+By default, the `combine` method randomly picks one of the two parent genes.
+A gene class can implement custom behavior by overriding `.combine`.
+
+```ruby
+class SpeedGene
   include Evolvable::Gene
 
-  def self.chars
-    @chars ||= 32.upto(126).map(&:chr)
+  def self.combine(gene_a, gene_b)
+    new_gene = new
+    new_gene.value = (gene_a.value + gene_b.value) / 2
+    new_gene
   end
 
-  def to_s
-    @to_s ||= self.class.chars.sample
+  attr_writer :value
+
+  def value
+    @value ||= rand(1..100)
   end
 end
 ```
 
-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.
+**Design Patterns**
+
+Effective gene design typically follows these principles:
 
-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.
+- **Immutability**: Cache values after initial sampling (e.g., `@value ||= ...`)
+- **Self-Contained**: Genes should encapsulate their logic and state
+- **Composable**: You can build complex structures using multiple genes or clusters
+- **Domain-Specific**: Genes should map directly to your problem’s traits or features
 
-### Step 3
+Genes come in various types, each representing different aspects of a solution.
+Common examples include numeric genes for quantities, selection genes for choices
+from sets, boolean genes for binary decisions, structural genes for architecture,
+and parameter genes for configuration settings.
 
-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.
 
-For a working implementation, see the `#value` method in [examples/hello_world.rb](https://github.com/mattruzicka/evolvable/blob/main/examples/hello_world.rb)
+[Gene Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Gene)
 
-### Step 4
+## Populations
 
-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.
+Populations orchestrate the evolutionary process through four key components:
 
-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%).
+1. **Evaluation**: Sorts evolvable instances by fitness
+2. **Selection**: Chooses parents for combination
+3. **Combination**: Creates new evolvables from selected parents
+4. **Mutation**: Introduces variation to maintain genetic diversity
 
-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)
+**Features**:
+
+Initialize a population with default or custom parameters:
 
 ```ruby
-population = HelloWorld.new_population(size: 100,
-                                       evaluation: { equalize: 0 },
-                                       mutation: { probability: 0.6 }
+population = YourEvolvable.new_population(
+  size: 50,
+  evaluation: { equalize: 0 },
+  selection: { size: 10 },
+  mutation: { probability: 0.2, rate: 0.02 }
+)
 ```
 
+Or inject fully customized strategy objects:
 
-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.
+```ruby
+population = YourEvolvable.new_population(
+  evaluation: Your::Evaluation.new,
+  evolution: Your::Evolution.new,
+  selection: Your::Selection.new,
+  combination: Your::Combination.new,
+  mutation: Your::Mutation.new
+)
+```
 
-### Evolvable Population Hooks
+Evolve your population:
 
-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.
+```ruby
+population.evolve(count: 20)            # Run for 20 generations
+population.evolve_to_goal               # Run until the current goal is met
+population.evolve_to_goal(0.0)          # Run until a specific goal is met
+population.evolve_forever               # Run indefinitely, ignoring any goal
+population.evolve_selected([...])       # Use a custom subset of evolvables
+```
 
-1. `.before_evaluation(population)` - Runs before evaluation.
+Create new evolvables:
 
-2. `.before_evolution(population)`- Runs after evaluation and before evolution.
+```ruby
+new = population.new_evolvable
+many = population.new_evolvables(count: 10)
+with_genome = population.new_evolvable(genome: another.genome)
+```
 
-3. `.after_evolution(population)` - Runs after evolution.
+Customize the evolution lifecycle by implementing hooks:
 
+```ruby
+def self.before_evaluation(pop); end
+def self.before_evolution(pop); end
+def self.after_evolution(pop); end
+```
 
-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.
+Evaluate progress:
 
 ```ruby
-class HelloWorld
-  include Evolvable
+best = population.best_evolvable if population.met_goal?
+```
 
-  def self.before_evolution(population)
-    best_evolvable = population.best_evolvable
-    evolutions_count = population.evolutions_count
-    puts "#{best_evolvable} - Generation #{evolutions_count}"
-  end
 
-  # ...
+[Population Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Population)
 
-  def to_s
-    @to_s ||= genes.join
-  end
+## Evaluation
 
-  # ...
-end
-```
+Evaluation sorts evolvables based on their fitness and provides mechanisms to
+change the goal type and value (fitness goal). Goals define the success criteria
+for evolution. They allow you to specify what your population is evolving toward,
+whether it's maximizing a value, minimizing a value, or seeking a specific value.
+
+**How It Works**
 
-Finally we can **evolve the population with the `Evolvable::Population#evolve` instance method**.
+1. Your evolvable class defines a `#fitness` method that returns a
+[Comparable](https://docs.ruby-lang.org/en//3.4/Comparable.html) object.
+   - Preferably a numeric value like an integer or float.
+
+2. During evolution, evolvables are sorted by your goal's fitness interpretation
+   - The default goal type is `:maximize`, see goal types below for other options
+
+3. If a goal value is specified, evolution will stop when it is met
+
+**Goal Types**
+
+- Maximize (higher is better)
 
 ```ruby
-population.evolve
+robots = Robot.new_population(evaluation: :maximize) # Defaults to infinity
+robots.evolve_to_goal(100) # Evolve until fitness reaches 100+
+
+# Same as above
+Robot.new_population(evaluation: { maximize: 100 }).evolve_to_goal
 ```
 
-**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).
+- Minimize (lower is better)
 
-## Concepts
+```ruby
+errors = ErrorModel.new_population(evaluation: :minimize) # Defaults to -infinity
+errors.evolve_to_goal(0.01)  # Evolve until error rate reaches 0.01 or less
 
-[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).
+# Same as above
+ErrorModel.new_population(evaluation: { minimize: 0.01 }).evolve_to_goal
+```
 
-The following concept map depicts how genes flow through populations.
+- Equalize (closer to target is better)
 
-![Concept Map](https://github.com/mattruzicka/evolvable/raw/main/examples/images/diagram.png)
+```ruby
+targets = TargetMatcher.new_population(evaluation: :equalize) # Defaults to 0
+targets.evolve_to_goal(42)  # Evolve until we match the target value
 
-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.
+# Same as above
+TargetMatcher.new_population(evaluation: { equalize: 42 }).evolve_to_goal
+```
 
-## 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.
 
-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.
+**Custom Goals**
 
+You can create custom goals by subclassing `Evolvable::Goal` and implementing:
+- `evaluate(evolvable)`: Return a value that for sorting evolvables
+- `met?(evolvable)`: Returns true when the goal value is reached
+
+
+Example goal implementation that prioritizes evolvables with fitness values within a specific range:
 
 ```ruby
-# This gene generates a random hexidecimal color code for use by evolvables.
+class YourRangeGoal < Evolvable::Goal
+  def value
+    @value ||= 0..100
+   end
 
-require 'securerandom'
+  def evaluate(evolvable)
+    return 1 if value.include?(evolvable.fitness)
 
-class ColorGene
-  include Evolvable::Gene
+    min, max = value.minmax
+    -[(min - evolvable.fitness).abs, (max - evolvable.fitness).abs].min
+  end
 
-  def hex_code
-    @hex_code ||= SecureRandom.hex(3)
+  def met?(evolvable)
+    value.include?(evolvable.fitness)
   end
 end
 ```
 
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Gene)
+[Evaluation Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Evaluation)
 
-## Populations
-Population objects are responsible for generating and evolving instances.
-They orchestrate all the other Evolvable objects to do so.
+[Goal Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Goal)
+
+## Evolution
+
+**Evolution** moves a population from one generation to the next.
+It runs in three steps: selection, combination, and mutation.
+You can swap out any step with your own strategy.
+
+Default pipeline:
+1. **Selection** – keep the most fit evolvables
+2. **Combination** – create offspring by recombining genes
+3. **Mutation** – add random variation to preserve diversity
 
-Populations can be initialized and re-initialized with a number of useful
-parameters.
 
+[Evolution Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Evolution)
+
+## Selection
+
+Selection determines which evolvables will serve as parents for the next
+generation. You can control the selection process in several ways:
+
+Set the selection size during population initialization:
 
 ```ruby
-# TODO: initialize a population with all supported parameters
+population = MyEvolvable.new_population(
+  selection: { size: 3 }
+)
 ```
 
+Adjust the selection size after initialization:
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population)
+```ruby
+population.selection_size = 4
+```
 
-## 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".
+Manually assign the selected evolvables:
 
-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.
+```ruby
+population.selected_evolvables = [evolvable1, evolvable2]
+```
 
+Or evolve a custom selection directly:
 
 ```ruby
-# TODO: Show how to add/change population's evaluation object
+population.evolve_selected([evolvable1, evolvable2])
+```
+
+This flexibility lets you implement custom selection strategies,
+overriding or augmenting the built-in behavior.
+
+
+[Selection Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Selection)
+
+## Combination
+
+Combination is the process of creating new evolvables by mixing the genes
+of selected parents. This step drives the creation of the next generation
+by recombining traits in novel ways.
 
-# The goal value can also be assigned via as argument to `Evolvable::Population#evolve`
-population.evolve(goal_value: 1000)
+You can choose from several built-in combination strategies or implement your own.
+By default, Evolvable uses `Evolvable::GeneCombination`, which delegates
+gene-level behavior to individual gene classes.
+
+To define custom combination logic for a gene type, implement:
+
+```ruby
+YourGeneClass.combine(parent_1_gene, parent_2_gene)
 ```
 
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evaluation)
+[Combination Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Combination)
 
-## 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.
+**Point Crossover**
 
+A classic genetic algorithm strategy that performs single or multi-point crossover
+by selecting random positions in the genome and swapping gene segments between parents.
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Evolution)
+- **Single-point crossover (default):** Swaps all genes after a randomly chosen position.
+- **Multi-point crossover:** Alternates segments between multiple randomly chosen points.
 
-## 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.
+Best for:
+- Preserving beneficial gene blocks
+- Problems where related traits are located near each other
 
-Only two evolvables are selected as parents for each generation by default.
-The selection size is configurable.
+Set your population to use this strategy during initialization with:
 
+```ruby
+population = MyEvolvable.new_population(
+  combination: Evolvable::PointCrossover.new(points_count: 2)
+)
+```
+
+Or update an existing population:
 
 ```ruby
-# TODO: Show how to add/change population's selection object
+population.combination = Evolvable::PointCrossover.new(points_count: 3)
 ```
 
 
+[PointCrossover Documentation](https://mattruzicka.github.io/evolvable/Evolvable/PointCrossover)
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Selection)
+**Uniform Crossover**
 
-## 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.
+Chooses genes independently at each position, selecting randomly from either
+parent with equal probability. No segments are preserved—each gene is treated
+in isolation.
+
+Best for:
+- Problems where gene order doesn't matter
+- High genetic diversity and exploration
+- Complex interdependencies across traits
 
-You may choose from a selection of combination objects or implement your own.
-The default combination object is `Evolvable::GeneCombination`.
+Uniform crossover is especially effective when good traits are scattered across the genome.
 
+Set your population to use this strategy during initialization with:
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Combination)
+```ruby
+population = MyEvolvable.new_population(
+  combination: Evolvable::UniformCrossover.new
+)
+```
+
+Or update an existing population:
+
+```ruby
+population.combination = Evolvable::UniformCrossover.new
+```
+
+
+[UniformCrossover Documentation](https://mattruzicka.github.io/evolvable/Evolvable/UniformCrossover)
 
 ## 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.
 
-Mutation frequency is configurable using the `probability` and `rate`
-parameters.
+Mutation introduces genetic variation by randomly replacing genes with new
+ones. This helps the population explore new areas of the solution space
+and prevents premature convergence on suboptimal solutions.
+
+Mutation is controlled by two key parameters:
+- **probability**: Likelihood that an individual will undergo mutation (range: 0.0–1.0)
+- **rate**: Fraction of genes to mutate within those individuals (range: 0.0–1.0)
+
+A typical strategy is to start with higher mutation to encourage exploration:
+
+```ruby
+population = MyEvolvable.new_population(
+  mutation: { probability: 0.4, rate: 0.2 }
+)
+```
+
+Then later reduce the mutation rate to focus on refinement and convergence:
+
+```ruby
+population.mutation_probability = 0.1
+population.mutation_rate = 0.05
+```
+
+
+[Mutation Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Mutation)
+
+## Gene Clusters
+
+Gene clusters group related genes into reusable components that can be applied
+to multiple evolvable classes. This promotes clean organization, eliminates
+naming conflicts, and simplifies gene access.
 
+**Benefits:**
+- Reuse gene groups across multiple evolvables
+- Prevent name collisions via automatic namespacing
+- Treat clusters as structured subcomponents of a genome
+- Access all genes in a cluster with a single method call
+
+The `ColorPaletteCluster` below defines a group of genes commonly used for styling themes:
+
+```ruby
+class ColorPaletteCluster
+  include Evolvable::GeneCluster
+
+  gene :primary, type: 'ColorGene', count: 1
+  gene :secondary, type: 'ColorGene', count: 1
+  gene :accent, type: 'ColorGene', count: 1
+  gene :neutral, type: 'ColorGene', count: 1
+end
+```
+
+Use the `cluster` macro to apply the cluster to your evolvable class:
+
+```ruby
+class Theme
+  include Evolvable
+
+  cluster :colors, type: ColorPaletteCluster
+
+  def inspect_colors
+    colors.join(", ")
+  end
+end
+```
+
+When a cluster is applied, its genes are automatically namespaced with the cluster name:
+- Access the full group: `theme.colors` → returns all genes in the colors cluster
+- Access individual genes: `theme.find_gene("colors-primary")`
+
+
+[GeneCluster Documentation](https://mattruzicka.github.io/evolvable/Evolvable/GeneCluster)
+
+## Community
+
+The `Community` module provides a framework for coordinating multiple evolvable populations
+under a unified interface. Each population represents a distinct type of evolvable, and
+each key returns a single evolvable instance drawn from its corresponding population.
+
+Communities are ideal for simulations or systems where different components evolve
+in parallel but interact as part of a larger whole - such as ecosystems, design systems,
+or modular agents. Evolvables from different populations can co-evolve, influencing each other's fitness.
+
+Use the `evolvable_community` macro to declare the set of named populations in the community.
+Each population will have a corresponding method (e.g., `fish_1`, `plant`, `shrimp`) that
+returns a single evolvable instance. You can evolve all populations together using the
+`evolve` method, or per population.
+
+**Key Features**
+- Define a community composed of named populations
+- Automatically generate accessors for each evolvable instance
+- Coordinate evolution across populations through a shared interface
+- Evolve all populations in a single call with `evolve(...)`
+
+This `FishTank` example sets up a community with four named populations:
 
 ```ruby
-# Show how to initialize/assign population with a specific mutation object
+class FishTank
+  include Evolvable::Community
+
+  evolvable_community fish_1: Fish,
+                      fish_2: Fish,
+                      plant: AquariumPlant,
+                      shrimp: CleanerShrimp
+
+  def describe_tank
+    puts "🐟 Fish 1: #{fish_1.name} (#{fish_1.color})"
+    puts "🐟 Fish 2: #{fish_2.name} (#{fish_2.color})"
+    puts "🌿 Plant: #{plant.name} (#{plant.color})"
+    puts "🦐 Shrimp: #{shrimp.name} (#{shrimp.color})"
+  end
+end
 ```
 
+Initialize the community, describe the tank, and evolve each population:
+
+```ruby
+tank = FishTank.new_community
+tank.describe_tank
+tank.evolve
+```
+
+
+[Community Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Community)
+
+## Serialization
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Mutation)
+Evolvable supports saving and restoring the state of both populations
+and individual evolvable instances through a built-in `Serializer`.
+By default, it uses Ruby's `Marshal` class for fast, portable binary serialization.
 
-## 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.
+Serialization is useful for:
+- Saving progress during long-running evolution
+- Storing champion solutions for later reuse
+- Transferring evolved populations between systems
+- Creating checkpoints you can revert to
 
-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.
+Both `Population` and individual evolvables expose `dump` and `load` methods
+that use the `Serializer` internally.
 
+Save a population to a file:
 
 ```ruby
-# All 9 of these example definitions are equivalent
+population = YourEvolvable.new_population
+population.evolve(count: 100)
+File.write("population.marshal", population.dump)
+```
+
+Restore and continue evolution:
+
+```ruby
+data = File.read("population.marshal")
+restored = Evolvable::Population.load(data)
+restored.evolve(count: 100)
+```
 
-# Hash syntax
-{ chars: { type: 'CharGene', max_count: 100 } }
-{ chars: { type: 'CharGene', min_count: 1, max_count: 100 } }
-{ chars: { type: 'CharGene', count: 1..100 } }
+Save an individual evolvable's genome:
 
-# Array of arrays syntax
-[[:chars, 'CharGene', 1..100]]
-[['chars', 'CharGene',  1..100]]
-[['CharGene', 1..100]]
+```ruby
+best = restored.best_evolvable
+File.write("champion.marshal", best.dump_genome)
+```
+
+Restore genome into a new evolvable:
 
-# A single array works when there's only one type of gene
-['CharGene', 1..100]
-[:chars, 'CharGene', 1..100]
-['chars', 'CharGene', 1..100]
+```ruby
+raw = File.read("champion.marshal")
+champion = YourEvolvable.new_evolvable
+champion.load_genome(raw)
 ```
 
 
-[Documentation](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/SearchSpace)
+[Serializer Documentation](https://mattruzicka.github.io/evolvable/Evolvable/Serializer)
 
 ## Contributing
 
-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).
+Bug reports and pull requests are welcome on GitHub at https://github.com/mattruzicka/evolvable.