DarwinGA 1.0.2

🧬 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.

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)

🌍 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 }

🧠 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

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

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>