Evolute 0.1.0

Evolute

Evolute is a modular C# library for evolutionary computation with first-class NEAT (NeuroEvolution of Augmenting Topologies) support. It helps you evolve neural networks to solve machine learning and simulation problems with a clean, extensible API.

Highlights

• Core evolutionary primitives: genomes, mutation, crossover, selection
• Neural network runtime: nodes, connections, activation functions, forward evaluation
• NEAT: topology mutation (add node/connection), innovation tracking, speciation with fitness sharing, elitism, per-species offspring allocation
• Async fitness evaluation for performance
• Simple, extensible design via interfaces and parameters

Project Structure

Evolute/
├── Core/                     # Evolutionary algorithm components
│   ├── IGenome.cs
│   ├── Population.cs
│   ├── Selection/
│   └── Operators/
├── NeuralNetwork/            # NN runtime
│   ├── ActivationFunctions.cs
│   └── Network.cs
├── NEAT/                     # NEAT implementation
│   ├── Genes/
│   ├── Speciation/
│   ├── InnovationTracker.cs
│   ├── NeatGenome.cs
│   ├── NeatParameters.cs
│   └── NeatPopulation.cs
├── Simulation/               # Fitness interfaces
│   └── IFitnessFunction.cs
├── Utilities/
│   └── RandomExtensions.cs   # Random extension helpers
└── Examples/
    └── XorExample.cs

Requirements

• .NET 10 (preview) SDK

Quick Start

Evolute is a class library. Use it from your app or tests.

Install from NuGet:

dotnet add package Evolute

or with Package Manager:

Install-Package Evolute

Then, in a console app or test project, you can run the built-in XOR example:

using Evolute.Examples;

XorExample.Run();

From source (clone) build:

git clone https://github.com/kerodkibatu/Evolute
cd Evolute
dotnet build -c Release

Usage (NEAT)

Minimal example: create a population, define a fitness function, evolve, then inspect the best genome.

using Evolute.NEAT;
using Evolute.Simulation;

public class MyFitness : IFitnessFunction
{
    public double Evaluate(IGenome genome)
    {
        var neat = (NeatGenome)genome;
        // Compute error -> return higher-is-better fitness
        var outputs = neat.Network.Evaluate(new double[] { /* inputs */ });
        var error = /* ... */ 0.0;
        return 1.0 / (1.0 + error);
    }
}

var population = new NeatPopulation(size: 200, inputCount: 3, outputCount: 1);
await population.EvolveAsync(new MyFitness(), generations: 100);
var best = population.BestGenome();

Customize parameters:

var parameters = new NeatParameters
{
    PopulationSize = 300,
    CompatibilityThreshold = 3.0,
    ElitesPerSpecies = 1,
    SurvivalThreshold = 0.2,
    InterspeciesMatingRate = 0.01,
    WeightPerturbRate = 0.9,
    WeightReplaceRate = 0.1,
    WeightSigma = 0.5,
    AddConnectionRate = 0.08,
    AddNodeRate = 0.03,
    DisableInheritRate = 0.75
};

var pop = new NeatPopulation(size: parameters.PopulationSize, inputCount: 2, outputCount: 1, parameters: parameters);

NEAT Details

• Topology mutation
  • Add connection: randomly connects existing nodes if not already connected
  • Add node: splits an enabled connection into two with a new hidden node
• Crossover
  • Favors the fitter parent for disjoint/excess genes; matching genes are randomly chosen
  • Disabled-gene inheritance probability controlled by DisableInheritRate
• Speciation
  • Compatibility distance: c1*excess/n + c2*disjoint/n + c3*avgWeightDiff
  • Fitness sharing within species
  • Per-species offspring allocation proportional to shared fitness
  • Elitism per species

Neural Network

• Nodes: Input, Hidden, Output
• Connections: weighted, enabled/disabled
• Evaluation: multi-iteration propagation to support arbitrary DAGs and simple recurrent topologies
• Activation functions: Sigmoid, Tanh, Relu (extensible)

Randomness

• Evolute uses a single thread-safe RNG via Random.Shared
• Helper extension methods in Utilities/RandomExtensions.cs:
  • NextGaussian() (Box–Muller)
  • NextDouble(min, max)
  • NextBool(p) / NextSign()

Extensibility

• Fitness: implement IFitnessFunction
• Selection: implement ISelectionStrategy (e.g., replace TournamentSelection)
• Operators: implement IMutationOperator, ICrossoverOperator if you want to override NEAT defaults
• Activation: add custom functions and assign to nodes as needed

Roadmap

• Serialization of genomes/populations (JSON)
• Visualization of topologies (Graphviz export)
• Deterministic runs via optional seeded RNG injection
• More built-in environments/examples

Contributing

Contributions are welcome! Please open an issue or a PR with a clear description and tests where applicable.

License

MIT