Home

QMol-grid package

The QMol-grid package provides a suites of routines for performing quantum-mechanical simulations in atomic and molecular systems in one spatial dimension. All simulations use an underlying Cartesian-grid discretization scheme. The QMol-grid package is written using MATLAB's object-oriented features and handle classes.

By default and unless otherwise specified, all parameters in the QMol-grid package are specified in atomic units.

Features

The QMol-grid package provides support for the following types of computations, all with one spatial dimension

Ground- and excited-state density-functional theory (DFT), both using a Cartesian-grid or basis-set discretization
Ground- and excited-state Hartree Fock (HF), both using a Cartesian-grid or basis-set discretization
Ground- and excited-state Schrödinger equation (SE), both using a Cartesian-grid or basis-set discretization
Real-time time-dependent density-functional theory (TDDFT), using a Cartesian-grid discretization
Time-dependent Schrödinger equation (TDSE), using a Cartesian-grid discretization

The time-propagators are computed using symplectic-split operators (2nd, 4th, and 6th order in time, and spectral in space). They support field-free and laser-driven simulations (in the dipole approximation) with the following on-the-fly features, each specifying their own time sampling

Checkpointing, with the creation of a restart MATLAB file that can be used to resume a calculation that stopped before it was finished
Calculation and storage of the dipole, dipole velocity, and dipole acceleration signals
Calculation and storage of the wave function(s)/Kohn-Sham orbitals and Hamiltonian-component energies
Storage of the wave function(s) (Schrödinger), and Kohn-Sham orbitals and one-body density (DFT)
Calculation and storage of the ionization signal, keeping track of how much electronic density is absorbed at the domain boundaries
Calculation and storage of the results of installable output functions of the wave function(s) (Schrödinger), and Kohn-Sham orbitals or one-body density (DFT)
Saving the intermediate Schrödinger- or DFT-model objects in separate MATLAB files (.mat)

External components

The QMol-grid package includes the following three externally developed components (from the Tools toolbox, version 01.02 or later)

convertLaser, which facilitates miscellaneous unit conversions for laser fields
convertUnit, which is used to perform miscellaneous unit conversions between atomic and SI units
fourierTool, which is used with fast-Fourier transforms (e.g., when computing derivatives or convolutions)

Tutorials

For beginners, a few tutorials are available -- see the tutorial section.

How to cite the package

Main reference for the QMol-grid package:

F. Mauger and C. Chandre, QMol-grid: A MATLAB package for quantum-mechanical simulations in atomic and molecular systems, SoftwareX 28, 101968 (2024)

@article{MAUGER2024101968,
  title = {QMol-grid: A MATLAB package for quantum-mechanical simulations in atomic and molecular systems},
  author = {Mauger, Fran\c{c}ois and Chandre, Cristel},
  journal = {SoftwareX},
  volume = {28},
  pages = {101968},
  year = {2024},
  doi = {10.1016/j.softx.2024.101968}
}

Specific references to selected features are listed in the (run-time) documentation. The main ones are

Symplectic split operator propagator scheme: F. Mauger, C. Chandre, M.B. Gaarde, K. Lopata, and K.J. Schafer, "Hamiltonian formulation and symplectic split-operator schemes for time-dependent density-functional-theory equations of electron dynamics in molecules," Communications in Nonlinear Science and Numerical Simulation 129, 107685 (2024).

@article{MAUGER2024107685,
  title = {Hamiltonian formulation and symplectic split-operator schemes for time-dependent density-functional-theory equations of electron dynamics in molecules},
  journal = {Communications in Nonlinear Science and Numerical Simulation},
  volume = {129},
  pages = {107685},
  year = {2024},
  doi = {10.1016/j.cnsns.2023.107685}
}

Package architecture

The QMol-grid package provides an ecosystem of MATLAB handle classes (object-oriented). While the package is provided as a stand-alone suite, it is developed around 3 main groups: (1) external components, (2) kernel classes that define high-level calculation methods, and (3) implementation classes that define all the lower-level functionalities.

The package was developed to provide a versatile suite of quantum-mechanical methods with streamlined access to the wave function(s) (SE/TDSE) and the Kohn-Sham orbitals (DFT/TDDFT). The wave functions/Kohn-Sham orbitals are packaged into classes that enable abstract manipulations in the objects, e.g., for ground-state, time propagation, and common observables' calculations. The object-oriented structure provides a uniform user interface, where input parameters are specified as pairs parameter-name/parameter-values (in arbitrary order and case insensitive). Output results are stored in the objects and can be recovered using the standard object-oriented dot notation (see the tutorials for examples).

For developers

For readability, the QMol-grid package is divided into three main components

Kernel classes, which perform high-level operations (e.g., agnostic of the dimension or discretization). These classes are shared between the deployment of the QMol-grid package in various dimensions.
Implementation classes, which handle all the computations specific to the QMol-grid version.
Unit test classes, which perform low-level checks on the methods

When implementing new classes, one should

have the name of the class start with QMol_; for instance this is required for support in the test suite (i.e., implementing a suite of unit test for the new class)
derive the class from QMol_suite (abstract handle class); this will (i) provide default set, reset, clear, and constructor and (ii) grant setAccess to many class properties throughout the QMol package.

Development and contributors

The QMol-grid package was originally designed and developed by Francois Mauger, who remains the active developer for the code.

Individual contributors for each component used in simulations can be accessed using the run-time documentation.

License

2-Clause BSD License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Acknowledgments

The original development of the QMol-grid package, and its (TD)DFT features, was supported by the U.S. Department of Energy, Office of Science, Office of Basic Energy Sciences, under Award No. DE-SC0012462.
Addition of the (TD)SE features was supported by the National Science Foundation under Grant No. PHY-2207656.

This wiki is a copy of the documentation provided with the QMol-grid package (accessible in MATLAB documentation, via the "Supplemental Software" section).
Copyright © 2024, Francois Mauger, all right reserved.