maxwelllink.mxl_drivers.python.models.rttddft_model module¶

class maxwelllink.mxl_drivers.python.models.rttddft_model.RTTDDFTModel[source]¶

Bases: DummyModel

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

This class implements an RT-TDDFT 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 = RTTDDFTModel(
...     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=False,
...     remove_permanent_dipole=False
... )
>>> model.initialize(dt_new=0.12, molecule_id=0)
Initial SCF energy: -91.6751251525 Eh
>>> model._get_lr_tddft_spectrum(states=5, tda=False)
Energy (eV): [ 7.39216   8.554808  8.554808 10.736077 10.736077]
Oscillator strengths: [0.       0.       0.       0.048238 0.048238]
>>> model._propagate_full_rt_tddft(nsteps=10)
Step   30 Time 1.200000  Etot = -91.6751251490 Eh  ΔE = 0.0000000036 Eh,  μx = 0.000024 a.u.,  μy = 0.000024 a.u.,  μz = 0.965180 a.u.

__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)[source]¶

Initialize the necessary parameters for the RT-TDDFT 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") – Any Psi4 functional label, e.g. "PBE", "B3LYP", "SCAN", "PBE0". Default is "SCF" (Hartree-Fock).
basis (str, default: "sto-3g") – Any 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.). If the FDTD time step is an integer multiple of this, the driver will sub-step internally. This sub-stepping can avoid propagating EM fields too frequently when the molecule requires a small time step.
delta_kick_au (float, default: 0.0e-3) – Strength of the initial delta-kick perturbation along the x, y, and z direction in atomic units (a.u.). If this value is non-zero, the driver will apply a delta-kick perturbation at \(t=0\) to initiate the dynamics. With this delta-kick, and also setting the FDTD coupling to zero, one can compute the conventional RT-TDDFT linear absorption spectrum of the molecule.
delta_kick_direction (str, default: "xyz") – Direction of the initial delta-kick perturbation. Can be "x", "y", "z", "xy", "xz", "yz", or "xyz".
memory (str, default: "8GB") – Memory allocation for Psi4, e.g. "8GB", "500MB".
num_threads (int, default: 1) – Number of CPU threads to use in Psi4.
checkpoint (bool, default: False) – Whether to dump checkpoint files during propagation to allow restarting from the last checkpoint.
restart (bool, default: False) – Whether to restart the propagation from the last checkpoint. Setting this to True requires that checkpoint files exist. When restarting, the driver will ignore the initial delta-kick perturbation even if it is non-zero.
verbose (bool, default: False) – Whether to print verbose output.
remove_permanent_dipole (bool, default: False) – Whether to remove the effect of permanent dipole moments in the light–matter coupling term.
dft_grid_name (str, default: "SG0") – Name of the DFT grid to use in Psi4, e.g. "SG0", "SG1". Using "SG0" can speed up DFT calculations significantly but is less accurate.
dft_radial_points (int, default: -1) – Number of radial points in the DFT grid. -1 uses the Psi4 default.
dft_spherical_points (int, default: -1) – Number of spherical points in the DFT grid. -1 uses the Psi4 default.
electron_propagation (str, default: "pc") – The electron propagation scheme to use. Options are "etrs" (Enforced Time-Reversal Symmetry) or "pc" (Predictor-Corrector). Default is "pc".
threshold_pc (float, default: 1e-6) – Convergence threshold for the predictor–corrector scheme.

append_additional_data()[source]¶

Append additional data to be sent back to MaxwellLink.

The data can be retrieved by the user via: maxwelllink.SocketMolecule.additional_data_history.

Returns:: A dictionary containing additional data.
Return type:: dict

calc_amp_vector()[source]¶

Update the source amplitude vector after propagating this molecule for one time step.

The amplitude is \(\\displaystyle \\frac{\\mathrm{d}}{\\mathrm{d}t}[\\rho(t)\\,\\mu]\).

Returns:: The amplitude vector [A_x, A_y, A_z].
Return type:: numpy.ndarray of float, shape (3,)

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, reset_substep_num=None)[source]¶

Propagate the quantum molecular dynamics given the effective electric field vector.

Parameters:

effective_efield_vec (array-like of float, shape (3,)) – Effective electric field vector in the form [E_x, E_y, E_z].
reset_substep_num (int or None, optional) – If provided, reset the number of sub-steps to this value for the current propagation step.

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].