oqp.molecule.molecule

OQP molecule class

Attributes

`LEAN_JSON_ENV`
`HESSIAN_CACHE_VERSION`

Classes

Molecule

Functions

`compare_data`(data_1, data_2[, skip_sub, rtol])
`get_coord`(xyz, nat)
`string_config`(config)
`list2string`(in_list)

Module Contents

LEAN_JSON_ENV = 'OQP_LEAN_JSON'

HESSIAN_CACHE_VERSION = 2

class Molecule(project_name, input_file, log, xyz=None, elem=None, mass=None, charge=0, mult=1, silent=0, idx=1)

OQP molecule representation in python

mpi_manager

usempi = True

silent = 0

idx = 1

xyz = None

elem = None

mass = None

charge = 0

mult = 1

control = None

mol_energy = None

data = None

config

project_name

input_file

log

log_path

energies = None

grads = None

dcm = []

nac = []

soc = []

freqs

hessian

hessian_metadata

modes

inertia

infrared_intensities

raman_activities

vibrational_intensity_metadata

infrared_mode_dipole_derivatives

raman_mode_polarizability_derivatives

symmetry_metadata

mrsf_ekt_results_by_kind

tag = ['OQP::DM_A', 'OQP::DM_B', 'OQP::FOCK_A', 'OQP::FOCK_B', 'OQP::E_MO_A', 'OQP::E_MO_B',...

skip_tag

config_tag

start_time = None

back_door = None

get_atoms()

Get read-only atoms

initialize_symmetry_metadata()

label_molecular_orbitals()

Assign abelian irrep labels to converged MOs (metadata only, non-fatal).

Stores the result under ``symmetry_metadata['mo_labels']``; never
changes SCF/integral/response behavior.

reorient_for_integral_symmetry()

GAMESS-style reorientation to the standard frame (geometry only).

Call before the guess/basis stage; ``stage_integral_symmetry_maps``
completes the activation once the basis is available. No-op unless
``[symmetry] use_integral_symmetry`` is enabled.

stage_integral_symmetry_maps()

Stage petite-list maps for the Fortran SCF (requires the basis).

Fail-safe: any inconsistency leaves the run on the C1 path with the
reason recorded in the metadata.

stage_response_symmetry()

Stage per-pair irrep indices for response-space blocking.

Builds OQP::sym_pair_irrep (1-based irrep index per excitation
pair, occupied index fastest) from the converged MO labels. Only
acts when ``use_response_symmetry`` is enabled; bails to the
unblocked solver on any 'mixed' orbital or inconsistency.

label_excited_states()

Assign abelian irrep labels to TD excited states (metadata only).

Supports tda/rpa (closed-shell, occ/vir from VEC_MO_A) and sf/mrsf
(occ from alpha, vir from beta MOs; total symmetry includes the
direct product of the reference SOMO irreps). Stores results under
``symmetry_metadata['state_labels']``; never fatal.

symmetrize_gradient(grads)

Project gradients onto the totally symmetric component.

Valid in the standard orientation when the petite reduction is
active: g'_a = (1/|G|) sum_op M_op^T g_{perm_op(a)}. Exact for the
skeleton two-electron gradient and a noise-cleaner for the rest.

label_normal_modes()

Assign abelian irrep labels to normal modes (metadata only, non-fatal).

Stores the result under ``symmetry_metadata['mode_labels']``.

get_mass()

Get read-only molar mass

get_system()

Get read-only coordinates

get_scf_energy(component=None)

Retrieve SCF (Self-Consistent Field) energy components.

This method provides convenient access to individual or all energy
terms computed during an SCF procedure. If no component is specified,
the total SCF energy is returned.

:param component: The energy component to retrieve. Supported options are:

                  - ``None`` (default): Returns only the total SCF energy.
                  - ``"all"``: Returns a dictionary containing all available
                    energy components.
                  - One of the following component names:
                      * "energy"  — total SCF energy
                      * "psinrm"  — wavefunction norm
                      * "ehf1"    — Hartree-Fock energy (one-electron)
                      * "vee"     — electron-electron repulsion energy
                      * "nenergy" — nuclear energy contribution
                      * "vne"     — electron-nucleus attraction energy
                      * "vnn"     — nucleus-nucleus repulsion energy
                      * "vtot"    — total potential energy
                      * "tkin"    — kinetic energy
                      * "virial"  — virial ratio
:type component: str, optional

:returns:

          - If `component` is None, returns a single float (total SCF energy).
          - If `component` is "all", returns a dictionary with all energy components.
          - If `component` corresponds to a specific component, returns that component as a float.
:rtype: float or dict

:raises ValueError: If the provided `component` does not match any of the known energy components.

.. rubric:: Examples

>>> mol.get_scf_energy()
-75.98327432

>>> mol.get_scf_energy("tkin")
37.420192

>>> mol.get_scf_energy("all")
{
    'energy': -75.98327432,
    'psinrm': 0.999999,
    'ehf1': -72.3123,
    'vee': 18.2034,
    'nenergy': -80.000,
    'vne': -85.6214,
    'vnn': 5.6214,
    'vtot': -67.4180,
    'tkin': 37.4202,
    'virial': 2.1519
}

get_atoms2(prop=None)

Get atomic data.
:param prop: If None, return full atomic data dict.
             If a string, return that specific atomic property.
             Available keys: 'natom', 'coords', 'charge', 'mass'
:type prop: str or None

:rtype: dict or np.ndarray

get_grad()

Get gradient in Hartree/Bohr

get_nac()

Get the non-adiabatic (phase-corrected derivative) coupling matrix d_ij.

Populated by a NACME run (``self.dcm``); empty for every other runtype.
The elements are sign/phase ambiguous between builds, so the regression
comparison uses magnitudes (see the ``nac`` registry entry,
``phase_invariant=True``).

get_soc()

Get spin-orbit coupling eigenvalues in cm-1

get_hess()

Get hessian results

set_hessian_result(raw_hessian, asymmetry_tol=1e-08)

Store a final Cartesian Hessian in OpenQP frequency conventions.

Native analytic Hessian kernels should hand one square ``(3N, 3N)``
matrix to this helper. The helper records the pre-symmetrization
asymmetry for diagnostics and stores the symmetrized matrix used by
normal-mode analysis; it does not compute a numerical fallback.

snapshot_mrsf_ekt_results(kind)

Snapshot MRSF-EKT root results ('ip' or 'ea') right after the call.

The Fortran EKT driver reuses the same OQP::mrsf_ekt_* records for IP
and EA, so when both are requested in one runtype=ekt job the second
call overwrites the first.  Snapshotting after each call keeps the
Dyson orbitals and pole strengths of both kinds for the final JSON.

get_mrsf_ekt_results()

Collect MRSF-EKT root results for the final JSON file.

get_data()

Extract data from mol to dict

get_data_from_back_door()

Extract mol data for nacme calculation

explicit_scf_props()

Lowercased scf_prop values requested for this calculation.

``scf_prop`` defaults to empty, so its config value is exactly the set of
properties the user asked for -- works identically for file-based and
scripting-API (input_dict) runs. Regression coverage of a property is
opt-in: only requested properties are surfaced to the JSON, required by
the gate, and compared.

get_results()

Collect computed results to dict

get_coord(coordinates)

update_system(coordinates)

Modify coordinates in memory

update_mol(ref_mol)

Pass data from ref_mol to current mol

check(info)

Check internal data

data_allocate()

Allocate new oqp data object

data_deallocate()

Deallocate oqp data object

get_config(input_source)

load_config(input_source)

Load calculation parameters from a file or a dictionary based on the input type.

input_source: filename (str) or config dictionary (dict)

write_molden(filename)

Write calculation results in Molden format

set_log()

Set up log file

set_config_json()

save_data(lean=None)

Save mol data and computed results to json

:param lean: When True, drop internal ``OQP::`` arrays (density, Fock,
             MO coefficients, overlap/kinetic, SOC/TD/MRSF scratch, etc.)
             before writing. These are never compared by ``check_ref`` and
             are not consumed by any example, so test references can omit
             them to stay ~99% smaller. When None (default) the behaviour
             follows the ``OQP_LEAN_JSON`` environment variable; otherwise
             the full bundle is written so the ``guess=json`` restart
             workflow (``load_data``/``put_data``) keeps its DM/Fock/MO data.

save_freqs(state)

load_data()

update_config_json()

put_data(data)

read_freqs()

regression_context()

(runtype, excited, props) used to resolve which registry keys apply.

``excited`` is True when an excited-state (TDDFT/MRSF/...) method is
active, which is the gate for comparing ``td_energies`` (a ground-state
run stores the placeholder [0]). ``props`` is the list of requested
``scf_prop`` values (e.g. 'nmr'), the gate for property keys.

check_ref()

Compare runtime results against the reference, driven by the
regression registry (an allowlist: exactly the declared quantities for
this runtype/method/properties are compared).

compare_data(data_1, data_2, skip_sub=(), rtol=0.0)

Compute the numerical differences between two arrays

``skip_sub`` names dict sub-keys to ignore during comparison (e.g. the
phase/sign-ambiguous EKT orbital vectors); the registry supplies these per
quantity so they are declared in one place.

``rtol`` (0 = exact absolute compare) sets a relative tolerance: a value is
counted as matching when ``|a-b| <= rtol*|b|``, and only the excess beyond
that tolerance contributes to the reported diff. Used for large-magnitude
quantities (e.g. SOC, ~1e5 cm^-1) where the absolute round(diff,4) gate
would otherwise demand far more significant figures than ULP-level noise.

get_coord(xyz, nat)

Get coordinate

string_config(config)

list2string(in_list)