oqp.library.namd

Nonadiabatic molecular dynamics (NAMD) — Tully fewest-switches surface hopping
(FSSH) on MRSF-TDDFT adiabatic states.

Design
------
The numerically critical surface-hopping physics lives in Fortran
(``source/modules/namd.F90`` -> C entry ``mrsf_namd_hop``); this Python driver
only *sequences* the existing electronic-structure drivers and integrates the
nuclei with velocity Verlet:

  per step:  position update (Verlet)
             -> SinglePoint.reference()  (SCF)
             -> BasisOverlap.overlap()   (MO overlap vs previous step, phase aligned)
             -> SinglePoint.excitation() (MRSF energies + response vectors)
             -> Gradient (active state)
             -> velocity 2nd half-kick
             -> NACME.nacme()            (state overlap S = <i(t-dt)|j(t)>)
             -> oqp.mrsf_namd_hop()      (TDC, RK4 amplitude propagation, EDC,
                                          trivial-crossing follow, FSSH hop +
                                          isotropic velocity rescaling)
             -> on hop: recompute gradient on the new active surface
             -> output / restart

Units: coordinates in bohr, masses in electron masses, energies in Hartree,
velocities in bohr / atomic-time.  Time step is given in fs and converted.

This is the gas-phase (all-QM) path; QM/MM and PBC are layered on later.

Attributes

`FS_TO_AU`
`KB_HARTREE`
`AMU_TO_AU`
`BOHR_TO_NM`
`NM_TO_BOHR`
`HABOHR_TO_KJMOLNM`
`KJMOL_TO_HARTREE`
`HA_TO_WAVENUM`

Classes

`NAMD`
`NAMD_QMMM`
`NAMD_SOC`
`NAMD_SOC_MCH`
`NAMD_SOC_QMMM`
`NAMD_SOC_MCH_QMMM`

Module Contents

FS_TO_AU = 41.341374575751

KB_HARTREE = 3.166811563e-06

AMU_TO_AU = 1822.888486209

BOHR_TO_NM = 0.05291772109

NM_TO_BOHR = 18.89726124636483

HABOHR_TO_KJMOLNM = 49614.75258041956

KJMOL_TO_HARTREE = 0.0003808798847829512

class NAMD(mol)

Driver for FSSH nonadiabatic molecular dynamics.

mol

nstep

dt_fs

dt

dt_max

dt_adaptive

dt_min

dx_max

active

nstate

substep

decoherence = 0

edc_c

thrshe

tdc_scheme = 0

trivial = 0

trivial_thresh

init_temp

seed

velocity_source = ''

natom

mass

rng

coef

vel

prev_xyz = None

prev_data = None

run()

class NAMD_QMMM(mol)

Bases: NAMD

FSSH NAMD with electrostatic ESPF QM/MM embedding (non-periodic).

The QM region is the OpenQP Molecule; the MM region + QM/MM coupling are
handled by OpenMM via the OpenQpQMMM driver.  Per step:
  * sync positions (QM Molecule + OpenMM context),
  * MM electrostatic potential at QM atoms (POTMM),
  * embedded SCF + MRSF excitation (all states),
  * active-state embedded gradient = Gradient + grad_esp_qmmm_excited,
  * ESPF QM charges -> MM forces (forces_mm),
  * full-system velocity Verlet (QM+MM, atomic units),
  * QM-only FSSH hop (rescale only QM velocities, as in GAMESS RESCALV).

qm_atoms

cutoff

periodic

pdb

forcefield

driver

mm

natom_all

r_all

m_all

v_all

qm_mass

run()

HA_TO_WAVENUM = 219474.6313708

class NAMD_SOC(mol)

Bases: NAMD

SOC-NAMD (intersystem crossing) on the SHARC spin-adiabatic representation.

soc_mrsf builds and diagonalises H = diag(E_MCH) + H_SOC, giving the
spin-adiabatic energies (OQP::soc_eval, cm^-1 relative to the lowest
excitation) and eigenvectors U (OQP::soc_evec_*).  Surface hopping is done
on these spin-adiabatic states.

Nuclei propagate on the active spin-adiabatic surface using the SHARC
weighted-MCH diagonal gradient (sum_i |U_i,a|^2 grad E_i^MCH, triplet Ms
sublevels sharing one gradient), which is correct through an S/T crossing
where SOC mixes states strongly.  The spin-adiabatic FSSH hopping layer uses
the local-diabatization propagator with substep energy integration and
U-phase tracking (block-Procrustes within degenerate Ms groups) on the
block-diagonal MCH state overlap.

nstate_mrsf

ns

nt

nstate_soc

active

coef

e_ref = 0.0

e0 = 0.0

init_state = ''

econs

soc_du_dt_corr

soc_tdc_grad_corr

run()

class NAMD_SOC_MCH(mol)

Bases: NAMD_SOC

SOC-NAMD in the MCH (spin-pure) basis.

The active state is a single MCH basis function (singlet root or one
triplet Ms component), so the nuclear force is the exact MCH root gradient.
Electronic amplitudes are propagated by the SOC Hamiltonian in that MCH
basis instead of the spin-adiabatic local-diabatization propagator.

coef

run()

class NAMD_SOC_QMMM(mol)

Bases: NAMD_QMMM

SOC-NAMD (intersystem crossing) with electrostatic ESPF QM/MM embedding.

Union of the SHARC spin-adiabatic SOC-NAMD machinery (NAMD_SOC) and the
ESPF/OpenMM embedding (NAMD_QMMM).  Per step:
  * sync positions (QM Molecule + OpenMM context),
  * embedded SCF + singlet MRSF + triplet MRSF + soc_mrsf -> (E_diag, U),
  * spin-adiabatic MCH overlap -> U-phase tracking -> overlap T,
  * active-surface force = weighted-MCH diagonal gradient, each MCH
    component carrying its own ESPF embedding gradient,
  * ESPF QM charges (of the dominant MCH component) -> MM forces,
  * full-system velocity Verlet (QM+MM, atomic units),
  * local-diabatization propagation + spin-adiabatic fewest-switches hop,
    rescaling QM velocities only (as in GAMESS RESCALV).

The SOC electronic/hopping kernels are borrowed from NAMD_SOC via explicit
NAMD_SOC.<method>(self, ...) calls so this class can inherit the QM/MM
embedding plumbing from NAMD_QMMM.

nstate_mrsf

ns

nt

nstate_soc

active

coef

e_ref = 0.0

e0 = 0.0

init_state = ''

econs

soc_du_dt_corr

soc_tdc_grad_corr

run()

class NAMD_SOC_MCH_QMMM(mol)

Bases: NAMD_SOC_QMMM

QM/MM SOC-NAMD in the MCH basis with exact active-root QM gradient.

coef

run()