ProgramEvolutionResult

Models & Types · AiDotNet.Evolution.Programs

The reportable summary of a finished program-evolution run.

For Beginners

This is the report card for a run. It answers the four questions you actually ask afterwards: what is the best program found, what other good and different programs were found, how much did the AI calls cost, and can I resume this later. It deliberately keeps only a capped amount of each program’s text, because these summaries end up in logs and a generated program can be arbitrarily long. Use BestProgram for the winner and Elites to see the alternatives it beat.

How It Works

EvolutionRunResult is the engine’s own result and holds live archive snapshots of every island. This type is the flat, bounded projection of it that a caller can log, serialize, or hang off a model result: the best program, the top elites with their coordinates and a size-capped copy of their source, the language-model bill, the run counters, and where the checkpoint was written. Building it never re-reads the archives, so it stays valid after the engine is disposed.

Ordering is deterministic and direction-aware: elites are sorted by quality in the archive’s optimisation direction, unscored entries last, ties broken by genome identity, so the same run produces the same list on every machine. ArchiveCount is the number of filled cells across every island — the search’s coverage — while Elites holds only the top includeEliteSourceCount of them, because a full archive can hold thousands of programs.

Constructors

Constructor Summary
ProgramEvolutionResult(EvolutionStopReason stopReason, string stateHash, EvolutionRunCounters counters, EvolutionOptimizationDirection direction, ProgramGenome bestProgram, double? bestQuality, IReadOnlyDictionary<string, double> bestDescriptors, IReadOnlyList<ProgramEvolutionElite> elites, int archiveCount, int islandCount, ProgramEvolutionLlmUsage llmUsage, string checkpointPath) Initializes a run summary.

Properties

Property Summary
EvolutionOptimizationDirection Direction { get; } Gets whether higher or lower quality values are better.
EvolutionRunCounters Counters { get; } Gets how many proposals, evaluation attempts, and completions the run recorded.
EvolutionStopReason StopReason { get; } Gets why the run stopped.
IReadOnlyDictionary<string, double> BestDescriptors { get; } Gets the best program’s archive coordinates; empty when none were recorded.
IReadOnlyList<ProgramEvolutionElite> Elites { get; } Gets the retained elites, best first, each with a bounded copy of its source.
ProgramEvolutionLlmUsage LlmUsage { get; } Gets the language-model totals; Empty when none were used.
ProgramGenome BestProgram { get; } Gets the best program found, or null when nothing was archived.
bool HasBestProgram { get; } Gets whether the run archived at least one program.
double? BestQuality { get; } Gets the best program’s score, or null when there is none.
int ArchiveCount { get; } Gets how many archive cells were filled across every island.
int IslandCount { get; } Gets how many islands the run used.
string CheckpointPath { get; } Gets where the run’s checkpoint was written, or null when checkpointing was off.
string StateHash { get; } Gets the engine’s deterministic state hash; equal hashes mean two runs were identical.

Methods

Method Summary
IReadOnlyList<ProgramEvolutionElite> TopBy(string metric, int count, EvolutionOptimizationDirection? direction) Returns the retained elites that scored best on a named metric, best first.
IReadOnlyList<string> MetricNames() Returns every metric name any retained elite reported, ordered for stable display.
ProgramEvolutionElite BestBy(string metric, EvolutionOptimizationDirection? direction) Returns the retained elite that scored best on a named metric.
ProgramEvolutionResult Create(EvolutionRunResult<ProgramGenome> runResult, ProgramEvolutionLlmUsage llmUsage, string checkpointPath, int includeEliteSourceCount, int maxEliteSourceChars) Summarizes a finished engine run, bounding the retained program text.
ProgramEvolutionResult Create(EvolutionRunResult<ProgramGenome> runResult, ProgramEvolutionOptions options, ProgramEvolutionLlmUsage llmUsage, string checkpointPath) Summarizes a finished engine run using the retention limits held on the run’s options.
string ToString() Returns a description that never echoes program text.

Fields

Field Summary
int DefaultEliteCount The default number of elites whose bounded source is retained.
int DefaultEliteSourceChars The default per-elite source bound, in characters.