evolvable 1.2.0 → 2.0.0

data/lib/evolvable/serializer.rb

@@ -1,6 +1,52 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
+  # @readme
+  #   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.
+  #
+  #   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
+  #
+  #   Both `Population` and individual evolvables expose `dump` and `load` methods
+  #   that use the `Serializer` internally.
+  #
+  #   Save a population to a file:
+  #
+  #   ```ruby
+  #   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)
+  #   ```
+  #
+  #   Save an individual evolvable's genome:
+  #
+  #   ```ruby
+  #   best = restored.best_evolvable
+  #   File.write("champion.marshal", best.dump_genome)
+  #   ```
+  #
+  #   Restore genome into a new evolvable:
+  #
+  #   ```ruby
+  #   raw = File.read("champion.marshal")
+  #   champion = YourEvolvable.new_evolvable
+  #   champion.load_genome(raw)
+  #   ```
+  #
   class Serializer
     class << self
       def dump(data)

data/lib/evolvable/uniform_crossover.rb

@@ -2,7 +2,31 @@
 
 module Evolvable
   #
-  # Randomly chooses a gene from one of the parents for each gene position.
+  # @readme
+  #   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
+  #
+  #   Uniform crossover is especially effective when good traits are scattered across the genome.
+  #
+  #   Set your population to use this strategy during initialization with:
+  #
+  #   ```ruby
+  #   population = MyEvolvable.new_population(
+  #     combination: Evolvable::UniformCrossover.new
+  #   )
+  #   ```
+  #
+  #   Or update an existing population:
+  #
+  #   ```ruby
+  #   population.combination = Evolvable::UniformCrossover.new
+  #   ```
   #
   class UniformCrossover
     def call(population)
@@ -22,10 +46,11 @@ module Evolvable
 
     def build_genome(genome_pair)
       new_config = {}
-      genome_1, genome_2 = genome_pair.shuffle!
+      genome_1, genome_2 = genome_pair
       genome_1.each do |gene_key, gene_config_1|
-        count_gene = gene_config_1[:count_gene]
-        genes = crossover_genes(count_gene.count, gene_config_1, genome_2.config[gene_key])
+        gene_config_2 = genome_2.config[gene_key]
+        count_gene = [gene_config_1, gene_config_2].sample[:count_gene]
+        genes = crossover_genes(count_gene.count, gene_config_1, gene_config_2)
         new_config[gene_key] = { count_gene: count_gene, genes: genes }
       end
       Genome.new(config: new_config)
@@ -34,8 +59,7 @@ module Evolvable
     def crossover_genes(count, gene_config_1, gene_config_2)
       gene_arrays = [gene_config_1[:genes], gene_config_2[:genes]]
       Array.new(count) do |index|
-        genes = gene_arrays.sample
-        genes[index] || gene_arrays.detect { |a| a != genes }[index]
+        gene_arrays.shuffle!.detect { |genes| genes[index] }
       end
     end
   end

data/lib/evolvable/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Evolvable
-  VERSION = '1.2.0'
+  VERSION = '2.0.0'
+  DOC_URL = "https://mattruzicka.github.io/evolvable"
 end

data/lib/evolvable.rb

@@ -2,9 +2,9 @@
 
 require 'forwardable'
 require 'evolvable/version'
-require 'evolvable/error/undefined_method'
 require 'evolvable/gene'
-require 'evolvable/search_space'
+require 'evolvable/gene_cluster'
+require 'evolvable/gene_space'
 require 'evolvable/genome'
 require 'evolvable/goal'
 require 'evolvable/equalize_goal'
@@ -21,28 +21,87 @@ require 'evolvable/population'
 require 'evolvable/count_gene'
 require 'evolvable/rigid_count_gene'
 require 'evolvable/serializer'
+require 'evolvable/community'
 
 #
 # @readme
-#   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
 #
-#   ### Implementation Steps
+#   Example population of "shirts" with various colors, buttons, and collars.
 #
-#   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)
+#   ```ruby
+#   # Step 1
+#   class Shirt
+#     include Evolvable
+#
+#     # 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
+#
+#   # Step 4
+#   population = Shirt.new_population(size: 10)
+#   population.evolvables.each { |shirt| shirt.fitness = style_rating }
+#   ```
+#
+#   You are free to tailor the genes to your needs and find a style that suits you.
+#
+#   The `ColorGene` could be as simple as this:
+#
+#   ```ruby
+#   class ColorGene
+#     include Evolvable::Gene
+#
+#     def to_s
+#       @to_s ||= %w[red green blue].sample
+#     end
+#   end
+#   ```
+#
+#   Shirts aren't your style?
+#
+#   Here's a [Hello World](https://github.com/mattruzicka/evolvable/blob/main/exe/hello_evolvable_world)
+#   command line demo.
 #
 module Evolvable
   extend Forwardable
 
+  #
+  # Error class for Evolvable-specific exceptions.
+  #
+  class Error < StandardError; end
+
+  #
+  # Called when the Evolvable module is included in a class.
+  # Sets up the necessary instance variables and extends the class with ClassMethods.
+  #
+  # @param base [Class] The class that is including the Evolvable module
+  # @return [void]
+  #
   def self.included(base)
+    base.instance_variable_set(:@gene_config, {})
+    base.instance_variable_set(:@cluster_config, {})
     base.extend(ClassMethods)
   end
 
+  #
+  # Helper method for creating or updating objects with hash parameters.
+  # This is used internally for creating evaluation, selection, mutation, etc. objects
+  # from configuration hashes.
+  #
+  # @param old_val [Object, nil] The existing object to update, if any
+  # @param new_val [Object, Hash] The new object or configuration hash
+  # @param default_class [Class] The default class to instantiate if new_val is a Hash
+  # @return [Object] The new or updated object
+  #
   def self.new_object(old_val, new_val, default_class)
     new_val.is_a?(Hash) ? (old_val&.class || default_class).new(**new_val) : new_val
   end
@@ -50,9 +109,8 @@ module Evolvable
   module ClassMethods
     #
     # @readme
-    #   Initializes a population using configurable defaults that can be configured and optimized.
-    #   Accepts the same named parameters as
-    #   [Population#initialize](https://rubydoc.info/github/mattruzicka/evolvable/Evolvable/Population#initialize).
+    #   Initializes a population with defaults that can be changed using the same named parameters as
+    #   [Population#initialize](https://mattruzicka.github.io/evolvable/Evolvable/Population#initialize).
     #
     def new_population(keyword_args = {})
       keyword_args[:evolvable_type] = self
@@ -69,102 +127,148 @@ module Evolvable
     # initialized you can override either of the following two "initialize_instance"
     # methods.
     #
-    def new_evolvable(population: nil,
-                      genome: Genome.new,
-                      generation_index: nil)
+    def new_evolvable(population: nil, genome: nil, generation_index: nil)
       evolvable = initialize_evolvable
-      evolvable.population = population
-      evolvable.genome = genome
-      evolvable.generation_index = generation_index
-      evolvable.after_initialize
+      evolvable.make_evolvable(population: population, genome: genome, generation_index: generation_index)
+      evolvable.after_initialize_evolvable
       evolvable
     end
 
+    #
+    # Override this method to customize how your evolvable instances are initialized.
+    # By default, simply calls new with no arguments.
+    #
+    # @return [Evolvable] A new evolvable instance
+    #
     def initialize_evolvable
       new
     end
 
-    def new_search_space
-      space_config = search_space.empty? ? gene_space : search_space
-      search_space = SearchSpace.build(space_config, self)
-      search_spaces.each { |space| search_space.merge_search_space!(space) }
-      search_space
-    end
-
-    #
-    # @abstract
     #
-    # This method is responsible for configuring the available gene types
-    # of evolvable instances. In effect, it provides the
-    # blueprint for constructing a hyperdimensional genetic space that's capable
-    # of being used and searched by evolvable objects.
+    # @readme
+    #   The `.gene` macro defines traits that can mutate and evolve over time.
+    #   Syntactically similar to ActiveRecord-style macros, it sets up the genetic structure of your model.
     #
-    # Override this method with a search space config for initializing
-    # SearchSpace objects. The config can be a hash, array of arrays,
-    # or single array when there's only one type of gene.
+    #   Key features:
+    #   - Fixed or variable gene counts
+    #   - Automatic accessor methods
+    #   - Optional clustering for related genes
     #
-    # The below example definitions could conceivably be used to generate evolvable music.
+    # @example Basic gene definition
+    #   class Melody
+    #     include Evolvable
     #
-    # @todo
-    #   Define gene config attributes - name, type, count
+    #     gene :notes, type: NoteGene, count: 4..16 # Can have 4-16 notes
+    #     gene :instrument, type: InstrumentGene, count: 1
     #
-    # @example Hash config
-    #   def search_space
-    #     { instrument: { type: InstrumentGene, count: 1..4 },
-    #       notes: { type: NoteGene, count: 16 } }
-    #   end
-    # @example Array of arrays config
-    #   # With explicit gene names
-    #   def search_space
-    #     [[:instrument, InstrumentGene, 1..4],
-    #      [:notes, NoteGene, 16]]
+    #     def play
+    #       instrument.play(notes)
+    #     end
     #   end
     #
-    #   # Without explicit gene names
-    #   def search_space
-    #     [[SynthGene, 0..4], [RhythmGene, 0..8]]
-    #   end
-    # @example Array config
-    #   # Available when when just one type of gene
-    #   def search_space
-    #     [NoteGene, 1..100]
-    #   end
+    # @param name [Symbol] The name of the gene
+    # @param type [String, Class] The gene type or class name
+    # @param count [Integer, Range] Number or range of gene instances
+    # @param cluster [Symbol, nil] Optional cluster name for grouping related genes
     #
-    #   # With explicit gene type name.
-    #   def search_space
-    #     ['notes', 'NoteGene', 1..100]
+    def gene(name, type:, count: 1, cluster: nil)
+      raise Error, "Gene name '#{name}' is already defined" if @gene_config.key?(name)
+
+      @gene_config[name] = { type: type, count: count }
+
+      if (count.is_a?(Range) ? count.last : count) > 1
+        define_method(name) { find_genes(name) }
+      else
+        define_method(name) { find_gene(name) }
+      end
+
+      if cluster
+        raise Error, "Cluster name '#{cluster}' conflicts with an existing gene name" if @gene_config.key?(cluster)
+
+        if @cluster_config[cluster]
+          @cluster_config[cluster] << name
+        else
+          @cluster_config[cluster] = [name]
+          define_method(cluster) { find_gene_cluster(cluster) }
+        end
+      end
+    end
+
+    #
+    # @readme
+    #   The `.cluster` macro applies a pre-defined group of related genes.
+    #
+    #   Clusters promote code organization through:
+    #     - Modularity: Define related genes once, reuse them
+    #     - Organization: Group genes by function
+    #     - Maintenance: Update in one place
+    #     - Accessibility: Access via a single accessor
+    #
+    # @example UI Component with Styling Cluster
+    #   # Define a gene cluster for UI styling properties
+    #   class ColorSchemeCluster
+    #     include Evolvable::GeneCluster
+    #
+    #     gene :background_color, type: 'ColorGene', count: 1
+    #     gene :text_color, type: 'ColorGene', count: 1
+    #     gene :accent_color, type: 'ColorGene', count: 0..1
     #   end
     #
-    # @return [Hash, Array]
+    #   # Use the cluster in an evolvable UI component
+    #   class Button
+    #     include Evolvable
     #
-    # @see https://github.com/mattruzicka/evolvable#search_space
+    #     cluster :colors, type: ColorSchemeCluster
+    #     gene :padding, type: PaddingGene, count: 1
     #
-    def search_space
-      {}
+    #     def render
+    #       puts "Button with #{colors.count} colors"
+    #       puts "Background: #{colors.background_color.hex_code}"
+    #     end
+    #   end
+    #
+    # @param cluster_name [Symbol] The name for accessing the cluster
+    # @param type [Class, String] The class that defines the cluster
+    # @param opts [Hash] Optional arguments passed to the cluster initializer
+    #
+    def cluster(cluster_name, type:, **opts)
+      recipe = type.is_a?(String) ? Object.const_get(type) : type
+      unless recipe.respond_to?(:apply_cluster)
+        raise ArgumentError, "#{recipe} cannot apply a gene cluster"
+      end
+
+      recipe.apply_cluster(self, cluster_name, **opts)
+
+      define_method(cluster_name) { find_gene_cluster(cluster_name) }
     end
 
+    attr_reader :gene_config, :cluster_config
+
     #
-    # @abstract Override this method to define multiple search spaces
-    #
-    # @return [Array]
+    # Creates a new gene space for this evolvable class.
+    # Used internally when initializing populations.
     #
-    # @see https://github.com/mattruzicka/evolvable#search_space
+    # @return [Evolvable::GeneSpace] A new gene space
     #
-    def search_spaces
-      []
+    def new_gene_space
+      GeneSpace.build(@gene_config, self)
     end
 
-    # @deprecated
-    #   Will be removed in version 2.0.
-    #   Use {#search_space} instead.
-    def gene_space
-      {}
+    #
+    # Ensures that subclasses inherit the gene and cluster configuration.
+    #
+    # @param subclass [Class] The subclass that is inheriting from this class
+    # @return [void]
+    #
+    def inherited(subclass)
+      super
+      subclass.instance_variable_set(:@gene_config, @gene_config.dup)
+      subclass.instance_variable_set(:@cluster_config, @cluster_config.dup)
     end
 
-
     #
     # @readme
-    #   Runs before evaluation.
+    #   Called before evaluation.
     #
     def before_evaluation(population); end
 
@@ -193,49 +297,106 @@ module Evolvable
     def after_evolution(population); end
   end
 
-  # Runs an evolvable is initialized. Ueful for implementing custom initialization logic.
-  def after_initialize; end
+  def after_initialize_evolvable; end
+
+  attr_accessor :fitness
+
+  def find_gene(...)
+    @genome&.find_gene(...)
+  end
+
+  def find_genes(...)
+    @genome&.find_genes(...) || []
+  end
+
+  attr_reader :population,
+              :genome,
+              :generation_index
 
+  def genes
+    @genome&.genes || []
+  end
+
+  #
+  # Makes this object evolvable by setting up its population, genome, and generation index.
+  # This is called internally by the class method `new_evolvable`.
   #
-  # @!method value
-  #   Implementing this method is required for evaluation and selection.
+  # @param population [Evolvable::Population, nil] The population this evolvable belongs to
+  # @param genome [Evolvable::Genome, nil] The genome to initialize with
+  # @param generation_index [Integer, nil] The generation index
+  # @return [self] This evolvable object
   #
-  attr_accessor :id,
-                :population,
-                :genome,
-                :generation_index,
-                :value
+  def make_evolvable(population: nil, genome: nil, generation_index: nil)
+    self.population = population
+    @genome = genome
+    self.generation_index = generation_index
+    self
+  end
+
+  def population=(val)
+    @population = val
+    genes.each { |gene| gene.evolvable = self if gene.respond_to?(:evolvable=) }
+  end
 
+  def generation_index=(val)
+    @generation_index = val
+  end
+
+  #
+  # Finds an array of genes that belong to the specified cluster.
+  # This is used internally when accessing gene clusters.
   #
-  # @deprecated
-  #   Will be removed in version 2.0.
-  #   Use {#generation_index} instead.
+  # @param cluster [Symbol] The cluster name
+  # @return [Array<Evolvable::Gene>] The genes belonging to the cluster
   #
-  def population_index
-    generation_index
+  def find_gene_cluster(cluster)
+    find_genes(*self.class.cluster_config[cluster])
   end
 
   #
-  # @!method find_gene
-  #   @see Genome#find_gene
-  # @!method find_genes
-  #   @see Genome#find_genes
-  # @!method find_genes_count
-  #   @see Genome#find_genes_count
-  # @!method genes
-  #   @see Genome#genes
+  # Dumps the genome to a serialized format.
+  # Useful for saving the state of an evolvable.
+  #
+  # @param serializer [Evolvable::Serializer] The serializer to use
+  # @return [String] The serialized genome
   #
-  def_delegators :genome,
-                 :find_gene,
-                 :find_genes,
-                 :find_genes_count,
-                 :genes
-
   def dump_genome(serializer: Serializer)
     @genome.dump(serializer: serializer)
   end
 
+  #
+  # Loads a genome from serialized data.
+  # Useful for restoring the state of an evolvable.
+  #
+  # @param data [String] The serialized genome data
+  # @param serializer [Evolvable::Serializer] The serializer to use
+  # @return [Evolvable::Genome] The loaded genome
+  #
   def load_genome(data, serializer: Serializer)
     @genome = Genome.load(data, serializer: serializer)
   end
+
+  #
+  # Loads a genome from serialized data and merges it with the current genome.
+  # Useful for combining genomes from different sources.
+  #
+  # @param data [String] The serialized genome data
+  # @param serializer [Evolvable::Serializer] The serializer to use
+  # @return [Evolvable::Genome] The merged genome
+  #
+  def load_and_merge_genome!(data, serializer: Serializer)
+    genome = Genome.load(data, serializer: serializer)
+    merge_genome!(genome)
+  end
+
+  #
+  # Merges another genome into this evolvable's genome.
+  # Useful for combining genetic traits from different evolvables.
+  #
+  # @param other_genome [Evolvable::Genome] The genome to merge
+  # @return [Evolvable::Genome] The merged genome
+  #
+  def merge_genome!(other_genome)
+    @genome.merge!(other_genome)
+  end
 end