oqp.utils.perf_levels

Centralised resolver for OpenQP's performance options and the ``perf`` preset.

Each performance knob is an ordinary **input key** (e.g. ``[scf] xc_c2f``,
``[tdhf] resp_cutoff``) backed by a field on the shared ``control`` struct -- there are
no environment variables involved. ``[input] perf = 0|1|2|3`` is a preset that fills in
those input keys (the ones the user left at the sentinel ``auto``) before the config is
pushed to the native library. An explicit input key always overrides the preset.

  perf = 0  strict reference / reproducible  -- every accelerator off, tightest cutoffs.
  perf = 1  recommended production (exact)   -- only exact, proven-helpful knobs:
                                                MRSF response cutoff 1e-8, z-vector
                                                warm-start (+ the always-on Fock digest).
  perf = 2  faster, tiny degradation         -- + coarse-to-fine XC grid + grad Schwarz
                                                cutoff 1e-8 (<=5e-7 a.u. on gradients).
  perf = 3  aggressive, degradation allowed  -- looser cutoffs traded for speed: grad
                                                1e-7 (~1e-5 a.u.), response 1e-6 (~few ueV).

The accelerators that the CPU benchmark found net-negative or experimental -- Phi-cache,
IncDFT, FP32 and progressive screening (pscreen) -- are NOT enabled by any preset (they
stay available as explicit input keys, e.g. for GPU XC or regimes not covered here).

Precedence (low -> high): control-struct default  <  perf preset  <  explicit input key.
An input key set to ``auto`` (its default) defers to the preset; any other value overrides
it. ``perf`` unset (-1) leaves every key at its default -> identical to legacy behaviour.

Attributes

UNSET

KNOBS

NEW_INPUT_KEYS

Functions

resolve(config, perf)

validate(config[, scf_conv, zv_conv])

format_report(perf, report, warns)

apply(config, perf[, scf_conv, zv_conv])

Module Contents

UNSET = -1
KNOBS = [('scf', 'xc_c2f', ['off', 'off', 'on', 'on']), ('scf', 'xc_phi_cache', ['off', 'off', 'off',...
NEW_INPUT_KEYS
resolve(config, perf)
Fill the perf input keys in ``config`` from the preset (in place).

A key is filled from the preset only when its value is the sentinel ``auto`` -- so an
explicit value (from the input file or a caller-supplied dict, even a fully
default-expanded one) always wins. Returns a list of (label, shown_value, source) with
source in {"input", "perf"}. ``perf`` unset -> no change, empty report.
validate(config, scf_conv=None, zv_conv=None)
Warnings for risky resolved settings (reads the post-resolution config).
format_report(perf, report, warns)
apply(config, perf, scf_conv=None, zv_conv=None)
Resolve into ``config`` (in place) + validate; return (report, warns).