gext: Grassmann Extrapolation Library

This library define an Extrapolator class to be used for providing guesses in QM simulations. It is designed in such a way that requires minimum modifications on the QM code side.

Installation

The library can be installed using pip:

• Navigate to the root folder of the library
• Run pip install .

Usage

The usage requires only four lines of code:

• Add an import statement import gext.

• Initialize a new extrapolator by inserting the line:

  extrapolator = gext.Extrapolator(nelectrons, nbasis, natoms).

  Note: the extrapolator can be finely controlled by passing additional keyword arguments. This is explained in the next section.

• When a new SCF calculation has been performed, load the resulting data in the extrapolator by running:

  extrapolator.load_data(coordinates, coefficients, overlap).

  Here, coordinates are the molecule coordinates of size (natoms, 3), coefficients is the full coefficients matrix of size (nbasis, nbasis) and overlap is the overlap matrix of size (nbasis, nbasis).

• When a new guess density is needed, run:

  guess_density = extrapolator.guess(current_coordinates, current_overlap),

  if current_overlap is not available, run this alternative:

  guess_density = extrapolator.guess(current_coordinates).

Further options

The behavior can be finely controlled by passing additional keyword arguments to the gext.Extrapolator() constructor. Note: some options might be implemented in the future.

This is an up to date list of available keyword options:

• nsteps: integer, default 6, number of steps to be used in the extrapolation.
• verbose: boolean, default False, if True print additional information.
• descriptor: string, default "distance", possible options are "distance" and "coulomb".
• fitting: string, default "leastsquare", possible options are "leastsquare" and "qtr".
• allow_partially_filled: bool, default True. If True allow to do a guess before nsteps data points have been loaded, if False asking for a guess before nsteps data points will cause a ValueError.
• store_overlap: bool, default True. Store the overlaps for later usage in calling guess without passing the current overlap. It can be disabled for performance, but calling guess will require passing the overlap.

Some options can be piped to the fitting modules.

• fitting_regularization: float, default 0.0. Controls the regularization for both the "leastsquare" and "qtr" fitting schemes.

Acknowledgments

This work is based on these papers:

1. F. Pes, É. Polack, P. Mazzeo, G. Dusson, B. Stamm, and F. Lipparini, “A Quasi Time-Reversible Scheme Based on Density Matrix Extrapolation on the Grassmann Manifold for Born–Oppenheimer Molecular Dynamics,” The Journal of Physical Chemistry Letters, vol. 14, no. 43. American Chemical Society (ACS), pp. 9720–9726, Oct. 25, 2023. doi: 10.1021/acs.jpclett.3c02098.
2. É. Polack, G. Dusson, B. Stamm, and F. Lipparini, “Grassmann Extrapolation of Density Matrices for Born–Oppenheimer Molecular Dynamics,” Journal of Chemical Theory and Computation, vol. 17, no. 11. American Chemical Society (ACS), pp. 6965–6973, Oct. 08, 2021. doi: 10.1021/acs.jctc.1c00751.
3. É. Polack, A. Mikhalev, G. Dusson, B. Stamm, and F. Lipparini, “An approximation strategy to compute accurate initial density matrices for repeated self-consistent field calculations at different geometries,” Molecular Physics, vol. 118, no. 19–20. Informa UK Limited, p. e1779834, Jun. 22, 2020. doi: 10.1080/00268976.2020.1779834.