maxwelllink.mxl_drivers.python.models.rt_ehrenfest_model module

class maxwelllink.mxl_drivers.python.models.rt_ehrenfest_model.RTEhrenfestModel[source]

Bases: RTTDDFTModel

A real-time time-dependent density functional theory Ehrenfest (RT-TDDFT-Ehrenfest) quantum dynamics model using the Psi4 quantum chemistry package.

This class implements an RT-TDDFT-Ehrenfest model for quantum dynamics, which can be integrated with the MaxwellLink framework.

Examples

Create from an XYZ file and then set the molecule ID with restricted SCF:

>>> model = RTEhrenfestModel(
...     engine="psi4",
...     molecule_xyz="../../../../../tests/data/hcn.xyz",
...     functional="scf",
...     basis="sto-3g",
...     dt_rttddft_au=0.04,
...     delta_kick_au=1.0e-3,
...     memory="2GB",
...     verbose=True,
...     remove_permanent_dipole=False
... )
>>> model.initialize(dt_new=0.12, molecule_id=0)
Initial SCF energy: -91.6751251525 Eh
>>> model._propagate_rttddft_ehrenfest(n_nuc_steps=2)
__init__(engine='psi4', molecule_xyz='', functional='SCF', basis='sto-3g', dt_rttddft_au=0.04, delta_kick_au=0.0e-3, delta_kick_direction='xyz', memory='8GB', num_threads=1, checkpoint=False, restart=False, verbose=False, remove_permanent_dipole=False, dft_grid_name='SG0', dft_radial_points=-1, dft_spherical_points=-1, electron_propagation='pc', threshold_pc=1e-6, force_type='ehrenfest', n_fock_per_nuc=10, n_elec_per_fock=10, mass_amu=None, friction_gamma_au=0.0, temperature_K=None, rng_seed=1234, homo_to_lumo=False, partial_charges=None, fix_nuclei_indices=None, save_xyz=None)[source]

Initialize the necessary parameters for the RT-TDDFT-Ehrenfest quantum dynamics model.

Parameters:

  • engine (str, default: "psi4") – The computational engine to use (e.g., "psi4"). Currently, only "psi4" is supported.

  • molecule_xyz (str) – Path to the XYZ file containing the molecular structure. The second line of the XYZ file may contain the charge and multiplicity.

  • functional (str, default: "SCF") – Psi4 functional label, e.g., "PBE", "B3LYP", "SCAN", "PBE0".

  • basis (str, default: "sto-3g") – Basis set label recognized by Psi4, e.g., "sto-3g", "6-31g", "cc-pVDZ".

  • dt_rttddft_au (float, default: 0.04) – Time step for real-time TDDFT propagation in atomic units (a.u.).

  • delta_kick_au (float, default: 0.0e-3) – Strength of the initial delta-kick perturbation in atomic units.

  • delta_kick_direction (str, default: "xyz") – Direction of the delta-kick perturbation (e.g., "x", "xy", or "xyz").

  • memory (str, default: "8GB") – Memory allocation for Psi4.

  • num_threads (int, default: 1) – Number of CPU threads used by Psi4.

  • checkpoint (bool, default: False) – Whether to dump checkpoint files during propagation.

  • restart (bool, default: False) – Whether to restart propagation from a checkpoint.

  • verbose (bool, default: False) – Whether to print verbose output.

  • remove_permanent_dipole (bool, default: False) – Remove the permanent dipole contribution from the light–matter coupling term.

  • dft_grid_name (str, default: "SG0") – Name of the DFT grid (e.g., "SG0" or "SG1").

  • dft_radial_points (int, default: -1) – Number of radial grid points (Psi4 default if negative).

  • dft_spherical_points (int, default: -1) – Number of angular grid points (Psi4 default if negative).

  • electron_propagation (str, default: "pc") – Electron propagation scheme. Options: "etrs" or "pc".

  • threshold_pc (float, default: 1e-6) – Convergence threshold for predictor–corrector propagation.

  • force_type (str, default: "ehrenfest") – Type of forces used for nuclei: "bo" (Born–Oppenheimer) or "ehrenfest".

  • n_fock_per_nuc (int, default: 10) – Number of Fock builds per nuclear update.

  • n_elec_per_fock (int, default: 10) – Number of electronic RT-TDDFT steps per Fock build.

  • mass_amu (array-like, optional) – Atomic masses (amu) for each atom; if None, Psi4 defaults are used.

  • friction_gamma_au (float, default: 0.0) – Friction coefficient for Langevin dynamics (a.u.).

  • temperature_K (float, optional) – Temperature for Langevin thermostat (K).

  • rng_seed (int, default: 1234) – Random seed for Langevin dynamics.

  • homo_to_lumo (bool, default: False) – Promote one alpha electron from HOMO→LUMO at initialization.

  • partial_charges (list, optional) – Per-atom partial charges for additional external-field forces.

  • fix_nuclei_indices (list, optional) – Indices of fixed nuclei during propagation.

  • save_xyz (str, optional) – Path to save XYZ trajectory during propagation.

append_additional_data()[source]

Append additional data to be returned to MaxwellLink.

Returns:

Contains current time, total energy, and dipole components.

Return type:

dict

calc_amp_vector()[source]

Update the total amplitude vector after one full propagation step.

The total derivative is \(\frac{d}{dt}[\rho(t)\mu_e] + \frac{d}{dt}\Big[\sum_A Z_A R_A(t)\Big]\).

Returns:

Amplitude vector [A_x, A_y, A_z] in a.u.

Return type:

numpy.ndarray

commit_step()

Commit the previewed step and return the staged amplitude.

This method applies the changes from the staged step to the internal state and returns the calculated amplitude vector.

Notes

This method should not be overridden by subclasses.

Returns:

Amplitude vector in the form \([\mathrm{d}\mu_x/\mathrm{d}t,\ \mathrm{d}\mu_y/\mathrm{d}t,\ \mathrm{d}\mu_z/\mathrm{d}t]\).

Return type:

numpy.ndarray of float, shape (3,)

have_result()

Check if a staged step is ready to be committed.

Notes

This method should not be overridden by subclasses.

Returns:

Whether a staged step is ready.

Return type:

bool

initialize(dt_new, molecule_id)[source]

Set the time step and molecule ID for this quantum dynamics model.

Parameters:

  • dt_new (float) – The new time step in atomic units (a.u.).

  • molecule_id (int) – The ID of the molecule.

propagate(effective_efield_vec)[source]

Propagate coupled electronic–nuclear Ehrenfest dynamics under an external field.

The integrator involves four nested time scales:

  1. Velocity Verlet for nuclei (Δt_N)

  2. Midpoint Fock updates (Δt_Ne = Δt_N / n)

  3. MMUT-like electronic propagation (Δt_e = Δt_Ne / m)

  4. External FDTD driver coupling (Δt_FDTD)

Parameters:

effective_efield_vec (numpy.ndarray) – Effective electric field vector [E_x, E_y, E_z] in a.u.

stage_step(E_vec)

Stage a propagation step with the given effective electric field vector.

This method performs the propagation and calculates the amplitude vector, but does not commit the changes to the internal state. The result can be committed later using the self.commit_step method.

Notes

This method should not be overridden by subclasses.

Parameters:

E_vec (array-like of float, shape (3,)) – Effective electric field vector in the form [E_x, E_y, E_z].