oqp.analysis.transition_density

MRSF excited-state densities read from the OQP tagarray bridge.

The MRSF energy driver (``tdhf_mrsf_energy``) exposes three arrays (written by
the ``misc-excited-analysis`` patch):

* ``OQP::td_trans_density_mo`` -- ``trden(nbf,nbf,nstates*nstates)`` in the
  **alpha-MO basis**.  The off-diagonal blocks ``(ist != jst)`` are the
  state-interaction one-particle transition density matrices (1-TDM)
  :math:`\gamma^{i\to j}`; the diagonal blocks ``(ist == jst)`` are the
  *traceless difference* 1-RDMs :math:`\Delta\gamma^{n}=\gamma^{n}-\gamma^{\rm ref}`.
  Crucially, because the MRSF ground state ``S0`` is itself a response root
  (not the reference), every block has **only occ-occ and vir-vir parts** --
  the occ-vir block is zero.  This is the genuine state-interaction structure,
  not a reference->amplitude object.
* ``OQP::td_trans_dipole`` -- ``dip(3,nstates,nstates)`` OQP's own transition
  dipoles (a.u.) at the center of mass.
* ``OQP::td_dip_ao`` -- AO electric-dipole integrals (packed lower-triangle).

This module is validated at GATE 2: reconstructing
:math:`\mu^{i\to j}=-\mathrm{Tr}(\gamma^{i\to j}_{\rm AO}\,r)` from the exposed
1-TDM reproduces ``dip`` to ~1e-15, and ``Tr(gamma^n_AO . S) = N``.

Classes

MRSFExcitedStates

Module Contents

class MRSFExcitedStates(mol)

Excited-state density analysis for a finished MRSF calculation.

:param mol: A molecule whose MRSF energy run has completed in the *current*
            process (so the tagarray still holds the exposed densities).
:type mol: oqp.molecule.molecule.Molecule

mol

nbf

na

nb

n_elec

energies

nstates

C

S

R

dip_oqp

gamma_ref_mo

tdm_mo(i, j)

1-TDM gamma^{i->j} in the alpha-MO basis (0-based state indices).

Only the upper triangle is stored by OQP; gamma^{j->i} == (gamma^{i->j})^T.

tdm_ao(i, j)

1-TDM gamma^{i->j} in the AO basis: C gamma_mo C^T.

diff_density_mo(n)

Traceless difference density Delta gamma^n = gamma^n - gamma^ref (MO).

state_density_mo(n)

Unrelaxed state 1-RDM gamma^n in the MO basis (gamma_ref + Delta).

state_density_ao(n)

Unrelaxed state 1-RDM gamma^n in the AO basis.

mo_density_ao(mo_index)

AO density of a single (alpha) MO |phi><phi| (for cube export).

transition_dipole(i, j)

Reconstruct mu^{i->j} = -Tr(gamma_ao . r) (a.u.), x/y/z.

oscillator_strength(i, j)

f = (2/3) * dE * |mu|^2 (dE = |E_j - E_i| in a.u.).

amplitude_matrix(n)

Spin-adapted MRSF spin-flip amplitude matrix X^{(n)} (noca x nvirb).

Rows = alpha-occupied MOs 0..na-1 (holes), columns = beta-virtual MOs
nb..nbf-1 (particles).  Replicates the SOMO sqrt(2) handling of
``get_mrsf_transition_density`` so that ``trans_den(X,X)`` reproduces the
exposed difference density (validated in the GATE 3 self-check).

trans_den_from_amplitudes(xi, xj)

Reproduce OQP's ``get_trans_den`` (alpha-MO basis) from amplitude
matrices of two roots.  Used to validate ``amplitude_matrix``.