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.

• Previous bullet had details. To build PSI4 from source and use libefp from conda without thinking, consult sec:condapsi4dev.

• To remove a conda installation, conda remove libefp.

Source

• 

• If using PSI4 built from source and you want libefp built from from source also, enable it as a feature with ENABLE_libefp, and let the build system fetch and build it and activate dependent code.

EFP Fragments

LIBEFP comes with a couple dozen ready-to-use fragments (water, benzene, common solvents, etc.) listed here with source psi4/psi4/share/psi4/efpfrag. 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

1. Build bundled

>>> cmake -DENABLE_libefp=ON

2. Build without libefp

>>> cmake

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

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