Rigorous.RunRegistry

Rigorous.RunRegistry#

Rigorous.RunRegistry#

Disk-side breadcrumbs for rigorous optimization runs.

Why this exists#

A rigorous optimization can run for hours. Once launched (especially via compare_optimization_paths with monitor=False), the parent Python kernel may be busy and unable to answer “what is running right now?” from outside. External observers (a second VS Code session, an AI assistant, a shell) need an out-of-band way to find live runs without parsing process trees or guessing folder names.

The registry solves this by writing two artifacts:

  1. A per-run RUN_MANIFEST.json inside each analysis_folder (and, once known, inside the legacy work_folder too), recording method / niter / pid / start time / paths.

  2. An append-only ~/.molass/runs.jsonl global registry — one line per run start. Cheap to scan; never rewritten.

Both files are best-effort: any I/O error is swallowed so the optimizer itself never fails because of bookkeeping.

Public helpers#

write_run_manifest(folder, **fields)#

Write RUN_MANIFEST.json into folder and append a registry line.

All errors are swallowed. Returns the manifest dict on success, None on failure.

Parameters:

  • folder (str) – Absolute path of the folder to drop the manifest into. Must already exist.

  • **fields – Arbitrary JSON-serializable keys merged into the manifest. Common keys: method, niter, in_process, monitor, analysis_folder, role (‘analysis’ or ‘work’).

update_run_manifest(folder, **fields)#

Merge fields into an existing manifest in folder.

Creates the file if missing. Errors swallowed.

read_manifest(folder)#

Return the manifest dict in folder, or None if absent / unreadable.

locate_recent_runs(since_minutes=60, registry_path=None)#

Return a list of recently-started runs (newest first).

Reads the global registry at ~/.molass/runs.jsonl and filters by start time. Each entry is augmented with exists (folder still on disk) and manifest (the live manifest dict, if readable — may contain status fields like subprocess_returncode written later).

Parameters:

  • since_minutes (float, optional) – Window for “recent”. Default 60.

  • registry_path (str, optional) – Override registry location (mainly for tests).

Returns:

Each dict has at least folder, start_time, pid, method, niter, role, exists, manifest.

Return type:

list of dict