evolvable 1.2.0 → 2.0.0

data/lib/evolvable/evaluation.rb

@@ -3,67 +3,166 @@
 module Evolvable
   #
   # @readme
-  #   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".
+  #   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.
   #
-  #   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.
+  #   **How It Works**
   #
-  # @example
-  #   # TODO: Show how to add/change population's evaluation object
+  #   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.
   #
-  #   # The goal value can also be assigned via as argument to `Evolvable::Population#evolve`
-  #   population.evolve(goal_value: 1000)
+  #   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
+  #   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
+  #   ```
+  #
+  #   - Minimize (lower is better)
+  #
+  #   ```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
+  #
+  #   # Same as above
+  #   ErrorModel.new_population(evaluation: { minimize: 0.01 }).evolve_to_goal
+  #   ```
+  #
+  #   - Equalize (closer to target is better)
+  #
+  #   ```ruby
+  #   targets = TargetMatcher.new_population(evaluation: :equalize) # Defaults to 0
+  #   targets.evolve_to_goal(42)  # Evolve until we match the target value
+  #
+  #   # Same as above
+  #   TargetMatcher.new_population(evaluation: { equalize: 42 }).evolve_to_goal
+  #   ```
+  #
+  # @see Evolvable::Population
+  # @see Evolvable::Selection
   #
   class Evaluation
-    GOALS = { maximize: Evolvable::Goal::Maximize.new,
-              minimize: Evolvable::Goal::Minimize.new,
-              equalize: Evolvable::Goal::Equalize.new }.freeze
+    #
+    # Mapping of goal type symbols to their corresponding goal objects.
+    # See the readme section above for details on each goal type.
+    #
+    # @return [Hash<Symbol, Evolvable::Goal>] Available goal objects by type
+    #
+    GOALS = { maximize: Evolvable::MaximizeGoal.new,
+              minimize: Evolvable::MinimizeGoal.new,
+              equalize: Evolvable::EqualizeGoal.new }.freeze
 
+    #
+    # The default goal type used if none is specified.
+    # @return [Symbol] The default goal type (maximize)
+    #
     DEFAULT_GOAL_TYPE = :maximize
 
+    #
+    # Initializes a new evaluation object.
+    #
+    # @param goal [Symbol, Hash, Evolvable::Goal] The goal type (:maximize, :minimize, :equalize),
+    #   a hash specifying goal type and value, or a custom goal object
+    #
     def initialize(goal = DEFAULT_GOAL_TYPE)
       @goal = normalize_goal(goal)
     end
 
+    #
+    # The goal object used for evaluation.
+    # @return [Evolvable::Goal] The current goal object
+    #
     attr_accessor :goal
 
+    #
+    # Evaluates and sorts all evolvables in the population according to the goal.
+    #
+    # @param population [Evolvable::Population] The population to evaluate
+    # @return [Array<Evolvable>] The sorted evolvables
+    #
     def call(population)
       population.evolvables.sort_by! { |evolvable| goal.evaluate(evolvable) }
     end
 
+    #
+    # Returns the best evolvable in the population according to the goal.
+    #
+    # @param population [Evolvable::Population] The population to evaluate
+    # @return [Evolvable] The best evolvable based on the current goal
+    #
     def best_evolvable(population)
       population.evolvables.max_by { |evolvable| goal.evaluate(evolvable) }
     end
 
+    #
+    # Checks if the goal has been met by any evolvable in the population.
+    #
+    # @param population [Evolvable::Population] The population to check
+    # @return [Boolean] True if the goal has been met, false otherwise
+    #
     def met_goal?(population)
       goal.met?(population.evolvables.last)
     end
 
     private
 
+    #
+    # Normalizes the goal parameter into a proper goal object.
+    #
+    # @param goal_arg [Symbol, Hash, Evolvable::Goal] The goal parameter
+    # @return [Evolvable::Goal] A normalized goal object
+    #
     def normalize_goal(goal_arg)
       case goal_arg
       when Symbol
         goal_from_symbol(goal_arg)
       when Hash
         goal_from_hash(goal_arg)
+      when String
+        goal_from_symbol(goal_arg.to_sym)
       else
         goal_arg || default_goal
       end
     end
 
+    #
+    # Returns the default goal object.
+    #
+    # @return [Evolvable::Goal] The default goal object
+    #
     def default_goal
       GOALS[DEFAULT_GOAL_TYPE]
     end
 
+    #
+    # Creates a goal object from a symbol.
+    #
+    # @param goal_arg [Symbol] The goal type symbol
+    # @return [Evolvable::Goal] The corresponding goal object
+    #
     def goal_from_symbol(goal_arg)
       GOALS[goal_arg]
     end
 
+    #
+    # Creates a goal object from a hash specifying the goal type and value.
+    #
+    # @param goal_arg [Hash] A hash with a single key-value pair
+    # @return [Evolvable::Goal] The corresponding goal object with the specified value
+    #
     def goal_from_hash(goal_arg)
       goal_type, value = goal_arg.first
       goal = GOALS[goal_type]

data/lib/evolvable/evolution.rb

@@ -3,32 +3,30 @@
 module Evolvable
   #
   # @readme
-  #   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.
+  #   **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
   #
   class Evolution
     extend Forwardable
 
     #
-    #  Initializes a new evolution object.
-    #
-    # Keyword arguments:
+    # Initializes a new evolution object.
     #
-    # #### selection
-    # The default is `Selection.new`
-    # #### crossover - deprecated
-    # The default is `GeneCrossover.new`
-    # #### mutation
-    # The default is `Mutation.new`
+    # @param selection [Evolvable::Selection, Hash] The selection strategy
+    # @param combination [Evolvable::Combination, Hash] The combination strategy
+    # @param mutation [Evolvable::Mutation, Hash] The mutation strategy
     #
     def initialize(selection: Selection.new,
                    combination: GeneCombination.new,
-                   crossover: nil, # deprecated
                    mutation: Mutation.new)
       @selection = selection
-      @combination = crossover || combination
+      @combination = combination
       @mutation = mutation
     end
 
@@ -36,18 +34,43 @@ module Evolvable
                 :combination,
                 :mutation
 
+    #
+    # Sets the selection strategy.
+    #
+    # @param val [Evolvable::Selection, Hash] The new selection strategy or configuration hash
+    # @return [Evolvable::Selection] The updated selection object
+    #
     def selection=(val)
       @selection = Evolvable.new_object(@selection, val, Selection)
     end
 
+    #
+    # Sets the combination strategy.
+    #
+    # @param val [Evolvable::Combination, Hash] The new combination strategy or configuration hash
+    # @return [Evolvable::Combination] The updated combination object
+    #
     def combination=(val)
       @combination = Evolvable.new_object(@combination, val, GeneCombination)
     end
 
+    #
+    # Sets the mutation strategy.
+    #
+    # @param val [Evolvable::Mutation, Hash] The new mutation strategy or configuration hash
+    # @return [Evolvable::Mutation] The updated mutation object
+    #
     def mutation=(val)
       @mutation = Evolvable.new_object(@mutation, val, Mutation)
     end
 
+    #
+    # Executes the evolution process on the population.
+    # Applies selection, combination, and mutation in sequence.
+    #
+    # @param population [Evolvable::Population] The population to evolve
+    # @return [Evolvable::Population] The evolved population
+    #
     def call(population)
       selection.call(population)
       combination.call(population)

data/lib/evolvable/gene.rb

@@ -3,61 +3,160 @@
 module Evolvable
   #
   # @readme
-  #   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.
+  #   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.
   #
-  #   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.
+  #   **To define a gene class:**
+  #   1. Include the `Evolvable::Gene` module
+  #   2. Define how the gene's value is determined
   #
-  # @example
-  #   # This gene generates a random hexidecimal color code for use by evolvables.
+  #   ```ruby
+  #   class BehaviorGene
+  #     include Evolvable::Gene
+  #
+  #     def value
+  #       @value ||= %w[explore gather attack defend build].sample
+  #     end
+  #   end
+  #   ```
+  #
+  #   Then use it in an evolvable class:
+  #
+  #   ```ruby
+  #   class Robot
+  #     include Evolvable
+  #
+  #     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
+  #   ```
   #
-  #   require 'securerandom'
+  #   **Gene Count**
   #
-  #   class ColorGene
+  #   You can control how many copies of a gene are created using the `count:` parameter:
+  #
+  #   - `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.
+  #
+  #   Evolves melody length:
+  #
+  #   ```ruby
+  #   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 hex_code
-  #       @hex_code ||= SecureRandom.hex(3)
+  #     def self.combine(gene_a, gene_b)
+  #       new_gene = new
+  #       new_gene.value = (gene_a.value + gene_b.value) / 2
+  #       new_gene
+  #     end
+  #
+  #     attr_writer :value
+  #
+  #     def value
+  #       @value ||= rand(1..100)
   #     end
   #   end
+  #   ```
+  #
+  #   **Design Patterns**
+  #
+  #   Effective gene design typically follows these principles:
+  #
+  #   - **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
+  #
+  #   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.
+  #
+  # @see Evolvable::GeneSpace
+  # @see Evolvable::GeneCluster
+  # @see Evolvable::GeneCombination
+  # @see Evolvable::CountGene
+  # @see Evolvable::RigidCountGene
   #
-
   module Gene
+    #
+    # When included in a class, extends the class with ClassMethods.
+    # Gene classes should include this module to participate in the evolutionary process.
+    #
+    # @param base [Class] The class that includes the Gene module
+    #
     def self.included(base)
       base.extend(ClassMethods)
     end
 
+    #
+    # Class methods added to classes that include Evolvable::Gene.
+    # These methods enable gene-level behaviors like combination during evolution.
+    #
     module ClassMethods
+      #
+      # Sets the unique key for this gene type.
+      # The key is typically set automatically when using the `gene` macro.
+      #
+      # @param val [Symbol] The key to identify this gene type
+      #
       def key=(val)
         @key = val
       end
 
+      #
+      # Returns the unique key for this gene type.
+      #
+      # @return [Symbol] The key that identifies this gene type
+      #
       def key
         @key
       end
 
+      #
+      # Combines two genes to produce a new gene during the combination phase.
+      # By default, randomly picks one of the two parent genes.
+      #
+      # Override this method in your gene class to implement custom combination behavior.
+      #
+      # @param gene_a [Evolvable::Gene] The first gene to combine
+      # @param gene_b [Evolvable::Gene] The second gene to combine
+      # @return [Evolvable::Gene] A new gene resulting from the combination
+      #
       def combine(gene_a, gene_b)
         [gene_a, gene_b].sample
       end
-
-      #
-      # @deprecated
-      #   Will be removed in 2.0
-      #   Use {#combine}
-      #
-      alias crossover combine
     end
 
+    #
+    # The evolvable instance that this gene belongs to.
+    # Used for accessing other genes or evolvable properties.
+    #
+    # @return [Evolvable] The evolvable instance this gene is part of
+    #
     attr_accessor :evolvable
 
+    #
+    # Returns the unique key for this gene instance.
+    # Delegates to the class-level key.
+    #
+    # @return [Symbol] The key that identifies this gene type
+    #
     def key
       self.class.key
     end

data/lib/evolvable/gene_cluster.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # @readme
+  #   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")`
+  #
+  # @see Evolvable::Gene
+  # @see Evolvable::GeneSpace
+  #
+  module GeneCluster
+    #
+    # When included in a class, extends the class with ClassMethods and initializes
+    # the cluster configuration. This is called automatically when you include
+    # the GeneCluster module in your class.
+    #
+    # @param base [Class] The class that includes the GeneCluster module
+    # @return [void]
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@cluster_config, [])
+    end
+
+    #
+    # Class methods added to classes that include Evolvable::GeneCluster
+    #
+    module ClassMethods
+      #
+      # Defines a gene in the cluster.
+      # This is used internally by the cluster to define its component genes.
+      #
+      # @param name [Symbol] The name of the gene within the cluster
+      # @param opts [Hash] Options for the gene (type, count, etc.)
+      #
+      def gene(name, **opts)
+        @cluster_config << [name, opts]
+      end
+
+      #
+      # Applies all genes in this cluster to the given evolvable class.
+      # This is called automatically when using the `cluster` macro.
+      #
+      # @param evolvable_class [Class] The evolvable class to apply the cluster to
+      # @param cluster_name [Symbol] The name to use for the cluster in the evolvable class
+      # @param _ [Hash] Additional options (for future expansion)
+      # @return [void]
+      #
+      def apply_cluster(evolvable_class, cluster_name, **_)
+        @cluster_config.each do |name, kw|
+          evolvable_class.gene("#{cluster_name}-#{name}", **kw, cluster: cluster_name)
+        end
+      end
+
+      #
+      # Ensures that subclasses inherit the cluster configuration.
+      #
+      # @param subclass [Class] The subclass that is inheriting from this class
+      # @return [void]
+      #
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@cluster_config, @cluster_config.dup)
+      end
+    end
+  end
+end

data/lib/evolvable/gene_combination.rb

@@ -3,40 +3,60 @@
 module Evolvable
   #
   # @readme
-  #   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.
+  #   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.
   #
-  #   You may choose from a selection of combination objects or implement your own.
-  #   The default combination object is `Evolvable::GeneCombination`.
+  #   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.
   #
-  # Custom crossover objects must implement the `#call` method which accepts
-  # the population as the first object.
-  # Enables gene types to define combination behaviors.
+  #   To define custom combination logic for a gene type, implement:
   #
-  # Each gene class can implement a unique behavior for
-  # combination by overriding the following default implementation
-  # which mirrors the behavior of `Evolvable::UniformCrossover`
+  #   ```ruby
+  #   YourGeneClass.combine(parent_1_gene, parent_2_gene)
+  #   ```
   #
   class GeneCombination
+    #
+    # Performs the combination operation on the population.
+    # Creates new evolvables by combining parent genomes.
+    #
+    # @param population [Evolvable::Population] The population to perform combination on
+    # @return [Evolvable::Population] The population with new evolvables
+    #
     def call(population)
       new_evolvables(population, population.size)
       population
     end
 
+    #
+    # Creates new evolvable instances by combining parent genomes.
+    # For each new evolvable, selects parent genomes and combines them.
+    #
+    # @param population [Evolvable::Population] The population containing parent evolvables
+    # @param count [Integer] The number of new evolvables to create
+    # @return [Array<Evolvable>] The newly created evolvables
+    #
     def new_evolvables(population, count)
       parent_genome_cycle = population.new_parent_genome_cycle
       Array.new(count) do
-        genome = build_genome(parent_genome_cycle.next)
+        genome_1, genome_2 = parent_genome_cycle.next
+        genome = combine_genomes(genome_1, genome_2)
         population.new_evolvable(genome: genome)
       end
     end
 
-    private
-
-    def build_genome(genome_pair)
+    #
+    # Combines two parent genomes to create a new genome.
+    # For each gene key, combines the count genes and individual genes.
+    #
+    # @param genome_1 [Evolvable::Genome] The first parent genome
+    # @param genome_2 [Evolvable::Genome] The second parent genome
+    # @return [Evolvable::Genome] A new genome resulting from the combination
+    #
+    def combine_genomes(genome_1, genome_2)
       new_config = {}
-      genome_1, genome_2 = genome_pair.shuffle!
       genome_1.each do |gene_key, gene_config_1|
         gene_config_2 = genome_2.config[gene_key]
         count_gene = combine_count_genes(gene_config_1, gene_config_2)
@@ -46,12 +66,33 @@ module Evolvable
       Genome.new(config: new_config)
     end
 
+    private
+
+    #
+    # Combines two count genes to create a new count gene.
+    # Delegates to the count gene class's combine method.
+    #
+    # @param gene_config_1 [Hash] Configuration for the first gene group
+    # @param gene_config_2 [Hash] Configuration for the second gene group
+    # @return [Evolvable::CountGene, Evolvable::RigidCountGene] A new count gene
+    #
     def combine_count_genes(gene_config_1, gene_config_2)
       count_gene_1 = gene_config_1[:count_gene]
       count_gene_2 = gene_config_2[:count_gene]
       count_gene_1.class.combine(count_gene_1, count_gene_2)
     end
 
+    #
+    # Combines genes from two parent gene configurations.
+    # For each gene position, if both genes exist, uses the gene class's
+    # combine method to create a new gene. Otherwise, uses the existing
+    # gene or creates a new one.
+    #
+    # @param count [Integer] The number of genes to create
+    # @param gene_config_1 [Hash] Configuration for the first gene group
+    # @param gene_config_2 [Hash] Configuration for the second gene group
+    # @return [Array<Evolvable::Gene>] An array of combined genes
+    #
     def combine_genes(count, gene_config_1, gene_config_2)
       genes_1 = gene_config_1[:genes]
       genes_2 = gene_config_2[:genes]