oqp.utils.regression

Single source of truth for what the example test suite regression-checks.

Historically ``Molecule.check_ref`` compared *every* key in a reference JSON
except a hand-maintained ``skip_keys`` blocklist. That silently failed to test
quantities that live in sidecar files (IR/Raman intensities) or that were only
stored under internal ``OQP::`` arrays (non-adiabatic couplings), and nothing
flagged a newly added example whose reference was missing a value it should
carry.

This module replaces that with an explicit *allowlist* registry. Each entry
declares a physics quantity, where it lives, the runtypes/methods/properties it
applies to, and whether it is required (must be present and non-empty). The same
registry drives three things so they cannot drift apart:

  * ``keys_to_compare``  -> what ``check_ref`` compares
  * ``lean_keep``        -> what ``save_data(lean=True)`` keeps
  * ``missing_required`` -> the validation gate run when examples are added

Adding a new regression value is a one-line entry here.

Attributes

`GRAD_RUNTYPES`
`GEOMETRY_UNSTABLE_RUNTYPES`
`IDENTITY_KEYS`
`METADATA_KEYS`
`REGISTRY`
`EXEMPT_FLAGS`
`KNOWN_UNCOVERED`

Classes

RegKey

Functions

`keys_to_compare`(runtype[, excited, props])
`missing_required`(present_nonempty, runtype[, excited, ...])
`lean_keep`(key)
`is_phase_invariant`(key)
`skip_sub_keys`(key)
`sidecar_keys`(runtype[, excited, props])
`validate_examples`(examples_dir)
`feature_coverage`(examples_dir[, schema_file])

Module Contents

GRAD_RUNTYPES

GEOMETRY_UNSTABLE_RUNTYPES

IDENTITY_KEYS

METADATA_KEYS

class RegKey

One regression quantity.

key: str

runtypes: object = '*'

required: bool = False

source: str = 'primary'

sidecar_field: str | None = None

phase_invariant: bool = False

skip_sub: tuple = ()

rtol: float = 0.0

needs_excited: bool = False

needs_prop: str | None = None

exclude_runtypes: frozenset

field()

The field name to read from its source (sidecar field or the key).

applies(runtype, excited, props)

REGISTRY

keys_to_compare(runtype, excited=False, props=None)

Registry keys that ``check_ref`` should compare in this context.

missing_required(present_nonempty, runtype, excited=False, props=None)

Required registry keys absent or empty in this reference -> gate failures.

``present_nonempty`` is the set of keys that exist and are non-empty in the
reference (primary + sidecar merged).

lean_keep(key)

True if a JSON key survives a lean (test-reference) dump.

Keeps identity, metadata, and every registered physics key; drops internal
``OQP::`` arrays and anything else not declared a regression target.

is_phase_invariant(key)

skip_sub_keys(key)

sidecar_keys(runtype, excited=False, props=None)

Registry keys sourced from the .hess.json sidecar in this context.

validate_examples(examples_dir)

Validate every example reference under ``examples_dir``.

Returns a list of ``(relative_inp_path, [missing_required_keys])`` for
references that lack a required regression value for their runtype/method/
properties. An empty list means every example carries everything the
registry says it must -- this is the gate that fails when a new example (or
a newly registered value) is added without its reference value.

EXEMPT_FLAGS

KNOWN_UNCOVERED

feature_coverage(examples_dir, schema_file=None)

Check that every opt-in feature flag is exercised by an example.

Returns ``(failures, grandfathered)``:
  * ``failures``     -- [(flag, 'no example exercises it')] for flags that
                        are neither exempt nor known-uncovered -> gate fails.
  * ``grandfathered``-- [(flag, reason)] tracked gaps that still need a test.