Plugins: Adding New Functionality to PSI4¶
Modular Approach to Development¶
It is slightly cumbersome to the development cycle to recompile PSI4 every time a change is made to the C++ code. It’s also daunting to new developers if they’re required to learn the structure of the source tree, executable initialization code, and makefile systems in the existing code in order to add new features, which was never a problem with Psi3 due to the independent nature of the modules. To overcome these problems, PSI4 now has a useful plugin feature. This allows codes to be developed as standalone entities, which are compiled independently of the Psi source, but can still link against Psi’s vast library. The plugins can be loaded at run-time from any location.
Creating a New Plugin¶
PSI4 can create basic plugins for you and automatically tailor them
to your compilation environment. To create a basic plugin, run the
following while replacing
myplugin with the name of your great code.
If the name you provide is not valid, PSI4 will complain.
>>> psi4 --plugin-name myplugin
PSI4 will create a new directory with the name you specify for the plugin. In this example, a directory named myplugin will be created.
All you need to do is cd into the directory, use PSI4 to generate a Makefile, and type make. Then execute psi4 in the directory on the default input file.
1 2 3 4
>>> cd myplugin >>> `psi4 --plugin-compile` >>> make >>> psi4
PSI4 comes with a few templates that provide an excellent starting point. These include code that demonstrates AO, MO, and SO integrals. Use one of the following commands that meets your needs:
1 2 3 4 5 6
>>> psi4 --plugin-name myplugin --plugin-template aointegrals >>> psi4 --plugin-name myplugin --plugin-template mointegrals >>> psi4 --plugin-name myplugin --plugin-template sointegrals >>> psi4 --plugin-name myplugin --plugin-template wavefunction >>> psi4 --plugin-name myplugin --plugin-template scf >>> psi4 --plugin-name myplugin --plugin-template dfmp2
Creating a New Plugin Using a Conda Pre-compiled Binary¶
PSI4 plugins can also be created using Conda for both PSI4
binary and development environment. On Linux, one can use the
compiler installed alongside
psi4 itself in the Conda distribution
or environment (below,
1 2 3 4 5
.. # prepare .. >>> bash .. >>> export PATH=$PSI4CONDA/bin:$PATH # usually already done from psi4 installation .. >>> cd "$(dirname $(which psi4))"/.. # move into distribution/environment directory, $PSI4CONDA .. >>> conda install gcc # install compilers into expected place
# check (yes, next line gives empty result. yes, LD_LIBRARY_PATH irrelevant) >>> echo $PYTHONHOME $PYTHONPATH $DYLD_LIBRARY_PATH $PSIDATADIR
1 2 3 4 >>> which python psi4 gcc $PSI4CONDA/bin/python $PSI4CONDA/bin/psi4 $PSI4CONDA/bin/gcc
# create and compile plugin >>> psi4 –plugin-name testplugin # generate new plugin – Creating “testplugin” with “basic” template. —————– ==> Created plugin files (in testplugin as basic):__init__.py, doc.rst, pymodule.py, plugin.cc, input.dat, CMakeLists.txt
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 >>> cd testplugin # move into plugin directory >>> `psi4 --plugin-compile` # use build info from parent psi4 loading initial cache file $PSI4CONDA/share/cmake/psi4/psi4PluginCache.cmake -- The CXX compiler identification is GNU 5.2.0 -- Check for working CXX compiler: $PSI4CONDA/bin/g++ -- Check for working CXX compiler: $PSI4CONDA/bin/g++ -- works ... -- Generating done -- Build files have been written to: testplugin >>> make # compile the plugin to produce testplugin.so Scanning dependencies of target testplugin [ 50%] Building CXX object CMakeFiles/testplugin.dir/plugin.cc.o [100%] Linking CXX shared module testplugin.so [100%] Built target testplugin >>> psi4 # run sample input.dat Attention! This SCF may be density-fitted.
Please note that the conda distribution must be in
$PATH or the
conda enviroment must be activated before compilation and execution of
plugins created using this procedure.
Files in a Plugin Directory¶
In addition to the main
myplugin.cc file, a fresh plugin directory contains the following files
- CMakeLists.txt — CMake file governing project plugin.
The plugin source and CMakeLists.txt is independent of platform
and PSI4 installation. You use CMake (version 3.1 or later)
to generate a Makefile for the plugin by pointing it to a specific
PSI4 installation. Run
psi4 --plugin-compileto get a command to execute to generate the Makefile. What that command is doing is loading the compilers and options used to build the parent PSI4 (the
-C psi4PluginCachepart) which in turn can be overridden by passing
cmakeand pointing toward a particular PSI4 (and probably pybind11) library to link against (the
CMAKE_PREFIX_PATHpart) and telling it to do an in-source build (the
.part). Then just run
makein your plugin directory. After any change to the plugin C++ code,
makemust be run in the plugin directory to recompile the
myplugin.soexecutable, but recompiling the main PSI4 code is not necessary. Should you add additional (non-header) files to the plugin or need to link to additional external libraries, add that information here.
- input.dat — Sample input file for the plugin.
__init__.pyfile makes the plugin directory look like a Python module, the plugin can be treated as such in an input file. The location of the plugin directory must be included in
PYTHONPATH, either externally in the calling shell or defined in the input file. This is usually done by manipulating
PSIPATH. Then, the plugin can be loaded as
import mypluginand executed as
energy('myplugin'). Any other Python functions are also available from the input file, e.g.
myplugin.testfunction(), note the namespace protection.
- pymodule.py — Python component of the plugin.
By encoding the sequence of PSI4 module
calls needed to run the plugin in the
run_myplugin()function in this file, the plugin is hooked into the main PSI4 driver function
energy()and so can be accessed through
energy('myplugin')in an input file. Any other Python functions can also be placed in this file.
- __init__.py — Init script for the plugin (in the sense that
the whole plugin directory is a Python module). This file generally won’t
need editing unless additional Python files are added to the plugin
directory (add additional lines to the
# Load Python modulessection) or the plugin depends on .so codes in other plugin directories (add additional plugin_load lines relative to the current plugin directory to the
# Load C++ pluginsection).
- doc.rst — Documentation file. Place in this file any notes,
equations, warnings to users, todo lists, etc.. Plain text is fine,
though reStructuredText is the ultimate goal. Remove the
.. commenttext and build Sphinx documentation for samples of linking keywords, sections, and math. This file is absorbed into the PSI4 documentation, along with any docstrings to Python functions, and the C++ keywords block in the
myplugin.ccfile. See Documentation for building documentation.
Please note that pure virtual functions in a plugin may cause undefined symbols errors when the plugin is loaded.
To create a purely Python plugin, create a new plugin directory, then
myplugin.cc files and
erase the shared object loading portion of
__init__.py. Create as many .py
files as necessary (registering each one in
input.dat as a model for loading the plugin, no recompile ever