evolvable 1.2.0 → 2.0.0

data/lib/evolvable/gene_space.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Evolvable
+  #
+  # The gene space defines the structure of an evolvable's genome.
+  # It acts as a blueprint that describes what kinds of genes each
+  # evolvable instance should have—and how many.
+  #
+  # At runtime, Evolvable::GeneSpace is responsible for interpreting this blueprint,
+  # constructing genomes, and managing gene configurations. You typically won’t need to
+  # interact with GeneSpace directly.
+  #
+  # @see Evolvable::Gene
+  # @see Evolvable::GeneCluster
+  # @see Evolvable::GeneCombination
+  #
+  class GeneSpace
+    class << self
+      def build(config, evolvable_class = nil)
+        if config.is_a?(GeneSpace)
+          config.evolvable_class = evolvable_class if evolvable_class
+          config
+        else
+          new(config: config, evolvable_class: evolvable_class)
+        end
+      end
+    end
+
+    def initialize(config: {}, evolvable_class: nil)
+      @evolvable_class = evolvable_class
+      @config = normalize_config(config)
+    end
+
+    attr_accessor :evolvable_class, :config
+
+    def new_genome
+      Genome.new(config: new_genome_config)
+    end
+
+    def merge_gene_space(val)
+      val = val.config if val.is_a?(self.class)
+      @config.merge normalize_config(val)
+    end
+
+    def merge_gene_space!(val)
+      val = val.config if val.is_a?(self.class)
+      @config.merge! normalize_config(val)
+    end
+
+    private
+
+    def normalize_config(config)
+      normalize_hash_config(config)
+    end
+
+    def normalize_hash_config(config)
+      config.each do |gene_key, gene_config|
+        next unless gene_config[:type]
+
+        gene_class = lookup_gene_class(gene_config[:type])
+        gene_class.key = gene_key
+        gene_config[:class] = gene_class
+      end
+    end
+
+    def lookup_gene_class(class_name)
+      return class_name if class_name.is_a?(Class)
+
+      (@evolvable_class || Object).const_get(class_name)
+    end
+
+    def new_genome_config
+      genome_config = {}
+      config.each do |gene_key, gene_config|
+        genome_config[gene_key] = new_gene_config(gene_config)
+      end
+      genome_config
+    end
+
+    def new_gene_config(gene_config)
+      count_gene = init_count_gene(gene_config)
+      gene_class = gene_config[:class]
+      genes = Array.new(count_gene.count) { gene_class.new }
+      { count_gene: count_gene, genes: genes }
+    end
+
+    def init_count_gene(gene_config)
+      min = gene_config[:min_count]
+      max = gene_config[:max_count]
+      return init_min_max_count_gene(min, max) if min || max
+
+      count = gene_config[:count] || 1
+      case count
+      when Numeric
+        RigidCountGene.new(count)
+      when Range
+        CountGene.new(range: count)
+      when String
+        Object.const_get(gene_config[:count]).new
+      when Class
+        gene_config[:count].new
+      end
+    end
+
+    def init_min_max_count_gene(min, max)
+      min ||= 1
+      max ||= min * 10
+      CountGene.new(range: min..max)
+    end
+  end
+end

data/lib/evolvable/genome.rb

@@ -2,8 +2,22 @@
 
 module Evolvable
   #
-  # @readme
-  #   TODO...
+  # The Genome class represents the fully instantiated genetic blueprint of an evolvable instance.
+  # It stores all gene data in a structured, accessible form and provides methods to inspect,
+  # manipulate, and serialize that genetic information.
+  #
+  # A genome consists of:
+  # - A hash of gene configurations organized by key
+  # - Count genes that determine how many instances of each gene type are present
+  # - The actual gene instances used by the evolvable
+  #
+  # The genome acts as the bridge between the gene space (definition) and the
+  # evolvable instance (implementation), enabling flexible gene access and
+  # supporting dynamic mutation or crossover behavior.
+  #
+  # @see Evolvable::GeneSpace
+  # @see Evolvable::GeneCombination
+  # @see Evolvable::Gene
   #
   class Genome
     extend Forwardable
@@ -18,8 +32,15 @@ module Evolvable
 
     attr_reader :config
 
+    alias to_h config
+
     #
-    # Returns the first gene with the given key. In the Melody example above, the instrument gene has the key `:instrument` so we might write something like: `instrument_gene = melody.find_gene(instrument)`
+    # Returns the first gene with the given key. In the Melody example above, the instrument
+    # gene has the key `:instrument` so we might write something like:
+    #
+    # ```ruby
+    # instrument_gene = melody.find_gene(instrument)
+    # ```
     #
     # @param [<Type>] key <description>
     #
@@ -30,7 +51,10 @@ module Evolvable
     end
 
     #
-    # Returns an array of genes that have the given key. Gene keys are defined in the [EvolvableClass.search_space](#evolvableclasssearch_space) method. In the Melody example above, the key for the note genes would be `:notes`. The following would return an array of them: `note_genes = melody.find_genes(:notes)`
+    # Returns an array of genes that have the given key. Gene keys are defined using the
+    # [EvolvableClass.gene](https://mattruzicka.github.io/evolvable/Evolvable/ClassMethods#gene-instance_method)
+    # macro method. In the Melody example above, the key for the note genes would be `:notes`.
+    # The following would return an array of them: `note_genes = melody.find_genes(:notes)`
     #
     # @param [<Type>] *keys <description>
     #
@@ -75,6 +99,10 @@ module Evolvable
       @config.flat_map { |_gene_key, gene_config| gene_config[:genes] }
     end
 
+    def merge!(other_genome)
+      @config.merge!(other_genome.config)
+    end
+
     def inspect
       self.class.name
     end

data/lib/evolvable/goal.rb

@@ -1,36 +1,31 @@
 # frozen_string_literal: true
 
 module Evolvable
-
-  #
-  # The goal for a population can be specified via assignment - `population.goal = Evolvable::Goal::Equalize.new` - or by passing an evaluation object when [initializing a population](#evolvablepopulationnew).
   #
-  # You can intialize the `Evolvable::Evaluation` object with any goal object like this:
+  # @see Evolvable::Evaluation
   #
-  # You can implement custom goal object like so:
+  # @readme
+  #   **Custom Goals**
   #
-  # @example
-  #   goal_object = SomeGoal.new(value: 100)
-  #   Evolvable::Evaluation.new(goal_object)
+  #   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
   #
-  # or more succinctly like this:
+  # @example Example goal implementation that prioritizes evolvables with fitness values within a specific range
+  #   class YourRangeGoal < Evolvable::Goal
+  #     def value
+  #       @value ||= 0..100
+  #      end
   #
-  # @example
-  #   Evolvable::Evaluation.new(:maximize) # Uses default goal value of   Float::INFINITY
-  #   Evolvable::Evaluation.new(maximize: 50) # Sets goal value to 50
-  #   Evolvable::Evaluation.new(:minimize) # Uses default goal value of   -Float::INFINITY
-  #   Evolvable::Evaluation.new(minimize: 100) # Sets goal value to 100
-  #   Evolvable::Evaluation.new(:equalize) # Uses default goal value of 0
-  #   Evolvable::Evaluation.new(equalize: 1000) # Sets goal value to 1000
+  #     def evaluate(evolvable)
+  #       return 1 if value.include?(evolvable.fitness)
   #
-  # @example
-  #   class CustomGoal < Evolvable::Goal
-  #     def evaluate(instance)
-  #       # Required by Evolvable::Evaluation in order to sort instances in preparation for selection.
+  #       min, max = value.minmax
+  #       -[(min - evolvable.fitness).abs, (max - evolvable.fitness).abs].min
   #     end
   #
-  #     def met?(instance)
-  #       # Used by Evolvable::Population#evolve to stop evolving when the goal value has been reached.
+  #     def met?(evolvable)
+  #       value.include?(evolvable.fitness)
   #     end
   #   end
   #
@@ -42,11 +37,11 @@ module Evolvable
     attr_accessor :value
 
     def evaluate(_evolvable)
-      raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
+      raise Error, "Undefined method: #{self.class.name}##{__method__}"
     end
 
     def met?(_evolvable)
-      raise Errors::UndefinedMethod, "#{self.class.name}##{__method__}"
+      raise Error, "Undefined method: #{self.class.name}##{__method__}"
     end
   end
 end

data/lib/evolvable/maximize_goal.rb

@@ -13,18 +13,11 @@ module Evolvable
     end
 
     def evaluate(evolvable)
-      evolvable.value
+      evolvable.fitness
     end
 
     def met?(evolvable)
-      evolvable.value >= value
+      evolvable.fitness >= value
     end
   end
-
-  #
-  # @deprecated
-  #   Will be removed in 2.0.
-  #   Use {MaximizeGoal} instead
-  #
-  class Goal::Maximize < MaximizeGoal; end
 end

data/lib/evolvable/minimize_goal.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Evolvable
+  #
   # Prioritizes instances with lesser values.
   #
   # The default goal value is `-Float::INFINITY`, but it can be reassigned
@@ -12,18 +13,11 @@ module Evolvable
     end
 
     def evaluate(evolvable)
-      -evolvable.value
+      -evolvable.fitness
     end
 
     def met?(evolvable)
-      evolvable.value <= value
+      evolvable.fitness <= value
     end
   end
-
-  #
-  # @deprecated
-  #   Will be removed in 2.0.
-  #   Use {MinimizeGoal} instead
-  #
-  class Goal::Minimize < MinimizeGoal; end
 end

data/lib/evolvable/mutation.rb

@@ -3,70 +3,101 @@
 module Evolvable
   #
   # @readme
-  #   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 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 frequency is configurable using the `probability` and `rate`
-  #   parameters.
+  #   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)
   #
-  # @example
-  #   # Show how to initialize/assign population with a specific mutation object
+  #   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
+  #   ```
   #
   class Mutation
     extend Forwardable
 
+    #
+    # The default probability of mutation (3%).
+    # This is used when no probability is specified.
+    #
     DEFAULT_PROBABILITY = 0.03
 
     #
     # Initializes a new mutation object.
     #
-    # Keyword arguments:
-    #
-    # #### probability
-    # The probability that a particular instance undergoes a mutation.
-    # By default, the probability is 0.03 which translates to 3%.
-    # If initialized with a `rate`, the probability will be 1 which
-    # means all genes _can_ undergo mutation, but actual gene mutations
-    # will be subject to the given mutation rate.
-    # #### rate
-    # the rate at which individual genes mutate. The default rate is 0 which,
-    # when combined with a non-zero `probability` (the default), means that
-    # one gene for each instance that undergoes mutation will change.
-    # If a rate is given, but no `probability` is given, then the `probability`
-    # will bet set to 1 which always defers to the mutation rate.
-    #
-    # To summarize, the `probability` represents the chance of mutation on
-    # the instance level and the `rate` represents the chance on the gene level.
-    # The `probability` and `rate` can be any number from 0 to 1. When the
-    # `probability` is 0, no mutation will ever happen. When the `probability`
-    # is not 0 but the rate is 0, then any instance that undergoes mutation
-    # will only receive one mutant gene. If the rate is not 0, then if an
-    # instance has been chosen to undergo mutation, each of its genes will
-    # mutate with a probability as defined by the `rate`.
-    #
-    # @example Example Initializations:
-    #   Evolvable::Mutation.new # Approximately #{DEFAULT_PROBABILITY} of instances will receive one mutant gene
-    #   Evolvable::Mutation.new(probability: 0.5) # Approximately 50% of instances will receive one mutant gene
-    #   Evolvable::Mutation.new(rate: 0.03) # Approximately  3% of all genes in the population will mutate.
-    #   Evolvable::Mutation.new(probability: 0.3, rate: 0.03) # Approximately 30% of instances will have approximately 3% of their genes mutated.
-    #
-    # Custom mutation objects must implement the `#call` method which accepts the population as the first object.
+    # @example Basic initialization patterns
+    #   # Default: 3% of instances get one mutated gene
+    #   Evolvable::Mutation.new
+    #
+    #   # 50% of instances get one mutated gene
+    #   Evolvable::Mutation.new(probability: 0.5)
+    #
+    #   # All instances are considered, with 3% of genes mutating in each
+    #   Evolvable::Mutation.new(rate: 0.03)
+    #
+    #   # 30% of instances have 3% of their genes mutated
+    #   Evolvable::Mutation.new(probability: 0.3, rate: 0.03)
+    #
+    # When rate is specified but probability isn't, probability defaults to 1.0.
+    # When rate is 0 or not specified, only one gene is mutated per affected instance.
+    #
+    # @param probability [Float, nil] Chance of an instance being mutated (0.0-1.0)
+    # @param rate [Float, nil] Chance of each gene mutating when an instance is selected (0.0-1.0)
     #
     def initialize(probability: nil, rate: nil)
       @probability = probability || (rate ? 1 : DEFAULT_PROBABILITY)
       @rate = rate
     end
 
-    attr_accessor :probability,
-                  :rate
+    #
+    # The probability that an evolvable instance will undergo mutation.
+    # Value between 0.0 (never) and 1.0 (always).
+    #
+    # @return [Float] The mutation probability
+    #
+    attr_accessor :probability
 
+    #
+    # The rate at which genes mutate within an instance.
+    # Value between 0.0 (no genes mutate) and 1.0 (all genes likely to mutate).
+    # When nil, exactly one random gene is mutated per instance.
+    #
+    # @return [Float, nil] The mutation rate
+    #
+    attr_accessor :rate
+
+    #
+    # Applies mutations to the population's evolvables based on the
+    # configured probability and rate.
+    #
+    # @param population [Evolvable::Population] The population to mutate
+    # @return [Evolvable::Population] The mutated population
+    #
     def call(population)
       mutate_evolvables(population.evolvables) unless probability.zero?
       population
     end
 
+    #
+    # Mutates a collection of evolvable instances based on the mutation
+    # probability and rate.
+    #
+    # @param evolvables [Array<Evolvable>] The collection of evolvable instances to potentially mutate
+    # @return [Array<Evolvable>] The potentially mutated evolvables
+    #
     def mutate_evolvables(evolvables)
       evolvables.each do |evolvable|
         next unless rand <= probability
@@ -77,6 +108,14 @@ module Evolvable
 
     private
 
+    #
+    # Mutates genes in the given collection based on the mutation rate.
+    # If a rate is set, each gene has a chance to mutate according to the rate.
+    # If no rate is set, a single random gene is mutated.
+    #
+    # @param genes [Array<Evolvable::Gene>] The collection of genes to potentially mutate
+    # @return [void]
+    #
     def mutate_genes(genes)
       genes_count = genes.count
       return if genes_count.zero?
@@ -86,6 +125,13 @@ module Evolvable
       genes_count.times { |index| mutate_gene_by_index(genes, index) if rand <= rate }
     end
 
+    #
+    # Replaces a gene at the specified index with a new instance of the same gene class.
+    #
+    # @param genes [Array<Evolvable::Gene>] The collection of genes
+    # @param gene_index [Integer] The index of the gene to mutate
+    # @return [void]
+    #
     def mutate_gene_by_index(genes, gene_index)
       genes[gene_index] = genes[gene_index].class.new
     end

data/lib/evolvable/point_crossover.rb

@@ -2,10 +2,30 @@
 
 module Evolvable
   #
-  # Supports single and multi-point crossover. The default is single-point
-  # crossover via a `points_count` of 1 which can be changed on an existing population
-  # (`population.crossover.points_count = 5`) or during initialization
-  # (`Evolvable::PointCrossover.new(5)`)
+  # @readme
+  #   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.
+  #
+  #   - **Single-point crossover (default):** Swaps all genes after a randomly chosen position.
+  #   - **Multi-point crossover:** Alternates segments between multiple randomly chosen points.
+  #
+  #   Best for:
+  #   - Preserving beneficial gene blocks
+  #   - Problems where related traits are located near each other
+  #
+  #   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
+  #   population.combination = Evolvable::PointCrossover.new(points_count: 3)
+  #   ```
   #
   class PointCrossover
     def initialize(points_count: 1)