Interface to GDMA Distributed Multipole Analysis by A. J. Stone — gdma()
¶
Code author: Anthony J. Stone, Andrew C. Simmonett
Section author: Andrew C. Simmonett
Module: Keywords, PSI Variables, GDMA_INTERFACE
Installation¶
Binary
GDMA is available as a conda package for Linux and macOS (and Windows, through the Ubuntu shell).
If using the PSI4 binary, gdma has already been installed alongside.
If using PSI4 built from source, and anaconda or miniconda has already been installed (instructions at Quick Installation), gdma can be obtained through
conda install gdma -c psi4
. Then enable it as a feature with ENABLE_gdma, hint its location with CMAKE_PREFIX_PATH, and rebuild PSI4 to detect gdma and activate dependent code.
To remove a conda installation,
conda remove gdma
.
Source
Input¶
The distributed multipole analysis (DMA) technique, developed by Anthony J.
Stone and implemented by him into the GDMA package, is available in PSI4.
The current implementation simply embeds Stone’s GDMA code into the main
executable, and generates the appropriate input files automatically. The
program takes as input a data file, and a Gaussian formatted checkpoint (see
Section FCHK) file. The simplest usage of the GDMA code is
demonstrated below, along with a listing of the options supported; these
options correspond to the options described in the
GDMA manual
.
If more advanced usage is desired, which is not is permitted by the options
listed below, the user may provide their own data file containing keywords to
control the GDMA code. Simply place the data file in the directory PSI4
is called from, and provide the file name as the datafile argument to the
gdma()
routine. For example, if GDMA data file is called
control.dma, the GDMA code is called as follows:
grad, wfn = gradient('mp2', return_wfn=True)
gdma(wfn, datafile='control.dma')
An FCHK file will be generated for the GDMA code to read; this file will have the prefix given by WRITER_FILE_LABEL (if set), or else by the name of the output file plus the name of the current molecule, and the suffix will be ‘.fchk’. This FCHK file name should be passed to the ‘File’ keyword in the DGMA data file, to ensure that the GDMA code reads the correct wavefunction information.
After running, two matrices of results can be accessed:
dma_results = get_array_variable('DMA DISTRIBUTED MULTIPOLES')
tot_results = get_array_variable('DMA TOTAL MULTIPOLES')
The first contains distributed multipoles, in units given by GDMA_MULTIPOLE_UNITS, with the row index corresponding to the site and the column index referencing the multipole component. Both indices are zero based, and the \(Q^l_m\) components of the multipoles are ordered as \(Q^0_0, Q^1_0, Q^1_{1c}, Q^1_{1s}, Q^2_0, Q^2_{1c}, Q^2_{1s}, Q^2_{2c}, Q^2_{2s}, \ldots\) The second matrix returned has a single row, whose columns are the total multipoles, translated to GDMA_ORIGIN, and summed.
- psi4.gdma(wfn)[source]
Function to use wavefunction information in wfn and, if specified, additional commands in filename to run GDMA analysis.
New in version 0.6.
- Returns:
None
- Parameters:
wfn (
Wavefunction
) – set of molecule, basis, orbitals from which to generate DMA analysisdatafile (str) – optional control file (see GDMA manual) to peform more complicated DMA analyses. If this option is used, the File keyword must be set to read a filename.fchk, where filename is provided by WRITER_FILE_LABEL .
- Examples:
>>> # [1] DMA analysis from MP2 wavefunction. N.B. gradient must be requested to generate MP2 density. >>> grad, wfn = gradient('mp2', return_wfn=True) >>> gdma(wfn)
Options¶
GDMA_LIMIT¶
The order of multipole expansion on each site. Currently limited to the same order for all sites; for more advanced usage a user-provided GDMA data file should be provided.
Type: integer
Default: 2
GDMA_ORIGIN¶
The origin (in Angstrom, expressed as an [x, y, z] array) about which the total multipoles will be computed during DMA. Useful for determining single site expansions at an arbitrary point.
Type: array
Default: No Default
GDMA_MULTIPOLE_UNITS¶
Whether to print DMA results in atomic units or SI.
Type: string
Possible Values: AU
Default: AU SI
GDMA_RADIUS¶
The radii to be used, overriding the defaults. Specified as an array [ n1, r1, n2, r2, … ] where n1,n2,n3… are atom type strings and r1,r2,r3 are radii in Angstrom.
Type: array
Default: No Default
GDMA_SWITCH¶
The value to switch between the older standard DMA and the new grid-based approach. Pairs of primitives whose exponents sum is above this value will be treated using standard DMA. Set to 0 to force all pairs to be treated with standard DMA.
Type: double
Default: 4.0
How to configure gdma for building Psi4¶
Role and Dependencies
Role — In PSI4, GDMA is a library that provides additional quantum chemical capabilities (multipole analysis).
Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) gdma
Upstream Dependencies — gdma \(\Leftarrow\) Fortran
CMake Variables
ENABLE_gdma — CMake variable toggling whether Psi4 builds with gdma
CMAKE_PREFIX_PATH — CMake list variable to specify where pre-built dependencies can be found. For gdma, set to an installation directory containing
include/GDMA/GDMA_MANGLE.h
gdma_DIR — CMake variable to specify where pre-built gdma can be found. Set to installation directory containing
share/cmake/gdma/gdmaConfig.cmake
CMAKE_DISABLE_FIND_PACKAGE_gdma — CMake variable to force internal build of gdma instead of detecting pre-built
CMAKE_INSIST_FIND_PACKAGE_gdma — CMake variable to force detecting pre-built gdma and not falling back on internal build
Examples
Build bundled
>>> cmake -DENABLE_gdma=ON
Build without gdma
>>> cmake
Link against pre-built
>>> cmake -DENABLE_gdma=ON -DCMAKE_PREFIX_PATH=/path/to/gdma/root>>> cmake -DENABLE_gdma=ON -Dgdma_DIR=/path/to/gdma/configdir
Build bundled despite pre-built being detectable
>>> cmake -DENABLE_gdma=ON -DCMAKE_PREFIX_PATH=/path/to/unwanted/gdma/root/and/wanted/other/dependencies/root -DCMAKE_DISABLE_FIND_PACKAGE_gdma=ON