Jobs and Results

CADDForge writes each workflow execution into a standardized run directory.

Example layout:

runs/
  2026-05-05/
    <job-id>/
      config.json
      config.yaml          # optional tool-specific copy
      metadata.json
      stdout.log
      stderr.log
      results/
        results.json
        result_record.json
        tool_specific/

Metadata

Core saves config.json as the canonical restart configuration. A tool may also write a YAML copy; preserve the original submitted YAML alongside the run for provenance.

metadata.json should capture job identity, tool name, user, timestamps, backend, versions, and key runtime parameters when available.

Registry

The job registry maps job IDs to status and paths. CLI commands such as status and logs should use the shared registry helpers rather than plugin-specific lookup code.

Registry access is serialized with a filesystem lock so controller-side updates remain consistent under multiprocess fan-out and shared filesystems. Slurm worker payloads do not write to the shared registry; status refresh reconciles scheduler state with the job-local metadata and canonical result records. A completed scientific result is therefore not overwritten by a conflicting terminal scheduler state.

Composite and repeat workflows may record parent-child relationships. Repeat parents are refreshed through their children and publish replicas_manifest.json plus aggregate completion metrics once all children become terminal.

Loading results

Use the core execution helpers to load canonical results:

from caddforge.core.execution import load_result_for_job

result = load_result_for_job(job)

Tool-specific summaries may exist. result_record.json takes precedence when present; the loader also accepts a canonical results.json from older or simpler workflows. Use load_result_for_job to select the record instead of loading a tool-specific summary as though it were a CADDForge result.