DarwinGA 1.0.3

🧬 DarwinGA

A High-Performance Genetic Algorithm Engine for .NET

DarwinGA is a modular, extensible genetic algorithm framework for .NET 8.
Define your problem. Let evolution find the solution.

Author / Contact

• Email: gerardotous@gmail.com
• LinkedIn: https://www.linkedin.com/in/gerardo-tous-vallespir-42491636/

Quick Start · Features · Operators · Examples · API Reference

❓ What Is DarwinGA?

DarwinGA is a genetic algorithm (GA) library that lets you solve optimization problems using the principles of natural evolution: selection, crossover, mutation, and survival of the fittest.

Instead of coding a solver, you describe:

1. What a solution looks like (chromosome)
2. How to evaluate it (fitness function)
3. How it mutates and combines (genetic operators)

The engine evolves a population of candidate solutions across generations until it converges on the best one.

✨ Features at a Glance

📦 Installation

dotnet add package DarwinGA

Or via the NuGet Package Manager in Visual Studio:

Install-Package DarwinGA

🚀 Quick Start

Three steps to evolve a solution:

1️⃣ Define Your Chromosome

Implement IGAEvolutional<T> on any class that represents a candidate solution:

using DarwinGA.Interfaces;

public class PriceSolution : IGAEvolutional<PriceSolution>
{
    public double Price { get; set; }
}

2️⃣ Implement Mutation and Crossover

public class PriceMutation : IMutation<PriceSolution>
{
    public void Apply(PriceSolution evo, double mutationProb)
    {
        if (MyRandom.NextDouble() < mutationProb)
            evo.Price += MyRandom.NextDouble() * 2 - 1;
    }
}

public class PriceCrossover : ICross<PriceSolution>
{
    public PriceSolution Apply(PriceSolution a, PriceSolution b)
    {
        return new PriceSolution
        {
            Price = (a.Price + b.Price) / 2.0
        };
    }
}

3️⃣ Configure and Run

using DarwinGA;
using DarwinGA.Selections;
using DarwinGA.Terminations;

var ga = new GeneticAlgorithm<PriceSolution>
{
    NewItem = () => new PriceSolution { Price = MyRandom.NextDouble() * 100 },

    Fitness = solution =>
    {
        double demand = 100 - solution.Price;
        return solution.Price * demand; // maximize profit
    },

    Mutation            = new PriceMutation(),
    Cross               = new PriceCrossover(),
    MutationProbability = 0.05,

    Selection   = new TournamentSelection(tournamentSize: 5),
    Termination = new GenerationNumTermination(maxGenerations: 300),

    OnNewGeneration = result =>
    {
        Console.WriteLine($"Gen {result.GenerationNum}: Best Fitness = {result.BestFitness:F2}");
    }
};

ga.Run(populationSize: 100);

That's it. The algorithm handles the rest.

🧰 Built-in Operators

🏆 Selection Strategies (7)

Choose how parents are picked for breeding:

// Tournament selection keeping top 50% via 5-way tournaments
Selection = new TournamentSelection(tournamentSize: 5, selectionFraction: 0.5)

// Age-based on top of tournament (5% penalty per generation)
EnableAgeBasedSelection = true,
AgePenaltyFactor = 0.05,
Selection = new TournamentSelection(5)

🧬 Mutation Operators — Binary (11)

Control how chromosomes are randomly altered:

🔀 Crossover Operators — Binary (8)

Define how two parents produce offspring:

🛑 Termination Conditions (2)

Stop evolution when a condition is met:

// Stop after 500 generations
Termination = new GenerationNumTermination(500)

// Stop when fitness >= 0.98
Termination = new FitnessThresholdTermination(0.98)

♻️ Reinsertion Strategies (1)

Control which individuals from the current generation survive directly into the next (elitism):

// Keep the single best individual across generations (default)
Reinsert = new ReinsertBest<MyChromosome>(count: 1)

// Keep the top 3 elites
Reinsert = new ReinsertBest<MyChromosome>(count: 3)

Reinsertion prevents the best solution found so far from being lost to random variation. When Reinsert is set, the survivors it returns are injected at the start of the next population before breeding fills the rest.

You can define custom strategies by implementing IReinsert<T>:

public interface IReinsert<T> where T : IGAEvolutional<T>
{
    T[] GetSurvivors(FitnessResult[] elites);
}

🌍 Diversity Preservation

Prevent premature convergence by penalizing similar individuals:

EnableDiversity = true,

// Define how to measure distance between two individuals
DiversityMetric = new DelegateDiversityMetric<MyChromosome>(
    (a, b) => /* return a double representing distance */
),

// Penalize fitness of similar individuals (higher factor = stronger penalty)
DiversityStrategy = new SimilarityPenaltyStrategy<MyChromosome>(penaltyFactor: 0.5)

You can also implement IDiversityMetric<T> and IDiversityStrategy<T> for custom behavior.

⚡ Parallel Processing

Speed up evolution on multi-core machines:

// Evaluate fitness in parallel across the population
EnableParallelEvaluation = true,

// Breed children in parallel
EnableParallelBreeding = true,

// Optionally configure parallelism limits
ParallelOptions = new ParallelOptions { MaxDegreeOfParallelism = 8 }

🎲 Reproducibility, Adaptive Rates, and Checkpoints

Use a fixed seed for deterministic runs (recommended with parallel modes disabled):

RandomSeed = 12345,

Enable adaptive mutation/crossover when fitness stagnates:

EnableAdaptiveRates = true,

// Starts increasing mutation / decreasing crossover after N stagnant generations
StagnationThreshold = 10,

AdaptiveMutationStep = 0.01,
AdaptiveCrossoverStep = 0.02,

AdaptiveMutationMin = 0.001,
AdaptiveMutationMax = 0.5,
AdaptiveCrossoverMin = 0.2,
AdaptiveCrossoverMax = 1.0,

During OnNewGeneration, each GenerationResult<T> now includes:

• MutationProbability
• CrossoverProbability
• StagnationGenerations

Checkpoint and resume a run:

var ga = new GeneticAlgorithm<MyChromosome>
{
    // ... required setup ...
};

ga.Run(populationSize: 100);

// Save in-memory snapshot (population + generation + adaptive state)
var checkpoint = ga.CreateCheckpoint();

// Later, continue from the same checkpoint
ga.Run(checkpoint);

For deep-copy checkpoints, provide a clone function:

CloneElement = x => /* return a deep copy of x */

🧠 Neuroevolution Support

DarwinGA includes built-in support for evolving neural networks via ActivationNetworkEvolutional:

using DarwinGA.Evolutionals.ActivationNetworkEvolutional;

var ga = new GeneticAlgorithm<ActivationNetworkEvolutional>
{
    NewItem = () => new ActivationNetworkEvolutional(
        neuronsCount: new[] { 5, 3, 1 },
        inputsCount: 4
    ),

    Fitness = individual =>
    {
        // Evaluate the neural network on your dataset
        double[] output = individual.NeuralNetwork.Compute(inputData);
        return CalculateAccuracy(output, expected);
    },

    Mutation    = new ActivationNetworkMutation(),
    Cross       = new ActivationNetworkCrossover(),
    Selection   = new TournamentSelection(5),
    Termination = new GenerationNumTermination(1000),
    OnNewGeneration = r =>
        Console.WriteLine($"Gen {r.GenerationNum}: {r.BestFitness:F4}")
};

ga.Run(populationSize: 50);

Evolve neural network topologies and weights without backpropagation — ideal for reinforcement learning, game AI, and control systems.

📋 Full Example

The 0/1 Knapsack problem: choose a subset of items to maximize total value without exceeding a weight capacity.

using DarwinGA;
using DarwinGA.Diversity;
using DarwinGA.Evolutionals.BinaryEvolutional;
using DarwinGA.Evolutionals.BinaryEvolutional.Crossers;
using DarwinGA.Evolutionals.BinaryEvolutional.Mutations;
using DarwinGA.Selections;
using DarwinGA.Terminations;

var items = new (int weight, double value)[]
{
    (12, 60), (7, 34), (11, 55), (8, 40),
    (9, 42), (6, 30), (13, 70), (5, 25)
};
int capacity = 30;

var ga = new GeneticAlgorithm<BinaryEvolutional>()
{
    NewItem = () =>
    {
        var chr = new BinaryEvolutional(items.Length);
        for (int i = 0; i < items.Length; i++)
            chr.SetGen(i, MyRandom.NextDouble() < 0.5);
        return chr;
    },

    Fitness = individual =>
    {
        int w = 0;
        double v = 0;
        for (int i = 0; i < individual.Size; i++)
        {
            if (!individual.GetGen(i)) continue;
            w += items[i].weight;
            v += items[i].value;
        }

        if (w <= capacity) return v;

        int extra = w - capacity;
        return v - (extra * extra * 5.0); // penalty
    },

    MutationProbability    = 0.10,
    Mutation               = new KFlipMutation(2),
    Cross                  = new UniformCross(0.5),
    Selection              = new TournamentSelection(8),
    Termination            = new FitnessThresholdTermination(0.98),

    EnableParallelEvaluation = true,

    EnableDiversity  = true,
    DiversityMetric  = new DelegateDiversityMetric<BinaryEvolutional>((a, b) =>
    {
        int diff = 0;
        for (int i = 0; i < a.Size; i++)
            if (a.GetGen(i) != b.GetGen(i)) diff++;
        return diff;
    }),
    DiversityStrategy = new SimilarityPenaltyStrategy<BinaryEvolutional>(penaltyFactor: 0.6),

    OnNewGeneration = result =>
    {
        Console.WriteLine(
            $"Gen {result.GenerationNum,-4} | Best: {result.BestFitness:F2} | Avg: {result.AverageFitness:F2} | Div: {result.DiversityIndex:F2}");
    }
};

ga.Run(populationSize: 120);

🔌 API Reference

GeneticAlgorithm<T> — Main Engine

Main Methods

Key Interfaces

🧠 How to Think in Evolutionary Terms

Instead of asking:

❌ "How do I solve this problem?"

Ask:

✅ "What does a solution look like?" → Define your chromosome
✅ "How do I measure if it's good?" → Write a fitness function
✅ "How can I slightly modify it?" → Choose mutation & crossover operators

The algorithm handles the rest.

💡 Tips for Good Results

🔥 Use Case Ideas

DarwinGA can optimize any problem you can encode as a chromosome:

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

🔗 Repository: https://github.com/G3r4rd00/DarwinGA

📫 Contact

• Email: gerardotous@gmail.com
• LinkedIn: https://www.linkedin.com/in/gerardo-tous-vallespir-42491636/

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

<div align="center">

Made with 🧬 by Gerardo Tous

If DarwinGA helped your project, consider giving it a ⭐ on GitHub!

</div>