petri_dish_lab 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2b6825c1a801fb7bf1b0055bf7ad08eeafb11b07ba28738e119649e78da901e5
+  data.tar.gz: 8b4ec7f7f3aecf5dfe436b17e4fe1fc47cdbce4414cbfd0762a91f229787f7d6
+SHA512:
+  metadata.gz: f606acc337b9e3854a4d5f5fd97f322ab92819352d42ae5ad96904600451a31de000649cfc3db816fb111fa0146a3a0eeec58ebd8cc22e796450f048fbf9f08c
+  data.tar.gz: ce04833309b18e813f8ded79dc9d6d73af440754dc802045e4a4ed892d0c2c83843952491cf6474690f4a389c51998b6abab4a9705acd9fd71839c296e300824

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,2 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+## [Unreleased]
+### Added
+### Changed
+### Fixed
+### Removed
+
+## [0.1.1] - 2023-07-26
+
+### Added
+
+- Added `Configuration` class for customizing the parameters of the evolutionary algorithm.
+- Added `Member` class to represent an individual in the population.
+- Added `Metadata` class to keep track of the evolution process.
+- Added `World` class to run the evolutionary algorithm.
+- Initial implementation of evolutionary algorithm operations, including selection, crossover, and mutation.
+- Added fitness function support for evaluating the quality of individuals in the population.
+- Added callback functions for various events in the evolution process, including when a new highest fitness is found, when the maximum number of generations is reached, and when the end condition is met.
+- Included an example of using the library to solve a simple genetic algorithm problem (lazy dog example).
+- Included an example of using the library to solve the Traveling Salesperson Problem (salesperson example).

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+Hey there, it's Thomas! I'm really keen on keeping this project fun and inclusive. Everyone's welcome, no matter who you are or where you come from.
+
+## Let's Have Fun
+
+* Be kind and empathetic.
+* Respect other's opinions and viewpoints.
+* Learn from your mistakes, and most importantly, from each other.
+* Focus on what's best for everyone.
+
+## Not Fun
+
+* No inappropriate language or imagery.
+* No personal attacks or offensive behavior.
+* No harassment, public or private.
+* No publishing others' private info without permission.
+
+## If Things Are Not Fun
+
+If you see or experience something that's not fun, drop me an email at thomascountz@gmail.com. I'll take it seriously, and handle it respectfully and fairly.
+
+Depending on what happened, I might send a warning, or for repeated or serious incidents, issue a temporary or even permanent ban from the project.
+
+Let's keep it fun, respectful, and awesome!
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html), version 2.0, and inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Thomas Countz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,233 @@
+# Petri Dish - A Ruby library for Evolutionary Algorithms
+
+> **Note**
+> `gem install petri_dish_lab` to install the gem, _not_ `petri_dish`.
+
+## Introduction
+
+Welcome to Petri Dish, a Ruby library designed to provide an easy-to-use interface for implementing evolutionary algorithms. Petri Dish is a flexible library that allows you to configure and run your own evolutionary algorithms by simply providing your own genetic material, fitness function, and other parameters. This library is perfect for both beginners who are just starting to learn about evolutionary algorithms, and experts who want to experiment with different configurations and parameters.
+
+## Overview of Evolutionary Algorithms
+
+Evolutionary algorithms are a class of optimization algorithms that are inspired by the process of natural evolution. They work by maintaining a population of candidate solutions for the problem at hand and iteratively improving that population by applying operations that mimic natural evolution, such as mutation, crossover (or recombination), and selection.
+
+The basic steps of an evolutionary algorithm are as follows:
+
+1. **Initialization**: Begin with a population of randomly generated individuals.
+2. **Evaluation**: Compute the fitness of each individual in the population.
+3. **Selection**: Select individuals for reproduction based on their fitness.
+4. **Crossover**: Generate offspring by combining the traits of selected individuals.
+5. **Mutation**: Randomly alter some traits of the offspring.
+6. **Replacement**: Replace the current population with the offspring.
+7. **Termination**: If a termination condition is met (e.g., a solution of sufficient quality is found, or a maximum number of generations is reached), stop and return the best solution found. Otherwise, go back to step 2.
+
+## Key Concepts of this Library
+
+Petri Dish is built around a few key classes: `Configuration`, `Member`, `Metadata`, and `World`. 
+
+- `Configuration`: This class provides a way to configure the behavior of the evolutionary algorithm. It exposes various parameters like `population_size`, `mutation_rate`, `genetic_material`, and several callback functions that can be used to customize the evolution process. 
+
+- `Member`: This class represents an individual in the population. It has a set of genes and a fitness value, which is computed by a fitness function provided in the configuration.
+
+- `Metadata`: This class keeps track of the evolution process, like the number of generations that have passed and the highest fitness value found so far.
+
+- `World`: This class is responsible for running the evolutionary algorithm. It takes a configuration and a population of members as input, and runs the evolution process until a termination condition is met.
+
+## Configuration
+
+The `Configuration` class in Petri Dish allows you to customize various aspects of the evolutionary algorithm. Here are the parameters you can set:
+
+Here is the reformatted list as a markdown table:
+
+| Parameter | Description | Type |
+|---|---|---|
+| `logger` | An object that responds to `:info` for logging purposes | `Logger` |
+| `population_size` | The number of individuals in the population | `Integer` |
+| `mutation_rate` | The chance that a gene will change during mutation (between 0 and 1, inclusive) | `Float` |
+| `genetic_material` | An array of possible gene values | `Array[untyped]` |
+| `elitism_rate` | The proportion of the population preserved through elitism (between 0 and 1, inclusive) | `Float` |
+| `target_genes` | The ideal set of genes for the problem at hand | `Array[untyped]` |
+| `max_generations` | The maximum number of generations to run the evolution for | `Integer` |
+| `parents_selection_function` | A function used to select parents for crossover | `Proc[Array[Member], Array[Member]]` |
+| `crossover_function` | A function used to perform crossover between two parents | `Proc[Array[Member], Member]` |
+| `mutation_function` | A function used to mutate the genes of an individual | `Proc[Member, Member]` |
+| `fitness_function` | A function used to calculate the fitness of an individual | `Proc[Member, Numeric]` |
+| `highest_fitness_callback` | A callback function invoked when a new highest fitness is found | `Proc[Member, void]` |
+| `max_generation_reached_callback` | A callback function invoked when the maximum number of generations is reached | `Proc[void, void]` |
+| `end_condition_function` | A function that determines whether the evolution process should stop premature of `max_generations` | `Proc[Member, bool]` |
+| `next_generation_callback` | A callback function invoked at the start of each new generation | `Proc[void, void]` |
+| `end_condition_reached_callback` | A callback function invoked when the end condition is met. It is called with the `Member` which triggered the `end_condition_function` | `Proc[Member, void]` |
+
+You can create a new `Configuration` object by calling `Configuration.configure` and providing a block:
+
+```ruby
+configuration = PetriDish::Configuration.configure do |config|
+  # set your configuration parameters here
+end
+```
+
+In the block, you can set the parameters of the configuration to customize the behavior of your evolutionary algorithm.
+
+## Member
+
+The `Member` class in Petri Dish represents an individual in the population. Each member has a set of genes and a fitness value, which is calculated by a fitness function provided in the configuration. Here are the parameters and methods you can interact with:
+
+- `new(genes:, fitness_function:)`: This method is used to create a new member. It takes an array of genes and a fitness function as arguments.
+
+- `genes` (`Array[untyped]`): The genetic material of the individual, represented as an array .
+
+- `fitness_function`  (`Proc[Member, Float]`): The function used to calculate the fitness of the individual. It is provided during the initialization of the member.
+
+- `fitness`: This method calls the provided fitness function. The resulting fitness value is cached after the first calculation and reused in subsequent calls. 
+
+Here's an example of how to create a new member:
+
+```ruby
+member = PetriDish::Member.new(
+  genes: ["gene1", "gene2", "gene3"],
+  fitness_function: ->(member) { # calculate fitness }
+)
+```
+
+In this example, `["gene1", "gene2", "gene3"]` is the genetic material for the member, and the lambda function is used to calculate the fitness of the member. You should replace `# calculate fitness` with the actual logic for calculating fitness based on the problem you're trying to solve.
+
+## Fitness Function
+
+A fitness function is crucial as it provides a way to evaluate how good or "fit" an individual member of the population is in solving the problem at hand. The fitness function is a measure of quality or performance, and it guides the evolutionary algorithm in the search for optimal solutions.
+
+Here are the necessary technical properties required when defining a fitness function for the Petri Dish framework:
+
+1. Callable: The fitness function should be a callable object (for example, a lambda or a `Proc`). It should respond to `#call`.
+
+2. Input: The fitness function should take a single argument, which is an instance of the `Member` class. This represents an individual member of the population whose fitness is to be evaluated.
+
+3. Output: The fitness function should return a numerical value that represents the fitness of the given member. This could be an `Integer` or a `Float`, depending on the precision required. **Higher values should signify better fitness**.
+
+4. Deterministic: Given the same `Member`, the fitness function should always return the same fitness score. This is because the fitness of a member may be evaluated multiple times during the evolutionary process, and inconsistent results could lead to unpredictable behavior.
+
+5. Non-negative: The fitness function should ideally return non-negative values. This isn't a strict requirement, but having non-negative fitness values can make the algorithm easier to understand and debug.
+
+6. Discriminative: The fitness function should be able to discriminate between different members of the population. That is, members with different genes should have different fitness scores. If many members have the same fitness score, the evolutionary algorithm will have a harder time deciding which members are better.
+
+## Install and Setup
+
+> **Warning**
+> The name of the _repo_ is `petri_dish`.
+> The name of the _module_ is `PetriDish`.
+> The name of the _gem_ is `petri_dish_lab`.
+
+You can install `petri_dish_lab` as a gem in your application. Add this line to your application's Gemfile:
+
+```ruby
+gem 'petri_dish_lab'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install petri_dish_lab
+```
+
+At the top of your Ruby file, require the `petri_dish` _module_ name:
+
+```ruby
+require "petri_dish"
+```
+
+### Setup for Development
+
+If you want to set up the `petri_dish_lab` gem for development, follow these steps:
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/thomascountz/petri_dish.git
+```
+
+2. Change into the `petri_dish` directory:
+
+```bash
+cd petri_dish
+```
+
+3. Run the setup script:
+
+```bash
+bin/setup
+```
+
+This will install the necessary dependencies for development and testing.
+
+### Using Console for Development
+
+After setting up, you can use the development console to experiment with the `petri_dish` library:
+
+```bash
+bin/console
+```
+
+This will start an interactive Ruby session (IRB) with `PetriDish` pre-loaded. You can use this console to experiment with `PetriDish`, create `PetriDish::Member` instances, run evolutionary algorithms, etc.
+
+Remember to run your tests frequently during development to ensure everything is working as expected:
+
+```bash
+bundle exec rspec
+```
+
+If you add new code, remember to add corresponding tests and ensure all tests pass before committing your changes.
+
+## Examples
+
+### Lazy Dog Example
+
+The `lazy_dog_example.rb` is an example of using the Petri Dish library to solve a simple problem: Evolving a string to match "the quick brown fox jumped over the lazy white dog". This is a classic example of using a genetic algorithm to find a solution to a problem.
+
+The genetic material in this case is the array of all lowercase letters and space. The target genes are the characters in the target string. The fitness function is defined as the cube of the sum of matches between the genes of a member and the target genes. This means that members with more matching characters will have a much higher fitness.
+
+The parents for crossover are selected using a tournament selection function which picks the best 2 out of a random sample of 20% of the population. Crossover is performed at a random midpoint in the genes.
+
+Mutation is implemented as a chance to replace a gene with a random gene from the genetic material. The mutation rate is set to 0.005, which means that on average, 0.5% of the genes in a member will mutate in each generation.
+
+The end condition for the evolutionary process is when a member with genes exactly matching the target genes is found.
+
+To run the example, simply execute the following command in your terminal:
+
+```bash
+bundle exec ruby examples/lazy_dog_example.rb
+```
+
+### Traveling Salesperson Example
+
+The `salesperson_example.rb` is an example of using the Petri Dish library to solve a more complex problem: The Traveling Salesperson Problem. In this problem, a salesperson needs to visit a number of cities, each at a different location, and return to the starting city. The goal is to find the shortest possible route that visits each city exactly once.
+
+In this example, each city is represented as a `Gene` object with `x` and `y` coordinates. The genetic material is the array of all possible `x` and `y` coordinates. The fitness function is defined as the inverse of the total distance of the route, which means that shorter routes will have higher fitness.
+
+The parents for crossover are selected using a tournament selection function which picks the best 2 out of a random sample of 20% of the population. Crossover is performed using an ordered crossover method which maintains the relative order of the genes from both parents.
+
+Mutation is implemented as a chance to swap two genes in a member. The mutation rate is set to 0.01, which means that on average, 1% of the genes in a member will mutate in each generation.
+
+The evolutionary process runs for a fixed number of generations, and the highest fitness member in each generation is saved to a CSV file.
+
+To run the example, simply execute the following command in your terminal:
+
+```bash
+bundle exec ruby examples/salesperson_example.rb
+```
+
+You can then visualize the best route using the provided `uplot` command.
+
+## Resources
+  - [Genetic Algorithms Explained By Example - Youtube](https://www.youtube.com/watch?v=uQj5UNhCPuo)
+  - [Genetic Algorithms for Autonomous Robot Navigation - Paper](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.208.9941&rep=rep1&type=pdf)
+  - [Nature of Code, Chapter 9 - The Evolution of Code - Book](https://natureofcode.com/book/chapter-9-the-evolution-of-code/)
+  - [Weighted Random Sampling in Ruby - Gist](https://gist.github.com/O-I/3e0654509dd8057b539a)
+  - [Tail Call Optimization in Ruby - Blog](https://nithinbekal.com/posts/ruby-tco/)
+  - [Neural network and genetic algorithm based global path planning in a static environment - Paper](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.583.3340&rep=rep1&type=pdf)
+  - [Traveling Salesman Problem using Genetic Algorithm - Blog](https://www.geeksforgeeks.org/traveling-salesman-problem-using-genetic-algorithm/)
+  - [A KNOWLEDGE-BASED GENETIC ALGORITHM FOR PATH PLANNING OF MOBILE ROBOTS - Thesis](https://atrium.lib.uoguelph.ca/xmlui/bitstream/handle/10214/22039/Hu_Yanrong_MSc.pdf?sequence=2)

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/examples/lazy_dog_example.rb

@@ -0,0 +1,62 @@
+# require "petri_dish" # Uncomment this line and comment/remove the line below if you're using Petri Dish as a gem
+require_relative "../lib/petri_dish"
+
+target_genes = "the quick brown fox jumped over the lazy white dog".chars
+genetic_material = ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", " "]
+
+def genes_match_target_end_condition_function(configuration)
+  ->(member) do
+    member.genes == configuration.target_genes
+  end
+end
+
+def twenty_percent_tournament_function(configuration)
+  ->(members) do
+    members.sample(configuration.population_size * 0.2).max_by(2) { |member| member.fitness }
+  end
+end
+
+def exponential_fitness_function(configuration)
+  ->(member) do
+    member.genes.zip(configuration.target_genes).map do |target_gene, member_gene|
+      (target_gene == member_gene) ? 1 : 0
+    end.sum**3
+  end
+end
+
+def random_midpoint_crossover_function(configuration)
+  ->(parents) do
+    midpoint = rand(parents[0].genes.length)
+    PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: parents[0].genes[0...midpoint] + parents[1].genes[midpoint..])
+  end
+end
+
+def random_mutation_function(configuration)
+  ->(member) do
+    mutated_genes = member.genes.map do |gene|
+      if rand < configuration.mutation_rate
+        configuration.genetic_material.sample
+      else
+        gene
+      end
+    end
+    PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: mutated_genes)
+  end
+end
+
+configuration = PetriDish::Configuration.configure do |config|
+  config.max_generations = 5000
+  config.population_size = 250
+  config.mutation_rate = 0.005
+  config.genetic_material = genetic_material
+  config.target_genes = target_genes
+  config.parents_selection_function = twenty_percent_tournament_function(config)
+  config.fitness_function = exponential_fitness_function(config)
+  config.crossover_function = random_midpoint_crossover_function(config)
+  config.mutation_function = random_mutation_function(config)
+  config.end_condition_function = genes_match_target_end_condition_function(config)
+  config.highest_fitness_callback = ->(member) { puts "Highest fitness: #{member.fitness} (#{member})" }
+end
+
+init_members = Array.new(configuration.population_size) { PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: Array.new(target_genes.size) { genetic_material.sample }) }
+PetriDish::World.run(configuration: configuration, members: init_members)

data/examples/salesperson_example.rb

@@ -0,0 +1,135 @@
+# require "petri_dish" # Uncomment this line and comment/remove the line below if you're using Petri Dish as a gem
+require_relative "../lib/petri_dish"
+require "csv"
+
+XLIMIT = 10
+YLIMIT = XLIMIT
+NUM_OF_CITIES = 10
+GENETIC_MATERIAL = (0..XLIMIT - 1).to_a
+
+def random_uniq_city_gene_generation
+  result = []
+  until result.size == NUM_OF_CITIES
+    result << Gene.new(
+      x: GENETIC_MATERIAL.sample,
+      y: GENETIC_MATERIAL.sample
+    )
+    result.uniq!
+  end
+  result.shuffle
+end
+
+def fitness_function
+  ->(member) do
+    city_pairs = []
+    member.genes.each_cons(2) { |cities| city_pairs << cities }
+    # Return to the starting city
+    city_pairs << [member.genes.last, member.genes.first]
+    1.0 / city_pairs.sum { |a, b| a.distance_to(b) }
+  end
+end
+
+def swap_mutation_function(configuration)
+  ->(member) do
+    mutated_genes = member.genes.dup
+    if configuration.mutation_rate > rand
+      gene_one_index = rand(mutated_genes.size)
+      gene_two_index = rand(mutated_genes.size)
+      mutated_genes[gene_one_index], mutated_genes[gene_two_index] = mutated_genes[gene_two_index], mutated_genes[gene_one_index]
+    end
+    PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: mutated_genes)
+  end
+end
+
+def twenty_percent_tournament(configuration)
+  ->(members) do
+    members.sample(configuration.population_size * 0.2).max_by(2) { |member| member.fitness }
+  end
+end
+
+# In ordered crossover, we randomly select a subset of the first
+# parent string and then fill the remainder of the route with the
+# genes from the second parent in the order in which they appear,
+# without duplicating any genes in the selected subset from the
+# first parent
+def random_ordered_crossover_function(configuration)
+  ->(members) do
+    start_slice_index, end_slice_index = rand(members[0].genes.size), rand(members[0].genes.size)
+    parent1_slice = members[0].genes[start_slice_index...end_slice_index]
+    parent2_contribution = members[1].genes - parent1_slice
+    child_genes = Array.new(members[0].genes.size)
+    child_genes[start_slice_index...end_slice_index] = parent1_slice
+    child_genes.map! { |gene| gene.nil? ? parent2_contribution.shift : gene }
+    PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: child_genes)
+  end
+end
+
+def append_best_member_to_file
+  ->(member) do
+    File.open("best_member.txt", "a") do |file|
+      file.puts member.genes.join
+    end
+  end
+end
+
+def write_best_member_to_csv
+  ->(member) do
+    CSV.open("best_member.csv", "wb") do |csv|
+      csv << ["x", "y"]
+      member.genes.each do |gene|
+        csv << [gene.x, gene.y]
+      end
+      csv << [member.genes.first.x, member.genes.first.y]
+    end
+  end
+end
+
+class Gene
+  attr_reader :x, :y
+  def initialize(x: nil, y: nil)
+    @x = x
+    @y = y
+  end
+
+  def distance_to(other)
+    Math.sqrt((x - other.x)**2 + (y - other.y)**2)
+  end
+
+  def to_s
+    "(#{x}, #{y})"
+  end
+
+  # Override equality methods
+  def ==(other)
+    x == other.x && y == other.y
+  end
+
+  def eql?(other)
+    self == other
+  end
+
+  def hash
+    [x, y].hash
+  end
+end
+
+configuration = PetriDish::Configuration.configure do |config|
+  config.max_generations = 100
+  config.population_size = 100
+  config.mutation_rate = 0.01
+  config.genetic_material = GENETIC_MATERIAL
+  config.target_genes = random_uniq_city_gene_generation
+  config.mutation_function = swap_mutation_function(config)
+  config.fitness_function = fitness_function
+  config.parents_selection_function = twenty_percent_tournament(config)
+  config.crossover_function = random_ordered_crossover_function(config)
+  config.highest_fitness_callback = write_best_member_to_csv
+  # Rely on number of generations for end condition
+  config.end_condition_function = ->(_member) { false }
+end
+
+init_members = Array.new(configuration.population_size) { PetriDish::Member.new(fitness_function: configuration.fitness_function, genes: random_uniq_city_gene_generation) }
+PetriDish::World.run(configuration: configuration, members: init_members)
+
+# View CSV with YouPlot (https://github.com/red-data-tools/YouPlot):
+# ruby examples/salesperson_example.rb && uplot line best_member.csv --canvas dot -h 45 -w 150 -H -d ',' && rm best_member.csv

data/lib/petri_dish/configuration.rb

@@ -0,0 +1,125 @@
+module PetriDish
+  class Configuration
+    attr_accessor :logger,
+      :population_size,
+      :mutation_rate,
+      :genetic_material,
+      :elitism_rate,
+      :target_genes,
+      :max_generations,
+      :parents_selection_function,
+      :crossover_function,
+      :mutation_function,
+      :fitness_function,
+      :highest_fitness_callback,
+      :max_generation_reached_callback,
+      :end_condition_function,
+      :next_generation_callback,
+      :end_condition_reached_callback
+
+    def self.configure
+      yield(configuration = new)
+      configuration.validate!
+      configuration
+    end
+
+    def initialize
+      @logger = default_logger
+      @max_generations = default_max_generations
+      @population_size = default_population_size
+      @mutation_rate = default_mutation_rate
+      @elitism_rate = default_elitism_rate
+      @genetic_material = default_genetic_material
+      @target_genes = default_target_genes
+      @fitness_function = default_fitness_function
+      @parents_selection_function = default_parents_selection_function
+      @crossover_function = default_crossover_function
+      @mutation_function = default_mutation_function
+      @highest_fitness_callback = default_highest_fitness_callback
+      @end_condition_function = default_end_condition_function
+      @max_generation_reached_callback = default_max_generation_reached_callback
+      @next_generation_callback = default_next_generation_callback
+      @end_condition_reached_callback = default_end_condition_reached_callback
+    end
+
+    def validate!
+      raise ArgumentError, "logger must respond to :info" unless logger.respond_to?(:info)
+      raise ArgumentError, "max_generations must be greater than 0" unless max_generations > 0
+      raise ArgumentError, "population_size must be greater than 0" unless population_size > 0
+      raise ArgumentError, "mutation_rate must be between 0 and 1" unless mutation_rate >= 0 && mutation_rate <= 1
+      raise ArgumentError, "elitism_rate must be between 0 and 1" unless elitism_rate >= 0 && elitism_rate <= 1
+      raise ArgumentError, "genetic_material must be an Array" unless genetic_material.is_a?(Array)
+      raise ArgumentError, "target_genes must be an Array" unless target_genes.is_a?(Array)
+      raise ArgumentError, "fitness_function must respond to :call" unless fitness_function.respond_to?(:call)
+      raise ArgumentError, "parents_selection_function must respond to :call" unless parents_selection_function.respond_to?(:call)
+      raise ArgumentError, "crossover_function must respond to :call" unless crossover_function.respond_to?(:call)
+      raise ArgumentError, "mutation_function must respond to :call" unless mutation_function.respond_to?(:call)
+      raise ArgumentError, "end_condition_function must respond to :call" unless end_condition_function.respond_to?(:call)
+      raise ArgumentError, "highest_fitness_callback must respond to :call" unless highest_fitness_callback.respond_to?(:call)
+      raise ArgumentError, "max_generation_reached_callback must respond to :call" unless max_generation_reached_callback.respond_to?(:call)
+      raise ArgumentError, "next_generation_callback must respond to :call" unless next_generation_callback.respond_to?(:call)
+      raise ArgumentError, "end_condition_reached_callback must respond to :call" unless end_condition_reached_callback.respond_to?(:call)
+    end
+
+    def reset!
+      @logger = default_logger
+      @max_generations = default_max_generations
+      @population_size = default_population_size
+      @mutation_rate = default_mutation_rate
+      @elitism_rate = default_elitism_rate
+      @genetic_material = default_genetic_material
+      @target_genes = default_target_genes
+      @fitness_function = default_fitness_function
+      @parents_selection_function = default_parents_selection_function
+      @crossover_function = default_crossover_function
+      @mutation_function = default_mutation_function
+      @end_condition_function = default_end_condition_function
+      @highest_fitness_callback = default_highest_fitness_callback
+      @max_generation_reached_callback = default_max_generation_reached_callback
+      @next_generation_callback = default_next_generation_callback
+      @end_condition_reached_callback = default_end_condition_reached_callback
+    end
+
+    private
+
+    def default_logger
+      @logger = Logger.new($stdout).tap do |logger|
+        logger.level = Logger::INFO
+      end
+    end
+
+    def default_max_generations = 1
+
+    def default_population_size = 100
+
+    def default_mutation_rate = 0.005
+
+    def default_elitism_rate = 0.00
+
+    def default_genetic_material = []
+
+    def default_target_genes = nil
+
+    def default_fitness_function = ->(_member) { raise ArgumentError, "fitness_function must be set" }
+
+    def default_parents_selection_function = ->(_members) { raise ArgumentError, "parents_selection_function must be set" }
+
+    def default_crossover_function = ->(_members) { raise ArgumentError, "crossover_function must be set" }
+
+    def default_mutation_function = ->(_member) { raise ArgumentError, "mutation_function must be set" }
+
+    def default_end_condition_function = ->(_member) { false }
+
+    def default_highest_fitness_callback = ->(_member) { :noop }
+
+    # TODO: We might want to consider whether we really want to use `exit` as a
+    # default callback. This will stop the entire Ruby process, which could be
+    # surprising behavior if the user of the library doesn't override these
+    # callbacks.
+    def default_max_generation_reached_callback = -> { exit }
+
+    def default_next_generation_callback = ->(_generation) { :noop }
+
+    def default_end_condition_reached_callback = ->(_member) { exit }
+  end
+end

data/lib/petri_dish/member.rb

@@ -0,0 +1,18 @@
+module PetriDish
+  class Member
+    attr_reader :genes, :fitness_function
+
+    def initialize(genes:, fitness_function:)
+      @fitness_function = fitness_function
+      @genes = genes
+    end
+
+    def fitness
+      @fitness ||= fitness_function.call(self)
+    end
+
+    def to_s
+      genes.join("")
+    end
+  end
+end

data/lib/petri_dish/metadata.rb

@@ -0,0 +1,40 @@
+module PetriDish
+  class Metadata
+    attr_reader :generation_count, :id, :start_time, :highest_fitness, :last_fitness_increase
+
+    def initialize
+      @id = SecureRandom.uuid
+      @generation_count = 0
+      @highest_fitness = 0
+      @last_fitness_increase = 0
+      @start_time = nil
+    end
+
+    def start
+      @start_time = Time.now
+    end
+
+    def increment_generation
+      @generation_count += 1
+    end
+
+    def set_highest_fitness(fitness)
+      @highest_fitness = fitness
+      @last_fitness_increase = generation_count
+    end
+
+    def to_h
+      {
+        id: id,
+        generation_count: generation_count,
+        highest_fitness: highest_fitness,
+        elapsed_time: (Time.now - start_time).round(2),
+        last_fitness_increase: last_fitness_increase
+      }
+    end
+
+    def to_json
+      to_h.to_json
+    end
+  end
+end

data/lib/petri_dish/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PetriDish
+  VERSION = "0.1.1"
+end

data/lib/petri_dish/world.rb

@@ -0,0 +1,66 @@
+RubyVM::InstructionSequence.compile_option = {
+  tailcall_optimization: true,
+  trace_instruction: false
+}
+
+require "json"
+require "logger"
+require "securerandom"
+
+require_relative "../petri_dish"
+
+module PetriDish
+  class World
+    class << self
+      attr_accessor :metadata
+      attr_reader :configuration, :end_condition_reached
+
+      def run(
+        members:,
+        configuration: Configuration.new,
+        metadata: Metadata.new
+      )
+        configuration.next_generation_callback.call(metadata.generation_count)
+
+        end_condition_reached = false
+        max_generation_reached = false
+
+        if metadata.generation_count.zero?
+          configuration.logger.info "Run started."
+          metadata.start
+        end
+
+        configuration.logger.info(metadata.to_json)
+
+        if metadata.generation_count >= configuration.max_generations
+          configuration.max_generation_reached_callback.call
+          max_generation_reached = true
+        end
+
+        elitism_count = (configuration.population_size * configuration.elitism_rate).round
+        elite_members = members.sort_by(&:fitness).last(elitism_count)
+
+        new_members = (configuration.population_size - elitism_count).times.map do
+          child_member = configuration.crossover_function.call(configuration.parents_selection_function.call(members))
+
+          configuration.mutation_function.call(child_member).tap do |mutated_child|
+            if metadata.highest_fitness < mutated_child.fitness
+              metadata.set_highest_fitness(mutated_child.fitness)
+              configuration.highest_fitness_callback.call(mutated_child)
+
+              configuration.logger.info(metadata.to_json)
+            end
+
+            if configuration.end_condition_function.call(mutated_child)
+              configuration.end_condition_reached_callback.call(mutated_child)
+              end_condition_reached = true
+            end
+          end
+        end
+
+        metadata.increment_generation
+        run(members: (new_members + elite_members), configuration: configuration, metadata: metadata) unless end_condition_reached || max_generation_reached
+      end
+    end
+  end
+end

data/lib/petri_dish.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "petri_dish/version"
+require_relative "petri_dish/configuration"
+require_relative "petri_dish/metadata"
+require_relative "petri_dish/world"
+require_relative "petri_dish/member"
+
+module PetriDish
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/petri_dish.rbs

@@ -0,0 +1,4 @@
+module PetriDish
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: petri_dish_lab
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Thomas Countz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Petri Dish allows for various configuration options to let users to customize
+  and experiment with different parameters and functions of the evolutionary algorithm.
+email:
+- thomascountz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".DS_Store"
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/lazy_dog_example.rb
+- examples/salesperson_example.rb
+- lib/petri_dish.rb
+- lib/petri_dish/configuration.rb
+- lib/petri_dish/member.rb
+- lib/petri_dish/metadata.rb
+- lib/petri_dish/version.rb
+- lib/petri_dish/world.rb
+- sig/petri_dish.rbs
+homepage: https://github.com/thomascountz/petri_dish
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/thomascountz/petri_dish
+  source_code_uri: https://github.com/thomascountz/petri_dish
+  changelog_uri: https://github.com/thomascountz/petri_dish/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.17
+signing_key:
+specification_version: 4
+summary: A Ruby library for implementing and experimenting with evolutionary algorithms.
+test_files: []