parasolpy.borg_runtime

Parsing and analysis of Borg MOEA runtime files.

A Borg runtime file records periodic snapshots of the evolving archive. Each snapshot begins with a header block (“Function evaluations N”, recombination operator probabilities, improvement/restart counts, population and archive sizes) followed by one whitespace-delimited row per archive member. The first field of each data row is the solution ID, which equals the function evaluation (NFE) at which the solution was created.

These helpers reconstruct the birth and death of every archived solution, which supports questions like “how long do solutions survive in the archive?” and “which saved solution files should have been cleaned up?” (see leaked_model_ids). Use parasolpy.plotting.plot_archive_lifespans to visualize the result.

Functions

leaked_model_ids(models_dir, spans[, pattern])	Find saved solution-model files whose IDs appear in no snapshot.
parse_borg_runtime(runtime_path)	Parse a Borg runtime file into archive snapshots.
parse_borg_runtime_metadata(runtime_path)	Parse per-snapshot header metadata from a Borg runtime file.
solution_lifespans(snapshots)	Build a per-solution lifespan table from archive snapshots.

parasolpy.borg_runtime.parse_borg_runtime(runtime_path)

Parse a Borg runtime file into archive snapshots.

Header lines start with a word (for example “Improvements 41”) while data rows start with an integer solution ID, which is how the two are told apart.

Parameters:

runtime_path (str | PathLike) – Path to the Borg runtime text file.

Returns:

One (nfe, ids) pair per snapshot, in file order, where nfe is the function-evaluation count of the snapshot and ids is the set of solution IDs in the archive at that point.

Return type:

list of tuple

parasolpy.borg_runtime.parse_borg_runtime_metadata(runtime_path)

Parse per-snapshot header metadata from a Borg runtime file.

Parameters:

runtime_path (str | PathLike) – Path to the Borg runtime text file.

Returns:

Indexed by nfe with columns improvements, restarts, population_size, and archive_size.

Return type:

pd.DataFrame

parasolpy.borg_runtime.solution_lifespans(snapshots)

Build a per-solution lifespan table from archive snapshots.

A solution’s ID is the NFE at which it was born, so birth always equals the ID. Snapshots are periodic, so a removed solution’s true death lies between the last snapshot that contains it and the next snapshot; by convention death is the next snapshot’s NFE (or the final NFE for solutions still present at the end of the run).

Parameters:

snapshots (list of tuple) – (nfe, ids) pairs from parse_borg_runtime().

Returns:

Indexed by solution id with columns birth, death, and in_final_archive.

Return type:

pd.DataFrame

parasolpy.borg_runtime.leaked_model_ids(models_dir, spans, pattern='Solution*.mdl')

Find saved solution-model files whose IDs appear in no snapshot.

Borg-RiverWare saves a model file per archived solution and is expected to delete it when the solution is removed from the archive. Solutions that enter and leave the archive between two runtime snapshots (for example during a restart, when no runtime output is written) are invisible to snapshot-based cleanup and their files leak.

Parameters:

• models_dir (str | PathLike) – Folder containing saved model files named with the solution ID (for example Solution123.mdl).

• spans (pd.DataFrame) – Output of solution_lifespans().

• pattern (str, optional) – Glob pattern for model files.

Returns:

Sorted solution IDs with a file on disk but no record in any runtime snapshot.

Return type:

list of int