EvolutionOptions
Options & Configuration · AiDotNet.Configuration
The user-facing control panel for an evolution run: budgets, islands, the archive grid, and persistence.
For Beginners
Evolutionary search keeps a population of candidate solutions, changes them, scores
them, and keeps the good ones. The budget settings say how long to search: MaxEvaluationAttempts
caps how many times your scoring function actually runs, and TimeLimit caps wall-clock time.
Seed makes a run repeatable — the same seed and settings always give the same answer.
Descriptors is the interesting one: each entry is a measurable property of a candidate (its size,
its depth, how long it takes) and the search keeps the best candidate found for every combination of those
properties, so you end up with a map of good and different answers instead of one winner. Start with the
defaults, add one or two descriptors, and raise the budgets once your scoring function is stable.
How It Works
This is the options object AiModelBuilder.ConfigureEvolution takes. It carries every knob the engine
itself understands and three groups the engine cannot describe on its own: the behaviour axes the archive maps
candidates onto (Descriptors, ArchiveDirection, ArchiveCapacity), where
the run’s files go (OutputDirectory, CheckpointDirectory,
RetainOutput), and what is written to a trace (Trace). Everything is validated when
SnapshotAndValidate runs, which the builder does at configure time, so a misconfigured search fails
on the line that configured it rather than after the first evaluation.
SnapshotAndValidate returns an independent copy. The builder keeps the copy, so mutating the object
you passed in after configuring cannot change a run that is already under way — the same defensive-copy contract
the engine applies to its own options.
Defaults are deliberately cautious: one island, no retries, no timeout, no checkpointing, no tracing, caching on.
A first run should be cheap and free of surprises. CreateOpenEvolveDefaults is the opt-in that
switches on everything the reference OpenEvolve implementation enables out of the box.
Constructors
| Constructor | Summary |
|---|---|
EvolutionOptions() |
Properties
| Property | Summary |
|---|---|
EvolutionArtifactOptions Artifacts { get; set; } |
Gets or sets retention and sanitizing of untrusted evaluator artifacts; disabled by default. |
EvolutionCascadeOptions Cascade { get; set; } |
Gets or sets staged (cascade) evaluation; disabled by default. |
EvolutionDispatchMode Dispatch { get; set; } |
Gets or sets whether evaluations run in fixed batches or in a continuously refilled window. |
EvolutionEarlyStoppingOptions EarlyStopping { get; set; } |
Gets or sets plateau-based early stopping; disabled by default. |
EvolutionExecutionMode ExecutionMode { get; set; } |
Gets or sets whether commits are ordered deterministically or by completion. |
EvolutionFailurePolicy FailurePolicy { get; set; } |
Gets or sets whether a recoverable candidate failure stops the whole run. |
EvolutionIslandAssignmentStrategy IslandAssignment { get; set; } |
Gets or sets how a new proposal is assigned to an island. |
EvolutionMigrationTopology MigrationTopology { get; set; } |
Gets or sets the island graph migrations follow when the engine builds the migration policy. |
EvolutionMigrationTrigger MigrationTrigger { get; set; } |
Gets or sets which unit MigrationInterval counts. |
EvolutionOptimizationDirection ArchiveDirection { get; set; } |
Gets or sets whether a higher or a lower quality is better. |
EvolutionRetryStatuses RetryOn { get; set; } |
Gets or sets which failure-like outcomes are eligible for another attempt. |
EvolutionSelectionOptions Selection { get; set; } |
Gets or sets the branch ratios and inspiration mix a ratio-based selection policy uses. |
EvolutionSelectionPolicyKind SelectionPolicy { get; set; } |
Gets or sets which built-in selection policy the engine builds when none is supplied. |
EvolutionTraceOptions Trace { get; set; } |
Gets or sets what a run records to its trace file; disabled by default. |
IList<EvolutionDescriptorDefinition> Descriptors { get; set; } |
Gets or sets the behaviour axes the archive maps candidates onto. |
TimeSpan RetryBaseDelay { get; set; } |
Gets or sets the pause before a retry round; zero, the default, retries immediately. |
TimeSpan? EvaluationGracePeriod { get; set; } |
Gets or sets how long past EvaluationTimeout the run waits before abandoning a call. |
TimeSpan? EvaluationTimeout { get; set; } |
Gets or sets a cooperative time limit for one evaluator attempt. |
TimeSpan? TimeLimit { get; set; } |
Gets or sets a wall-clock limit for the whole run. |
bool DeduplicateFailedCandidates { get; set; } |
Gets or sets whether a candidate that failed stays permanently deduplicated. |
bool EnableEvaluationCache { get; set; } |
Gets or sets whether a completed evaluation is reused when the same candidate appears again. |
bool PreventRepeatedMigration { get; set; } |
Gets or sets whether a genome may migrate only once; by default it may migrate repeatedly. |
bool Resume { get; set; } |
Gets or sets whether a compatible checkpoint is loaded before new candidates are proposed. |
bool RetainOutput { get; set; } |
Gets or sets whether a directory the builder derived for this run survives the run. |
double MigrationRate { get; set; } |
Gets or sets the fraction of a destination island’s cells one migration may overwrite; zero means no cap. |
double NoveltyDistanceThreshold { get; set; } |
Gets or sets the structural novelty threshold; zero disables the pre-evaluation novelty gate. |
double RetryBackoffMultiplier { get; set; } |
Gets or sets the factor applied to RetryBaseDelay for each further attempt. |
double? TargetQuality { get; set; } |
Gets or sets a quality that ends the run as soon as an elite reaches it. |
int ArchiveCapacity { get; set; } |
Gets or sets the maximum number of filled cells one island keeps; zero means unbounded. |
int CheckpointInterval { get; set; } |
Gets or sets how many committed evaluations pass between checkpoints; zero disables periodic saves. |
int GlobalEliteCount { get; set; } |
Gets or sets the size of the cross-island elite index; zero disables it. |
int HistorySize { get; set; } |
Gets or sets how many past evaluations each island remembers beyond its elites; zero disables it. |
int InspirationCount { get; set; } |
Gets or sets how many inspiration elites are handed to the variation operator. |
int IslandCount { get; set; } |
Gets or sets how many independent archives the population is split across. |
int MaxDegreeOfParallelism { get; set; } |
Gets or sets how many evaluator calls may run at once. |
int MaxEvaluationAttempts { get; set; } |
Gets or sets the maximum number of evaluator attempts, retries included. |
int MaxGenerations { get; set; } |
Gets or sets the maximum number of non-seed variation proposals. |
int MaxInFlight { get; set; } |
Gets or sets how many evaluations may be in flight at once; zero follows the worker count. |
int MaxInFlightPerIsland { get; set; } |
Gets or sets how many evaluations one island may have in flight; zero means no per-island limit. |
int MaxProposals { get; set; } |
Gets or sets the maximum number of proposals, duplicates and rejections included. |
int MaxRetainedFailures { get; set; } |
Gets or sets how many failure diagnostics a run keeps. |
int MaxRetries { get; set; } |
Gets or sets how many further attempts a failed evaluation may have. |
int MigrantsPerIsland { get; set; } |
Gets or sets how many elites each island contributes to a migration round. |
int MigrationInterval { get; set; } |
Gets or sets how many units pass between migrations; zero disables migration. |
int ProposalBatchSize { get; set; } |
Gets or sets how many proposals form one logical batch, independent of worker count. |
long MaximumArchiveGridCells { get; set; } |
Gets or sets the ceiling on the archive’s total cell count, which guards against an unusable grid. |
string CheckpointDirectory { get; set; } |
Gets or sets the directory the checkpoint file goes in, overriding the one OutputDirectory derives. |
string OutputDirectory { get; set; } |
Gets or sets the directory this run’s checkpoint, trace, and artifact paths are derived from. |
string QualityDescriptorName { get; set; } |
Gets or sets the descriptor filled from a completed evaluation’s quality; null disables it. |
string RunId { get; set; } |
Gets or sets the stable run identifier that names this run’s checkpoint and trace files. |
ulong Seed { get; set; } |
Gets or sets the root seed every random stream in the run is derived from. |
Methods
| Method | Summary |
|---|---|
EvolutionOptions CreateOpenEvolveDefaults() |
Creates options equivalent to the shipped defaults of OpenEvolve 0.3.2. |
EvolutionOptions SnapshotAndValidate() |
Validates every value and returns an independent copy that later mutation cannot reach. |