Interface to LIBEFP by I. Kaliman¶
Code author: Andrew C. Simmonett, A. Eugene DePrince III, Rollin A. King, and Lori A. Burns
Section author: Lori A. Burns
Module: Keywords, PSI Variables, LIBEFP
PSI4 contains code to interface to the LIBEFP library developed in L. Slipchenko’s group by I. Kaliman. LIBEFP requires no additional licence, downloads, or configuration. Since February 2017, libefp is not required to build PSI4.
Installation¶
Binary
libefp is available as a conda package for Linux and macOS (and Windows, through the Ubuntu shell).
If using the PSI4 binary, libefp has already been installed alongside.
If using PSI4 built from source, and anaconda or miniconda has already been installed (instructions at Quick Installation), libefp can be obtained through
conda install libefp -c psi4
. Then enable it as a feature with ENABLE_libefp, hint its location with CMAKE_PREFIX_PATH, and rebuild PSI4 to detect libefp and activate dependent code.
To remove a conda installation,
conda remove libefp
.
Source
EFP Fragments¶
LIBEFP comes with a couple dozen ready-to-use fragments (water, benzene, common solvents, etc.) listed here with source https://github.com/libefp2/libefp/tree/master/fraglib. Any of these may be used directly in a PSI4 input file as described here.
Creating new efp fragments requires the GAMESS quantum chemistry package.
Instructions on building new fragments are here.
Once your new fragment is ready, make it accessible to PSI4 by
including the directory in which the .efp
file is located to the colon
separated environment variable PSIPATH
. Fragments are searched
for first in the current directory, next in the paths of PSIPATH
, and
finally in built-in library. If PSI4 is unable to find the
fragment, an error will be reported.
Note
When constructing new fragment files, the name of the name of the
file should be lowercase and have extension .efp
. The molecule name
within the file, e.g., $NH3
must correspond to the name of the
fragment file.
Molecule Specification¶
EFP fragment geometries are specified alongside the quantum mechanical
(QM) molecule and make use of the --
fragment separation scheme
described here. Each EFP fragment has its own
fragment section that includes the label efp
, the name of the file
fragname from which EFP parameters are to be read, and the position
specification for the fragment in one of two ways, XYZABC or POINTS. For
XYZABC, the fragment specification is all on one line: efp
and
fragname are followed by two sets of three numbers: the coordinates
of the center of mass of the fragment and the three Euler angles that
specify orientation about the center of mass. This format is compact
but not readily generated from molecule viewing software.
efp nh3 0.0 0.0 5.0 5 2 8
More convenient is the POINTS fragment specification. This consists of
four lines, the first of which is efp
and fragname. The next lines
are the coordinates (without element labels) of the first three atoms
in the fragment. Note that EFP fragment geometries are rigid, so the
first atom will be placed exactly where specified by the first point,
the second atom will be placed along the vector between the first and
second points, and the third atom will be placed in the plane formed
by the three points.
efp ch3oh
1.275 -2.447 -4.673
0.709 -3.191 -3.592
2.213 -1.978 -4.343
Note
At present, PSI4 has limited support for diatomic and monoatomic EFP fragments. Single points are allowed when the di-/mono-atomic fragments are specified in XYZABC format. Optimizations are not allowed.
Just as for QM, the center of mass
coordinates in the XYZABC format and all coordinates in the POINTS format are
taken to be in Angstroms by default or in Bohr if units au
is present.
Charge and multiplicity specifications are encoded in the fragment file
and so are not read from input.
Any combination of EFP and QM fragments can be placed in a molecule; even
the oddity below is legitimate. Note that symmetry and reorientation are
automatically turned off when EFP fragments are present (symmetry c1
and no_com
and no_reorient
are implied).
molecule qmefp {
efp nh3 0.0 0.0 5.0 5 2 8
--
C 0.0 0.0 0.0
O 0.0 1.5 0.0
O 0.0 -1.5 0.0
--
efp h2o 5.0 0.0 0.0 5 2 8
--
He -3.0 4.0 4.0
He -4.0 5.0 4.0
--
efp ch3oh
1.275 -2.447 -4.673
0.709 -3.191 -3.592
2.213 -1.978 -4.343
}
Running EFP¶
EFP can be invoked in similar fashion as other theories provided in PSI4. For example, if you want to obtain the EFP interaction energy for benzene and two waters, simply provide the following:
molecule {
efp c6h6 0.0 0.0 0.0 0.0 0.0 0.0
--
efp h2o 4.0 0.0 0.0 0.0 0.0 0.0
--
efp h2o -4.0 0.0 0.0 0.0 0.0 0.0
}
energy('efp')
This computation involves purely EFP/EFP fragment interactions and is performed entirely by the LIBEFP library. PSI4 can also handle mixed systems of quantum mechanical (QM) and EFP fragments through the native SCF code augmented by calls to the LIBEFP library. For example, turning one of the waters in the example above into a QM fragment is shown below.
molecule {
efp c6h6 0.0 0.0 0.0 0.0 0.0 0.0
--
O 4.0 0.0 0.0
H 4.7 0.7 0.0
H 3.3 -0.7 0.0
--
efp h2o -4.0 0.0 0.0 0.0 0.0 0.0
}
set basis 6-31g
energy('scf')
Whenever an EFP fragment is present in the active molecule, the SCF energy will include EFP contributions.
Warning
Although the EFP geometry is specified alongside the QM
geometry in a molecule name {...}
block, internally the handling
of EFP is not so clean. In straightforward input files that involve
any number of [molecule block, energy/opt/etc, clean()] portions,
there should be no problem; the energy/opt computation will always
be run on the molecule defined in the preceding block. For advanced
users, unexpected difficulties may arise due to: (1) the EFP fragment
from the last molecule block executed will always be active (and
potentially interfering with SCF) and (2) recalling a molecule
through activate(name)
(where name
was the python handle
in the molecule block) will not load up any EFP portion of that
molecule. This divergent treatment is a stopgap while we determine
how best to handle molecules with different domains.
At this time, PSI4 is only able to perform pure-efp single-points and geometry optimizations and mixed qm/efp SCF single-points.
name
molecule composition
calls method
efp
efp
efp
pure EFP
EFP interaction energy (IE) on all frags
mixed QM/EFP
EFP IE on EFP frags only
pure QM
error
scf
scf
scf
pure EFP
error
mixed QM/EFP
SCF energy on QM frags w/coupling to EFP frags, plus EFP IE on EFP frags
pure QM
SCF energy on all frags (normal PSI4 operation)
Fragment Library¶
Below are documented the EFP fragments available from the LIBEFP library.
These systems are accessible in molecule {...}
blocks without
additional configuration.
How to configure libefp for building Psi4¶
Role and Dependencies
Role — In PSI4, libefp is a library that provides additional molecular modeling capabilities (EFP).
Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) libefp
Upstream Dependencies — libefp \(\Leftarrow\) BLAS/LAPACK
CMake Variables
ENABLE_libefp — CMake variable toggling whether Psi4 builds with libefp
CMAKE_PREFIX_PATH — CMake list variable to specify where pre-built dependencies can be found. For libefp, set to an installation directory containing
include/efp.h
libefp_DIR — CMake variable to specify where pre-built libefp can be found. Set to installation directory containing
share/cmake/libefp/libefpConfig.cmake
CMAKE_DISABLE_FIND_PACKAGE_libefp — CMake variable to force internal build of libefp instead of detecting pre-built
CMAKE_INSIST_FIND_PACKAGE_libefp — CMake variable to force detecting pre-built libefp and not falling back on internal build
Examples
Build bundled
>>> cmake -DENABLE_libefp=ON
Build without libefp
>>> cmake
Link against pre-built
>>> cmake -DENABLE_libefp=ON -DCMAKE_PREFIX_PATH=/path/to/libefp/root>>> cmake -DENABLE_libefp=ON -Dlibefp_DIR=/path/to/libefp/configdir
Build bundled despite pre-built being detectable
>>> cmake -DENABLE_libefp=ON -DCMAKE_PREFIX_PATH=/path/to/unwanted/libefp/root/and/wanted/other/dependencies/root -DCMAKE_DISABLE_FIND_PACKAGE_libefp=ON