Skip to content

Calculation key

calculation_key says when two inputs are the same calculation: a store files each result under it, and a lookup by key returns a stored result only for the same calculation written the same way. It is computed from the input alone; which code produced a stored result is recorded with each run, not hashed into the key. The rules, and what is left out, are in Conventions.

from qcdata import calculation_key

key = calculation_key(prog_input)  # "k1:f996..."

qcdata.calculation_key

calculation_key(inp: FileInput | ProgramInput) -> str

Return the key under which a store files the calculation inp requests.

The key is "k1:" and the sha256 hex digest of the canonical JSON form of the input as given. It names the calculation only: which code produced a stored result (each program's numerics identity) is recorded with each run by the runner and the store, not hashed into the key. The canonical form has:

  • keys sorted;
  • numbers normalized: an integral float is written as an integer (100.0 as 100, -0.0 as 0), any other float in its shortest round-trip form;
  • fields at their default left out, so adding a field to qcdata never changes an old key;
  • coordinates in bohr rounded to 1e-10 and written as integers, atom order kept;
  • every other array field (a given Hessian, orbital coefficients) as {"array": shape, "dtype": dtype, "sha256": digest}, the digest of its C-order little-endian bytes: float64 with -0.0 as 0.0, integers in their own dtype. Arrays inside free-form values such as keywords stay JSON numbers;
  • attached files by the sha256 of their bytes (UTF-8 for text);
  • subprograms canonicalized the same way, in order.

Left out: extras at every level, structure identifiers, and the resource keywords threads, memory_gib and device_memory_gib at the top level of keywords, in the input and in every subprogram. Everything else counts, given and backend included. Spellings are not normalized: a synonym or a default written out explicitly gives another key.

Parameters:

Name Type Description Default
inp FileInput | ProgramInput

The input as given. A bare ProgramSpec is not a calculation; bind it to a structure with ProgramInput.from_spec first.

required

Returns:

Type Description
str

The key, "k1:" followed by 64 hex digits.

Raises:

Type Description
TypeError

inp is not an input, or it holds a value JSON cannot represent (a set, bytes outside files, a mapping with non-string keys).

ValueError

The input holds a non-finite number.

Source code in src/qcdata/key.py
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def calculation_key(inp: FileInput | ProgramInput) -> str:
    """Return the key under which a store files the calculation ``inp`` requests.

    The key is ``"k1:"`` and the sha256 hex digest of the canonical JSON form of the
    input as given. It names the calculation only: which code produced a stored result
    (each program's numerics identity) is recorded with each run by the runner and the
    store, not hashed into the key. The canonical form has:

    - keys sorted;
    - numbers normalized: an integral float is written as an integer (``100.0`` as
      ``100``, ``-0.0`` as ``0``), any other float in its shortest round-trip form;
    - fields at their default left out, so adding a field to qcdata never changes an
      old key;
    - coordinates in bohr rounded to 1e-10 and written as integers, atom order kept;
    - every other array field (a `given` Hessian, orbital coefficients) as
      ``{"array": shape, "dtype": dtype, "sha256": digest}``, the digest of its C-order
      little-endian bytes: float64 with ``-0.0`` as ``0.0``, integers in their own
      dtype. Arrays inside free-form values such as ``keywords`` stay JSON numbers;
    - attached files by the sha256 of their bytes (UTF-8 for text);
    - subprograms canonicalized the same way, in order.

    Left out: ``extras`` at every level, structure identifiers, and the resource
    keywords ``threads``, ``memory_gib`` and ``device_memory_gib`` at the top level of
    ``keywords``, in the input and in every subprogram. Everything else counts,
    ``given`` and ``backend`` included. Spellings are not normalized: a synonym or a
    default written out explicitly gives another key.

    Args:
        inp: The input as given. A bare `ProgramSpec` is not a calculation; bind it to
            a structure with `ProgramInput.from_spec` first.

    Returns:
        The key, ``"k1:"`` followed by 64 hex digits.

    Raises:
        TypeError: ``inp`` is not an input, or it holds a value JSON cannot represent
            (a set, bytes outside ``files``, a mapping with non-string keys).
        ValueError: The input holds a non-finite number.
    """
    if not isinstance(inp, FileInput) or (
        isinstance(inp, ProgramSpec) and not isinstance(inp, ProgramInput)
    ):
        raise TypeError(
            "A calculation key needs a ProgramInput or a FileInput, not "
            f"{type(inp).__name__}; bind a ProgramSpec with ProgramInput.from_spec."
        )
    text = json.dumps(
        _canonical_model(inp),
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=True,
        allow_nan=False,
    )
    return f"{_VERSION}:{hashlib.sha256(text.encode('ascii')).hexdigest()}"