More updates to README and docs

Author: mattruzicka

README.md

@@ -2,9 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/evolvable.svg)](https://badge.fury.io/rb/evolvable)
 
-**Code Version: {@string Evolvable::VERSION}** (unreleased)
-
-🚧 **The README and Documentation are still evolving**
+**Code Version: {@string Evolvable::VERSION}**
 
 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.
 
@@ -24,11 +22,10 @@ Evolvable is ideal when the solution space is too large or complex for brute-for
 
 Whether you're optimizing parameters, generating creative content, or simulating complex systems, Evolvable provides a natural, object-oriented approach to evolutionary algorithms.
 
-## Creative Applications
+**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.
+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:
 
-Creative applications of Evolvable 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
@@ -45,11 +42,7 @@ Creative applications of Evolvable include:
 * [Evolution](#evolution)
 * [Selection](#selection)
 * [Combination](#combination)
-* [Crossover Strategies](#crossover-strategies)
 * [Mutation](#mutation)
-* [Gene Space](#gene-space)
-* [Count Genes](#count-genes)
-* [Genomes](#genomes)
 * [Gene Clusters](#gene-clusters)
 * [Community](#community)
 * [Serialization](#serialization)
@@ -69,7 +62,7 @@ Add [gem "evolvable"](https://rubygems.org/gems/evolvable) to your Gemfile and r
 ## Concepts
 
 Evolvable is built on these core concepts:
-- **Genes**: Ruby objects that cache data for evolvables
+- **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
@@ -96,8 +89,6 @@ The framework offers built-in implementations while allowing domain-specific cus
 
 {@readme Evolvable::Goal}
 
-{@readme Evolvable::Evaluation}
-
 Example goal implementation that prioritizes evolvables with fitness values within a specific range:
 
 {@example Evolvable::Goal}
@@ -124,257 +115,40 @@ Example goal implementation that prioritizes evolvables with fitness values with
 
 [Combination Documentation]({@string Evolvable::DOC_URL}/Evolvable/Combination)
 
-## Crossover Strategies
-
 **Point Crossover**
 
 {@readme Evolvable::PointCrossover}
 
+[PointCrossover Documentation]({@string Evolvable::DOC_URL}/Evolvable/PointCrossover)
+
 **Uniform Crossover**
 
 {@readme Evolvable::UniformCrossover}
 
-[PointCrossover Documentation]({@string Evolvable::DOC_URL}/Evolvable/PointCrossover)
+[UniformCrossover Documentation]({@string Evolvable::DOC_URL}/Evolvable/UniformCrossover)
 
 ## Mutation
 
 {@readme Evolvable::Mutation}
 
-**Example**
-{@example Evolvable::Mutation}
-
 [Mutation Documentation]({@string Evolvable::DOC_URL}/Evolvable/Mutation)
 
-## Gene Space
-
-{@readme Evolvable::GeneSpace}
-
-**Example**
-```ruby
-class MusicComposer
-  include Evolvable
-
-  # Define basic musical genes
-  gene :melody, type: MelodyGene, count: 1
-  gene :harmony, type: HarmonyGene, count: 1
-  gene :rhythm, type: RhythmGene, count: 1
-
-  # Group audio effects into a cluster for easier handling
-  gene :reverb, type: ReverbGene, count: 0..1, cluster: :effects
-  gene :delay, type: DelayGene, count: 0..1, cluster: :effects
-  gene :distortion, type: DistortionGene, count: 0..1, cluster: :effects
-  gene :flanger, type: FlangerGene, count: 0..1, cluster: :effects
-
-  def play
-    # Access genes directly
-    puts "Playing melody: #{melody}"
-
-    # Or access gene clusters as collections
-    puts "With effects: #{effects.map(&:name).join(', ')}"
-  end
-
-  def fitness
-    # Evaluate fitness based on musical theory and constraints
-    melody_score = melody.consonance_with(harmony)
-    structure_balance = structure.count > 1 ? 1.0 : 0.5
-    effect_complexity = [1.0, effects.count * 0.2].min
-
-    melody_score * structure_balance * effect_complexity
-  end
-end
-
-# Access genes and clusters
-composer = MusicComposer.new_evolvable
-composer.reverb                # Access a specific gene
-composer.effects               # Access all genes in the effects cluster
-composer.effects.count         # Number of effect genes
-composer.structure.first.type  # Access a property of the first structure gene
-```
-
-[GeneSpace Documentation]({@string Evolvable::DOC_URL}/Evolvable/GeneSpace)
-
-## Count Genes
-
-**Dynamic Count Genes**
-
-{@readme Evolvable::CountGene}
-
-**Fixed Count Genes**
-
-{@readme Evolvable::RigidCountGene}
-
-[CountGene Documentation]({@string Evolvable::DOC_URL}/Evolvable/CountGene)
-
-## Genomes
-
-{@readme Evolvable::Genome}
-
-[Genome Documentation]({@string Evolvable::DOC_URL}/Evolvable/Genome)
-
 ## Gene Clusters
 
 {@readme Evolvable::GeneCluster}
 
-**Example**
-```ruby
-# Define a reusable cluster for visual styling
-module Evolvable::UI
-  class StylingCluster
-    include Evolvable::GeneCluster
-
-    gene :background_color, type: 'UI::ColorGene', count: 1
-    gene :text_color, type: 'UI::ColorGene', count: 1
-    gene :border_color, type: 'UI::ColorGene', count: 0..1
-    gene :border_width, type: 'UI::SizeGene', count: 0..1
-    gene :border_radius, type: 'UI::RadiusGene', count: 0..1
-    gene :shadow, type: 'UI::ShadowGene', count: 0..1
-  end
-end
-
-# Use the styling cluster in multiple UI components
-class Button
-  include Evolvable
-
-  # Apply the styling cluster
-  cluster :styling, type: Evolvable::UI::StylingCluster
-
-  # Button-specific genes
-  gene :size, type: SizeGene, count: 1
-  gene :text, type: TextGene, count: 1
-
-  def render
-    puts "Button with #{text}"
-    puts "Background: #{styling.background_color.hex_code}"
-    puts "Border: #{styling.border_width&.value || 0}px"
-  end
-
-  def fitness
-    # Evaluate based on design principles and constraints
-    contrast = styling.text_color.contrast_with(styling.background_color)
-    readability = text.length < 15 ? 1.0 : 0.7
-
-    contrast * readability
-  end
-end
-
-class Panel
-  include Evolvable
-
-  # Reuse the same styling cluster with a different name
-  cluster :visual, type: Evolvable::UI::StylingCluster
-
-  # Panel-specific genes
-  gene :width, type: SizeGene, count: 1
-  gene :height, type: SizeGene, count: 1
-  gene :children, type: ComponentGene, count: 0..10
-
-  def render
-    puts "Panel #{width.value}x#{height.value}"
-    puts "Background: #{visual.background_color.hex_code}"
-    children.each(&:render)
-  end
-end
-```
-
 [GeneCluster Documentation]({@string Evolvable::DOC_URL}/Evolvable/GeneCluster)
 
 ## Community
 
 {@readme Evolvable::Community}
 
-**Example**
-```ruby
-# A complex ecosystem with multiple interacting species
-class BiomeSimulation
-  include Evolvable::Community
-
-  evolvable_community plants: Plant,
-                      herbivores: Herbivore,
-                      carnivores: Carnivore
-
-  def simulate_interactions(cycles = 1)
-    cycles.times do
-      # Plants grow based on environmental factors
-      plants.each(&:grow)
-
-      # Herbivores eat plants and may increase or decrease in population
-      herbivores.each do |herbivore|
-        herbivore.eat(plants.sample)
-      end
-
-      # Carnivores hunt herbivores
-      carnivores.each do |carnivore|
-        carnivore.hunt(herbivores.sample)
-      end
-
-      # Evolve all populations for one generation
-      evolve_all
-    end
-  end
-
-  def evolve_all
-    populations_by_name.values.each do |population|
-      population.evolve(count: 1)
-    end
-  end
-end
-
-# Initialize and use the simulation
-biome = BiomeSimulation.new_community
-biome.simulate_interactions(10)
-```
-
 [Community Documentation]({@string Evolvable::DOC_URL}/Evolvable/Community)
 
 ## Serialization
 
 {@readme Evolvable::Serializer}
 
-**Example**
-```ruby
-# Basic serialization and persistence
-class EvolutionManager
-  def save_champion(population, filename)
-    champion = population.best_evolvable
-    serialized = champion.dump_genome
-    File.write(filename, serialized)
-    puts "Champion saved with fitness: #{champion.fitness}"
-  end
-
-  def load_champion(evolvable_class, filename)
-    serialized = File.read(filename)
-    champion = evolvable_class.new_evolvable
-    champion.load_genome(serialized)
-    champion
-  end
-
-  def checkpoint_population(population, filename)
-    serialized = population.dump
-    File.write(filename, serialized)
-    puts "Population checkpoint saved at generation #{population.evolutions_count}"
-  end
-
-  def restore_population(filename)
-    serialized = File.read(filename)
-    Evolvable::Population.load(serialized)
-  end
-end
-
-# Usage
-manager = EvolutionManager.new
-population = MyEvolvable.new_population(size: 100)
-
-# Run evolution for 50 generations with checkpoints
-5.times do |i|
-  population.evolve(count: 10)
-  manager.checkpoint_population(population, "checkpoint_#{i}.dat")
-  manager.save_champion(population, "champion_#{i}.dat")
-end
-
-# Restore from checkpoint
-restored = manager.restore_population("checkpoint_3.dat")
-```
-
 [Serializer Documentation]({@string Evolvable::DOC_URL}/Evolvable/Serializer)
 
 ## Contributing

README_YARD.md

@@ -407,7 +407,7 @@ <h2>
         <li class="public ">
   <span class="summary_signature">
 
-      <a href="#find_gene-instance_method" title="#find_gene (instance method)">#<strong>find_gene</strong>(name)  &#x21d2; Object </a>
+      <a href="#find_gene-instance_method" title="#find_gene (instance method)">#<strong>find_gene</strong>  &#x21d2; Object </a>
 
 
 
@@ -452,7 +452,7 @@ <h2>
         <li class="public ">
   <span class="summary_signature">
 
-      <a href="#find_genes-instance_method" title="#find_genes (instance method)">#<strong>find_genes</strong>(name)  &#x21d2; Object </a>
+      <a href="#find_genes-instance_method" title="#find_genes (instance method)">#<strong>find_genes</strong>  &#x21d2; Object </a>
 
 
 
@@ -1054,7 +1054,7 @@ <h3 class="signature " id="dump_genome-instance_method">
       <div class="method_details ">
   <h3 class="signature " id="find_gene-instance_method">
 
-    #<strong>find_gene</strong>(name)  &#x21d2; <tt>Object</tt> 
+    #<strong>find_gene</strong>  &#x21d2; <tt>Object</tt> 
 
 
 
@@ -1073,8 +1073,8 @@ <h3 class="signature " id="find_gene-instance_method">
     <td>
       <pre class="code"><span class="info file"># File 'lib/evolvable.rb', line 304</span>
 
-<span class='kw'>def</span> <span class='id identifier rubyid_find_gene'>find_gene</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
-  <span class='ivar'>@genome</span><span class='op'>&amp;.</span><span class='id identifier rubyid_find_gene'>find_gene</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
+<span class='kw'>def</span> <span class='id identifier rubyid_find_gene'>find_gene</span><span class='lparen'>(</span><span class='op'>...</span><span class='rparen'>)</span>
+  <span class='ivar'>@genome</span><span class='op'>&amp;.</span><span class='id identifier rubyid_find_gene'>find_gene</span><span class='lparen'>(</span><span class='op'>...</span><span class='rparen'>)</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -1161,7 +1161,7 @@ <h3 class="signature " id="find_gene_cluster-instance_method">
       <div class="method_details ">
   <h3 class="signature " id="find_genes-instance_method">
 
-    #<strong>find_genes</strong>(name)  &#x21d2; <tt>Object</tt> 
+    #<strong>find_genes</strong>  &#x21d2; <tt>Object</tt> 
 
 
 
@@ -1180,8 +1180,8 @@ <h3 class="signature " id="find_genes-instance_method">
     <td>
       <pre class="code"><span class="info file"># File 'lib/evolvable.rb', line 308</span>
 
-<span class='kw'>def</span> <span class='id identifier rubyid_find_genes'>find_genes</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span>
-  <span class='ivar'>@genome</span><span class='op'>&amp;.</span><span class='id identifier rubyid_find_genes'>find_genes</span><span class='lparen'>(</span><span class='id identifier rubyid_name'>name</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='lbracket'>[</span><span class='rbracket'>]</span>
+<span class='kw'>def</span> <span class='id identifier rubyid_find_genes'>find_genes</span><span class='lparen'>(</span><span class='op'>...</span><span class='rparen'>)</span>
+  <span class='ivar'>@genome</span><span class='op'>&amp;.</span><span class='id identifier rubyid_find_genes'>find_genes</span><span class='lparen'>(</span><span class='op'>...</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='lbracket'>[</span><span class='rbracket'>]</span>
 <span class='kw'>end</span></pre>
     </td>
   </tr>
@@ -1609,7 +1609,7 @@ <h3 class="signature " id="merge_genome!-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri May  9 16:06:43 2025 by
+  Generated on Sat May 10 18:35:47 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.2).
 </div>

docs/Evolvable.html

@@ -1223,7 +1223,7 @@ <h3 class="signature " id="new_population-instance_method">
 </div>
 
       <div id="footer">
-  Generated on Fri May  9 16:06:43 2025 by
+  Generated on Sat May 10 18:35:47 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.37 (ruby-3.4.2).
 </div>