Provenance (Developer Reference)

Overview

Every zppy run writes two provenance files for each invocation:

File	Contents
provenance.<ts_utc>.cfg	A verbatim copy of the user-supplied .cfg configuration file.
provenance.<ts_utc>.settings	Key-value metadata about the run: case_name, machine, hpc_username, and diagnostics_url. Only written when at least one field resolves to a non-empty value.

Both files are written to the script directory (<output>/post/scripts/) and mirrored under <www>/<case>/ when that directory is accessible.

The .settings file format

One key = value pair per line, e.g.:

case_name = v3.LR.historical_0051
machine = pm-cpu
hpc_username = ac.zhang40
diagnostics_url = https://portal.nersc.gov/cfs/e3sm/ac.zhang40/zppy_demo/v3.LR.historical_0051

Fields with empty or None values are omitted.

Implementation

• Python module: zppy/provenance.py

• Called from: zppy/__main__.py

zppy/provenance.py exports four public helpers:

parse_env_case_xml(input_dir)

Reads <input_dir>/case_scripts/env_case.xml and returns a dict with any of case_name, machine, and hpc_username that were successfully parsed. Degrades gracefully on a missing file, missing entries, or malformed XML (logs a warning and returns a partial or empty dict).

build_diagnostics_url(www, case, machine_info)

Constructs the public web-portal URL for the run’s diagnostics output using the machine’s web_portal base_path and base_url from the mache MachineInfo config. Returns None when www is empty, when www is not under the machine’s base_path, or when the machine config lacks web_portal entries.

write_provenance_settings(settings_path, extras)

Writes the provenance.settings file from a dict, skipping empty and None values. Does nothing if no usable entries remain.

build_provenance_extras(config_default, machine_info)

Orchestrates the other three functions. Reads case_name, machine, and hpc_username from env_case.xml under cfg["default"]["input"], builds diagnostics_url from cfg["default"]["www"] and cfg["default"]["case"], and returns the assembled extras dict. Logs a warning if the case name in the cfg disagrees with the value in env_case.xml (the XML value is treated as authoritative).

Unit tests

tests/test_zppy_provenance.py covers all four public helpers, including missing-file, partial-entry, malformed-XML, unsupported-machine, and case-mismatch scenarios.