ProgramRunOutputWriter
Models & Types · AiDotNet.Evolution.Programs.Outputs
Writes the best program of a run to disk, with an info document describing it.
For Beginners
When a search finishes, this is what leaves the winning program on your disk instead
of only in memory. Create one with an output directory, then either call it yourself or - more usually - hand it
to ProgramRunOutputObserver, which calls it at every checkpoint and once more when the run stops.
Afterwards, best/best_program.py is the program and best/best_program_info.json tells you how it
scored and where it came from.
How It Works
The layout matches the reference OpenEvolve controller
(openevolve/controller.py``_save_checkpoint and _save_best_program): a checkpoint snapshot
goes to checkpoints/checkpoint_<n>/ and the final answer to best/, each holding
best_program with the extension of its language plus best_program_info.json. The upstream info
document carries the program’s identity, generation, iteration, metrics, language and timestamps; this one
carries all of those and adds what upstream’s Program record has no room for - the archive cell and the
raw descriptor coordinates behind it, the full lineage including operator, island and inspirations, the
evaluation cost and cache status, and the task, evaluator and configuration hashes that say which code and
settings produced the score.
Both files are written atomically: each is serialized to a temporary file in the destination directory, flushed
to disk, and swapped into place, so an interrupted write leaves the previous snapshot rather than a truncated
one. Upstream writes both with a plain open(...,"w"), which leaves a half-written program behind if the
process dies mid-write - the exact moment a caller most wants the file to be trustworthy.
The program text is model-generated and untrusted. It is written as opaque UTF-8 bytes, never executed or
interpreted, and cut to MaxSourceBytes on a character boundary so a
truncated file is still valid UTF-8; the info document records both the original size and the truncation, so a
bounded file never silently passes for a complete one.
Constructors
| Constructor | Summary |
|---|---|
ProgramRunOutputWriter(string outputDirectory, ProgramRunOutputOptions options) |
Initializes a writer, creating the output directory when it does not exist. |
Properties
| Property | Summary |
|---|---|
int WrittenProgramCount { get; } |
Gets how many per-candidate files this writer has written, rewrites included. |
string OutputDirectory { get; } |
Gets the absolute directory that holds the run’s output tree. |
Methods
| Method | Summary |
|---|---|
ProgramRunOutputOptions GetOptions() |
Gets an independent copy of the settings this writer was validated with. |
ProgramRunOutputRecord Write(EvolutionArchiveEntry<ProgramGenome> best, ProgramRunOutputTrigger trigger, long ordinal, string note) |
Writes the best program and its info document to the directory the trigger selects. |
ProgramRunOutputRecord WriteCheckpoint(EvolutionArchiveEntry<ProgramGenome> best, long ordinal, string note) |
Writes a snapshot into a numbered checkpoint directory. |
ProgramRunOutputRecord WriteFinal(EvolutionArchiveEntry<ProgramGenome> best, string note) |
Writes the run’s final answer into the best directory. |
string GetDirectory(ProgramRunOutputTrigger trigger, long ordinal) |
Computes the directory one write would target, whether or not it exists. |
string WriteProgram(EvolutionCandidate<ProgramGenome> candidate, EvolutionEvaluation evaluation, EvolutionCellKey cell) |
Writes one evaluated candidate as its own file, program text and all. |