HEAL.HeuristicLib 0.1.168-alpha

<div align="center">

HeuristicLib

Heuristic and evolutionary optimization for modern .NET

Get started · Read the guide · Browse examples · Report an issue

</div>

HeuristicLib is a .NET library for building, running and studying heuristic optimization algorithms. Configure a genetic algorithm, hill climber, evolution strategy or NSGA-II in plain C#. Combine typed operators with your problem, stream every search state and repeat runs with deterministic random seeds.

<p align="center"> <a href="https://heal.heuristiclab.com/"> <img src="https://raw.githubusercontent.com/heal-research/HeuristicLib/main/docs/public/heal-logo.png" alt="Heuristic and Evolutionary Algorithms Laboratory" width="360"> </a> </p>

The library is developed by the Heuristic and Evolutionary Algorithms Laboratory, the research group behind HeuristicLab and Operon. HeuristicLib is a new library with a smaller scope and an API designed for current C#.

Why HeuristicLib

• Configure algorithms with C# object initializers and records. There is no operator graph or separate configuration language.
• Keep candidate, search space, problem and operator types connected through the whole algorithm. The compiler catches incompatible combinations.
• Stream search states or attach analyzers for quality, diversity, genealogy and evaluation counts.
• Reproduce a run from its root seed. Forked random streams keep parallel work independent of scheduling.
• Repeat configurations, build typed parameter grids and process independent trials concurrently.
• Use built in real, integer, Boolean, permutation and symbolic expression representations.

Install

HeuristicLib targets .NET 10 and is available as a prerelease NuGet package.

dotnet add package HEAL.HeuristicLib --prerelease

Example 1: solve a TSPLIB instance and record its quality curve

This example loads the named berlin52 benchmark from a standard TSPLIB file, solves it with a genetic algorithm and records the best, median and worst tour length after every generation. You can use the berlin52.tsp file in this repository to run it.

using HEAL.HeuristicLib.Algorithms;
using HEAL.HeuristicLib.Random;
using HEAL.HeuristicLib.Analysis;
using HEAL.HeuristicLib.Operators;
using HEAL.HeuristicLib.Problems.TravelingSalesman;

var instance = TsplibTspInstanceProvider.LoadData(
    "berlin52.tsp",
    bestQuality: 7542);
var problem = new TravelingSalesmanProblem(instance.ToCoordinatesData());

var algorithm = GeneticAlgorithm.For(
    problem,
    selector: TournamentSelector.For(problem, tournamentSize: 3),
    populationSize: 100,
    maximumGenerations: 500,
    mutationRate: 0.05);

var run = algorithm
    .CreateRun(problem, RandomNumberGenerator.Create(seed: 42))
    .TrackBestMedianWorst(out var qualityAnalyzer);

await run.CompleteAsync();

var qualityCurve = run.GetResult(qualityAnalyzer);
var best = qualityCurve[^1].Best;

Console.WriteLine($"Instance: {instance.Name}");
Console.WriteLine($"Best tour length: {best.ObjectiveVector[0]:F0}");

foreach (var (entry, generation) in qualityCurve.Select((entry, i) => (entry, i + 1)))
{
    Console.WriteLine(
        $"{generation,3}: " +
        $"best {entry.Best.ObjectiveVector[0],8:F0}  " +
        $"median {entry.Median.ObjectiveVector[0],8:F0}  " +
        $"worst {entry.Worst.ObjectiveVector[0],8:F0}");
}

GeneticAlgorithm.For(problem, ...) asks the problem and its encoding for suggested operators. Here the traveling salesperson problem supplies order crossover, while the permutation encoding supplies random creation and inversion mutation. Algorithm settings come from GeneticAlgorithmDefaults unless the call overrides them. Defaults are starting points rather than tuned choices. Configure an operator explicitly when an experiment depends on that choice.

The algorithm configuration stays reusable. Change the TSPLIB file to run another named instance. Use a with expression to change the crossover or mutation operator and test another search policy. Keep the problem, seed schedule and analyzer unchanged when comparing configurations.

See problems, operators, observability and analysis and experiments for the underlying APIs.

Example 2: train a symbolic regression model

Symbolic regression searches for a mathematical expression instead of fitting coefficients in a fixed model form. In this example genetic programming evolves the expression structure. A numeric refiner fits constants inside each candidate with nonlinear least squares.

using HEAL.HeuristicLib.Algorithms;
using HEAL.HeuristicLib.Random;
using HEAL.HeuristicLib.Data;
using HEAL.HeuristicLib.MachineLearning;
using HEAL.HeuristicLib.Encodings.SymbolicExpressions;
using HEAL.HeuristicLib.Operators;
using HEAL.HeuristicLib.Problems.MachineLearning;

var x = Enumerable.Range(0, 40)
    .Select(index => (index - 20) * 0.25)
    .ToArray();
var y = x.Select(value => 2.5 * value + 1.3).ToArray();

var trainingData = new RegressionData(
    new DataFrame([Series<double>.FromOwnedArray("x", x)]),
    Series<double>.FromOwnedArray("y", y));

var searchSpace = new ExpressionTreeSearchSpace(
    maximumLength: 15,
    maximumDepth: 5,
    operations: [Symbols.Addition, Symbols.Subtraction, Symbols.Multiplication],
    variables: ["x"],
    constants: [new EvolvableConstantSymbol()]);

var problem = new SymbolicRegressionProblem(
    trainingData,
    Metrics.MSE,
    searchSpace);

var algorithm = GeneticAlgorithm.Create(
    new RampedHalfAndHalfTreeCreator(),
    new SubtreeCrossover(),
    ChooseOneMutator.Create(
        new NodeReplacementMutator(),
        new LocalPerturbationMutator(),
        new SubtreeMutator()),
    refiner: new NumericParameterFittingRefiner
    {
        MaximumIterations = 10
    },
    selector: TournamentSelector.For(problem, tournamentSize: 3),
    populationSize: 100,
    maximumGenerations: 50,
    mutationRate: 0.25);

var finalState = await algorithm.CompleteAsync(
    problem,
    RandomNumberGenerator.Create(seed: 42));

var best = finalState.Population.EvaluatedCandidates
    .MinBy(candidate => candidate.ObjectiveVector[0])!;
var compiledModel = best.Candidate.Compile(optimize: true);
var predictions = compiledModel.Evaluate(trainingData.Inputs);

Console.WriteLine($"Model: {best.Candidate.ToInfixString()}");
Console.WriteLine($"Training MSE: {best.ObjectiveVector[0]:G6}");

The trained candidate is an expression tree. Inspect it, format it as infix, C#, Python or LaTeX and evaluate it on new data.

Interactive symbolic regression

Draw a target curve in the Python demonstrator and watch HeuristicLib evolve candidate expressions. The browser displays each generation and the final tradeoff between fit and expression complexity.

<p align="center"> <img src="https://raw.githubusercontent.com/heal-research/HeuristicLib/main/examples/PythonInteractiveDemonstrator/documentation/demo.gif" alt="Interactive symbolic regression demonstrator" width="480"> </p>

The complete application is in examples/PythonInteractiveDemonstrator. It uses pythonnet to host HeuristicLib from a FastAPI application.

What is included

Research algorithms such as ALPS and the open ended relevant alleles preserving genetic algorithm are in HEAL.HeuristicLib.Experimental. The Experimental package also owns genealogy workflows and population level or Pareto history analyzers. Static Quadratic Assignment is part of the main package, while its dynamic variants remain Experimental. Add an explicit package reference when an example or application uses an Experimental feature:

dotnet add package HEAL.HeuristicLib.Experimental --prerelease

Documentation

• Build your first optimizer
• Understand the core concepts
• Choose an algorithm
• Run repeatable experiments
• Train symbolic regression models
• Work with symbolic expressions
• Use HeuristicLib from Python

Build the repository

Install the .NET 10 SDK, then run:

dotnet restore
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-restore

To work on the documentation site:

npm ci
npm run docs:dev

Contributor rules and validation commands are in AGENTS.md. Implementation and public API conventions are in the developer guidelines.

License

HeuristicLib is available under the MIT License.