oqp.library.symmetry
Backend-free symmetry utilities for one-electron diagnostics.
This module currently provides metadata-only diagnostics used by the symmetry
planning gates. It does not change SCF/integral/response execution behavior.
Classes
Functions
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Module Contents
- class OneElectronBlockLeakSummary
Normalized summary payload for one-electron block leakage checks.
- max_off_block_abs: float
- max_off_block_indices: list[tuple[int, int]]
- off_block_element_count: int
- within_tolerance: bool
- orthogonality_ok: bool
- orthogonality_max_deviation: float
- status: str
- as_dict() dict[str, Any]
- one_electron_block_diagnostics(matrix: Any, symmetry_adapted_transform: Any, basis_labels: Iterable[str], tolerance: float = 1e-06) dict[str, Any]
Compute off-block leakage diagnostics in a symmetry-adapted basis. :param matrix: One-electron matrix (overlap or core-Hamiltonian like). :param symmetry_adapted_transform: AO-space transformation matrix to symmetry-adapted AO basis. :param basis_labels: Per-AO symmetry labels in the transformed basis. :param tolerance: Off-block absolute-coupling tolerance.
- update_one_electron_block_diagnostics(symmetry_metadata: Mapping[str, Any] | None, matrices: Mapping[str, Any], symmetry_adapted_transform: Any, basis_labels: Iterable[str], tolerance: float = 1e-06) dict[str, Any]
Attach named one-electron diagnostics under ``symmetry_metadata['one_electron_block_diagnostics']``. This is metadata-only and intentionally does not enable any symmetry acceleration behavior.
- build_symmetry_adapted_transform(shells: Iterable[Any], operations: Iterable[Mapping[str, Any]], character_table: Mapping[str, Iterable[int]]) tuple[numpy.ndarray, list[str]]
Build an orthogonal symmetry-adapted AO transform with irrep labels. :param shells: Shell specs as (atom_index, l) pairs or {'atom','l'} mappings, Cartesian s/p/d only, in AO order. :param operations: Abelian-group operations from ``symmetry_detect.detect_point_group`` (``operations`` payload), in character-table column order. :param character_table: Irrep -> characters mapping matching the operation order. :returns: Orthogonal (n_ao, n_ao) transform whose columns are SALCs, and the per-column irrep labels. :rtype: (U, labels)
- assign_mo_irreps(mo_coefficients: Any, overlap: Any, shells: Iterable[Any], operations: Iterable[Mapping[str, Any]], character_table: Mapping[str, Iterable[int]], tolerance: float = 0.0001, matrix_key: str = 'matrix') dict[str, Any]
Assign abelian irrep labels to molecular orbitals (metadata only). For each MO ``m`` the character under operation ``O`` is ``chi(O) = <m|S O|m> / <m|S|m>``; the MO gets the irrep whose character row matches within ``tolerance``, otherwise the label 'mixed'. ``matrix_key`` selects which operation matrix to use; pass ``'matrix_input_frame'`` when the MO coefficients live in the original input coordinates rather than the standard orientation.
- build_reduction_maps(shells: Iterable[Any], operations: Iterable[Mapping[str, Any]]) dict[str, Any]
Shell/AO symmetry maps for integral reductions (Gate A, metadata only). Valid in the standard orientation, where every abelian operation is a signed shell permutation: requires sign-diagonal operation matrices (the ``matrix`` payload of ``symmetry_detect``). Returns per-operation shell permutations and per-AO sign vectors, plus shell orbit representatives and orbit sizes for petite-list iteration.
- build_full_group_blocks(shells: Iterable[Any], operations: Iterable[Mapping[str, Any]]) dict[str, Any]
Shell map and dense per-shell operation blocks for the full group. Generalizes the petite-list staging beyond sign-diagonal (abelian) operations: every operation contributes its shell permutation plus a dense (size x size) component-mixing block per shell, flattened column-major (Fortran order), concatenated shell-by-shell then op-by-op.
- product_irrep(labels: Iterable[str], character_table: Mapping[str, Iterable[int]]) str
Direct product of abelian irreps, e.g. b1 x b2 -> a2 in C2v. Returns 'mixed' if any input label is not in the table (e.g. a symmetry-broken 'mixed' orbital).
- assign_state_irreps(amplitudes: Any, occ_coefficients: Any, vir_coefficients: Any, overlap: Any, shells: Iterable[Any], operations: Iterable[Mapping[str, Any]], character_table: Mapping[str, Iterable[int]], reference_labels: Iterable[str] = (), tolerance: float = 0.001, matrix_key: str = 'matrix') dict[str, Any]
Assign abelian irrep labels to excitation amplitudes (metadata only). ``amplitudes`` holds X_ia per state, shape (n_states, n_occ, n_vir), where i indexes the occupied set described by ``occ_coefficients`` (n_ao, n_occ) and a the virtual set of ``vir_coefficients`` (n_ao, n_vir). The transition character per operation is ``<X, U X V^T> / <X, X>`` with ``U/V`` the MO representations of the operation in the two sets. The total state irrep is the direct product of the transition irrep with ``reference_labels`` (e.g. the SOMOs of a spin-flip reference); for a closed-shell reference leave it empty.
- assign_mode_irreps(modes: Any, operations: Iterable[Mapping[str, Any]], character_table: Mapping[str, Iterable[int]], tolerance: float = 0.001, matrix_key: str = 'matrix') dict[str, Any]
Assign abelian irrep labels to Cartesian normal modes (metadata only). ``modes`` holds one mode per row with 3*natom displacement components. Each operation acts by permuting atoms and rotating the per-atom displacement vectors; the character is ``<v|T v> / <v|v>``. Use ``matrix_key='matrix_input_frame'`` for modes in input coordinates.