OpenGA.Net 1.0.0

🧬 OpenGeneticAlgorithm.NET

The most intuitive, powerful, and extensible genetic algorithm framework for .NET

OpenGA.Net is a high-performance, type-safe genetic algorithm library that makes evolutionary computation accessible to everyone. Whether you're solving complex optimization problems, researching machine learning, or just getting started with genetic algorithms, OpenGA.Net provides the tools you need with an elegant, fluent API.

🚀 Quick Start

Installation

dotnet add package OpenGA.Net

Your First Genetic Algorithm

A Chromosome in OpenGA.Net represents a potential solution to your optimization problem. It contains genes (the solution components) and defines how to evaluate, modify, and repair solutions.

Step 1: Create your chromosome by inheriting from the Chromosome<T> abstract class, the example below demonstrates how a Chromosome representing a potential solution to the traveling salesman problem could look like:

using OpenGA.Net;

// A chromosome for the Traveling Salesman Problem. Each chromosome represents a route through cities (genes = city sequence)
public class TspChromosome : Chromosome<int>
{
    private readonly double[,] _distanceMatrix;
    
    public TspChromosome(IList<int> cities, double[,] distanceMatrix) : base(cities)
    {
        _distanceMatrix = distanceMatrix;
    }
    
    // Calculate how "good" this route is (shorter distance = higher fitness)
    public override async Task<double> CalculateFitnessAsync()
    {
        double totalDistance = CalculateTotalDistance();
        
        return 1.0 / (1.0 + totalDistance);
    }
    
    // Randomly swap two cities in the route
    public override async Task MutateAsync(Random random)
    {
        int index1 = random.Next(Genes.Count);
        int index2 = random.Next(Genes.Count);
        (Genes[index1], Genes[index2]) = (Genes[index2], Genes[index1]);
        
        InvalidateFitness(); // Important: invalidate cached fitness after mutation
    }
    
    // Create an identical copy of this chromosome
    public override async Task<Chromosome<int>> DeepCopyAsync()
    {
        return new TspChromosome(new List<int>(Genes), _distanceMatrix);
    }
    
    // Ensure each city appears exactly once (fix any duplicates)
    public override async Task GeneticRepairAsync()
    {
        // Implementation would ensure no duplicate cities exist
        // For example: remove duplicates and fill missing cities
    }
    
    private double CalculateTotalDistance()
    {
        double distance = 0;
        for (int i = 0; i < Genes.Count - 1; i++)
        {
            distance += _distanceMatrix[Genes[i], Genes[i + 1]];
        }
        distance += _distanceMatrix[Genes[^1], Genes[0]]; // Return to start
        return distance;
    }
}

Step 2: Create your initial population:

// Generate initial population of random routes. The initial population represents a set of random solutions to the optimization problem.
var initialPopulation = new TspChromosome[100];
for (int i = 0; i < 100; i++)
{
    var cities = Enumerable.Range(0, numberOfCities).OrderBy(x => _random.Next()).ToList();
    initialPopulation[i] = new TspChromosome(cities, _distanceMatrix);
}

Step 3: Configure and run your genetic algorithm:

// Configure and run your genetic algorithm
var bestSolution = await OpenGARunner<int>
    .Initialize(initialPopulation)
    .RunToCompletionAsync();

// Get your optimized result
Console.WriteLine($"Best route: {string.Join(" → ", bestSolution.Genes)}");

That's it! 🎉 You just solved an optimization problem with a few lines of code.

🏗️ Architecture Overview

OpenGA.Net is built around four core concepts that work together seamlessly:

🧬 Chromosomes

Your solution candidates. Strongly typed and extensible. Each Chromosome<T> subclass defines how a solution is represented and evaluated. Implement:

• CalculateFitnessAsync() — return a higher-is-better score for the current Genes
• MutateAsync() — randomly perturb Genes to explore the search space
• DeepCopyAsync() — produce a full copy used during crossover
• GeneticRepairAsync() (optional) — fix invalid states after crossover/mutation

Tip: See the TSP chromosome in the Quick Start above for a concrete example. The pattern is the same for any problem: choose a gene representation, define a fitness function, add a simple mutation, and optionally repair to enforce constraints.

🎯 Parent Selection Strategies

Choose the chromosomes that will participate in mating/crossover:

🧬 Crossover Strategies

Create offspring by combining parent chromosomes:

🔄 Survivor Selection Strategies

Manage population evolution over generations:

🏁 Termination Strategies

Control when the genetic algorithm stops evolving:

💡 Strategy Selection Examples

// High-performance optimization (fast convergence needed)
.ParentSelection(c => c.RegisterSingle(s => s.Tournament()))
.Crossover(c => c.RegisterSingle(s => s.OnePointCrossover()))
.SurvivorSelection(r => r.RegisterSingle(s => s.Elitist()))
.Termination(t => t.MaximumEpochs(100))

// Exploratory search (avoiding local optima)
.ParentSelection(c => c.RegisterSingle(s => s.Tournament()))
.Crossover(c => c.RegisterSingle(s => s.UniformCrossover()))
.SurvivorSelection(r => r.RegisterSingle(s => s.Generational()))
.Termination(t => t.TargetStandardDeviation(stdDev: 0.001))

// Production system (time-constrained)
.ParentSelection(c => c.RegisterSingle(s => s.Tournament()))
.Crossover(c => c.RegisterSingle(s => s.OnePointCrossover()))
.SurvivorSelection(r => r.RegisterSingle(s => s.Elitist()))
.Termination(t => t.MaximumDuration(TimeSpan.FromMinutes(5)))

// Quality-focused research (target fitness termination)
.ParentSelection(c => c.RegisterSingle(s => s.RouletteWheel()))
.Crossover(c => c.RegisterSingle(s => s.KPointCrossover(3)))
.SurvivorSelection(r => r.RegisterSingle(s => s.Elitist(0.2f)))
.Termination(t => t.TargetFitness(0.95).TargetStandardDeviation(stdDev: 0.001, window: 10))

🎯 Use Cases

🏭 Optimization Problems

• Scheduling: Job shop, vehicle routing, resource allocation
• Engineering Design: Antenna design, circuit optimization, structural engineering
• Financial: Portfolio optimization, trading strategies, risk management

🧠 Machine Learning

• Neural Architecture Search: Automatically design neural networks
• Hyperparameter Tuning: Optimize ML model parameters
• Feature Selection: Find optimal feature subsets

🎮 Game Development

• AI Behavior: Evolve intelligent game agents
• Level Generation: Create procedural game content
• Balancing: Optimize game mechanics and difficulty curves

🔬 Research & Academia

• Evolutionary Computation: Research platform for GA variants
• Multi-objective Optimization: Pareto-optimal solutions
• Algorithm Comparison: Benchmark different evolutionary strategies

⚙️ Advanced Configuration

For sophisticated optimization scenarios, OpenGA.Net supports advanced multi-strategy configurations with Adaptive Pursuit - an intelligent operator selection policy that learns which strategies perform best over time and automatically adjusts selection probabilities.

🧠 Adaptive Pursuit Algorithm

Adaptive Pursuit continuously monitors the performance of each configured strategy and dynamically adapts their selection probabilities based on:

• Fitness improvement from applied operators
• Population diversity maintenance
• Recent performance trends with temporal weighting
• Exploration vs exploitation balance

This creates a self-optimizing genetic algorithm that automatically discovers the best operator combinations for your specific problem.

� Multi-Strategy Configuration

var result = await OpenGARunner<int>
    .Initialize(initialPopulation, minPopulationPercentage: 0.4f, maxPopulationPercentage: 2.5f)
    .WithRandomSeed(42)
    .MutationRate(0.15f)
    
    // Multi-strategy parent selection with adaptive learning
    .ParentSelection(p => p.RegisterMulti(m => m
        .Tournament(stochasticTournament: true, customWeight: 0.4f)
        .RouletteWheel(customWeight: 0.3f)
        .Rank(customWeight: 0.2f)
        .Boltzmann(temperatureDecayRate: 0.05, initialTemperature: 1.0, customWeight: 0.1f)
        .WithPolicy(policy => policy.AdaptivePursuit(
            learningRate: 0.12,
            minimumProbability: 0.05,
            rewardWindowSize: 15
        ))
    ))
    
    // Single high-performance crossover for exploitation
    .Crossover(c => c.RegisterSingle(s => s.KPointCrossover(3))
        .WithCrossoverRate(0.85f))
    
    // Multi-strategy survivor selection for dynamic population management
    .SurvivorSelection(s => s.RegisterMulti(m => m
        .Elitist(elitePercentage: 0.12f, customWeight: 0.6f)
        .Tournament(tournamentSize: 4, stochasticTournament: true, customWeight: 0.3f)
        .AgeBased(customWeight: 0.1f)
        .WithPolicy(policy => policy.AdaptivePursuit(
            learningRate: 0.08,
            diversityWeight: 0.15
        ))
    ).OverrideOffspringGenerationRate(1.3f))
    
    // Multi-condition termination
    .Termination(t => t
        .MaximumEpochs(750)
        .MaximumDuration(TimeSpan.FromMinutes(10))
        .TargetFitness(0.98)
        .TargetStandardDeviation(0.001, window: 20))
    
    .RunToCompletionAsync();

🛠️ Extensibility

Create your own strategies by inheriting from base classes:

// Custom crossover strategy
public class MyCustomCrossover<T> : BaseCrossoverStrategy<T>
{
    protected internal override async Task<IEnumerable<Chromosome<T>>> CrossoverAsync(
        Couple<T> couple, Random random)
    {
        // Your custom crossover logic
    }
}

// Custom survivor selection strategy  
public class MySurvivorSelectionStrategy<T> : BaseSurvivorSelectionStrategy<T>
{
    internal override float RecommendedOffspringGenerationRate => 0.5f;
    
    protected internal override async Task<IEnumerable<Chromosome<T>>> SelectChromosomesForEliminationAsync(
        Chromosome<T>[] population, Chromosome<T>[] offspring, Random random, int currentEpoch = 0)
    {
        // Your custom survivor selection logic
    }
}

// Custom reproduction selector
public class MyParentSelector<T> : BaseParentSelectorStrategy<T>
{
    protected internal override async Task<IEnumerable<Couple<T>>> SelectMatingPairsAsync(
        Chromosome<T>[] population, Random random, int minimumNumberOfCouples)
    {
        // Your custom parent selection logic
    }
}

// Custom termination strategy
public class MyTerminationStrategy<T> : BaseTerminationStrategy<T>
{   
    public override bool Terminate(GeneticAlgorithmState state)
    {
        // Your custom logic to control when the GA should terminate
    }
}

// Using your custom strategies
var result = await OpenGARunner<MyGeneType>
    .Initialize(initialPopulation)
    .ParentSelection(c => c.RegisterSingle(s => s.Custom(new MyParentSelector<MyGeneType>())))
    .Crossover(c => c.RegisterSingle(s => s.CustomCrossover(new MyCustomCrossover<MyGeneType>())))
    .SurvivorSelection(r => r.RegisterSingle(s => s.Custom(new MySurvivorSelectionStrategy<MyGeneType>())))
    .Termination(t => t.Custom(new MyTerminationStrategy<MyGeneType>(50)))
    .RunToCompletionAsync();

📊 Performance & Benchmarks

OpenGA.Net has been rigorously tested on classic optimization problems to demonstrate its performance and solution quality. Our comprehensive benchmark suite includes:

🔬 Benchmark Problems

• 🗺️ Traveling Salesman Problem (TSP): 30 and 50 city instances
• 🎒 Knapsack Problem: 50 and 100 item optimization
• 📦 Bin Packing Problem: 50 and 100 item optimization

⚡ Performance Highlights

• Execution Speed: 601ms-2,321ms for 500 generations on complex problems
• Scalability: Linear scaling with population size and problem complexity
• Solution Quality: Consistently achieves near-optimal results within 1-2% of known bounds

📈 Key Results

Result Interpretation:

• TSP: % improvement over random tours / absolute distance (showing significant optimization capability)
• Knapsack: Total value achieved and efficiency vs upper bound (nearly optimal solutions)
• Bin Packing: Bins used (achieving optimal or near-optimal solutions)

🏃 Run Benchmarks Yourself

cd OpenGA.Net.Benchmarks

# Quick performance tests
dotnet run --simple

# Detailed solution quality analysis  
dotnet run --analysis

# Comprehensive BenchmarkDotNet suite
dotnet run

📋 View Complete Benchmark Results - Detailed methodology, configurations, and analysis

🤝 Contributing

We welcome contributions! OpenGA.Net is built by the community, for the community.

🐛 Found a Bug?

Open an issue with:

• Clear reproduction steps
• Expected vs actual behavior
• Environment details

🔧 Want to Code?

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Submit a pull request

📄 License

OpenGA.Net is released under the MIT License. See LICENSE.md for details.

Copyright (c) 2024 Ahmed Sarnaout

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.