Tour of PSI & Design Philosophy

Dr. Justin M. Turney

Friday, January 24, 2014

PSI4

Psi4: An open-source ab initio electronic structureprogram

Psi4 is a new approach to modern quantum chemistry.

The program is written entirely in C++ and relies on a newinfrastructure that has been designed to permit high-efficiencycomputations of both standard and emerging electronic structuremethods.

Psi4: An open-source ab initio electronic structureprogram

Psi4 offers flexible user input built on the Python scriptinglanguage.

This enables...

• both new and experienced users to make full use of theprogram’s capabilities

• even to implement new functionality with moderate effort.

Psi4: open-source

To maximize its impact and usefulness, Psi4 is available throughan open-source license to everyone.

To the best of my knowledge people are working to get Psi4included in the main repositories of Fedora and Debian (and byextension Ubuntu).

Design Philosophy

The design philosophy of Psi4 is to be as user-friendly as possiblewithout sacrificing performance or extensibility and to choose thebest method for the problem.

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

C++ is used for performance critical parts:

• Integrals and transformation

• SCF (HF and DFT)

• Coupled cluster (CC)

• Configuration Interaction (CI)

• Symmetry Adapted Perturbation Theory (SAPT)

• and others

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Design Philosophy

Python is used for everything else:

• Input file

• Procedures for performing a calculation

• Mixing of DFT functionals

• Gn methods

• Focal point

• PubChem interface

Psi4: open-sourceYou can obtain Psi4 from GitHub:

Psi4: open-source

To clone Psi4 onto you box:

1 $ git clone git@github.com:psi4/psi4public.git

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

bin contains scripts needed forconfigure. This directory ishardly ever touched.

Chances are you don’t need tobother with this directory...ever.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

boost contains Psi4’sprovided Boost tarball.

If your system has a compatibleBoost that is use, if not, Psi4will compile one for you.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

doc contains Psi4’sdocumentation or the scriptsand files for generating thedocumentation.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

include contains globalheader files used by bothlibraries and modules.

For example: masses.h,physconst.h, psi4-dec.h,and psifiles.h

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

lib/

basis/

databases/

grids/

plugin/

psi4/

python/

quadratures/

scripts/

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

plugins contains sampleplugin files. These includeaointegrals, backtrans,mointegrals, mp2, andsointegrals.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

samples contains exampleinput files. Each example inputfile lives in it’s ownsubdirectory of samples.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

src contains the C++ sourcecode for the libraries andmodules of Psi4. These will bediscussed in detail shortly.

What do you get when you download Psi4?

Let’s go through the directory structure:

psi4public/

bin/

boost/

doc/

include/

lib/

plugins/

samples/

src/

tests/

tests contains the end testcases for Psi4. The samples

are derived from the tests.

If you’re looking for inputs tostart from don’t use these asthey contain extra code specificfor testing.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

lib3index provides classes forDF/RI integrals, Choleskydecomposition, and other typesof decompositions.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libchkpt provides access tothe old file32 checkpoint file.

This is here mostly for legacycodes. Newer codes arediscouraged from using it.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libciomr provides a collectionof functions that deal withfiles, matrices, printing, somemath (matrix multiplicationand diagonalization).

Newer codes tend to not usethis library much.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libderiv computes 1st and2nd derivatives of two-electronintegrals using the Obara-Saikarecursion scheme.

You should not directly use thislibrary. Instead, use libmints

to abstract and simply theinterface.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libdiis handles DIISextrapolations.

Compatible with libdpd

buffers and libmints

matrices.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libdisp handles computingdispersion corrections; e.g.Grimme’s -D2 and -D3.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libdpd Daniel’s DirectProduct Decomposition libraryfor tensors commonly foundcoupled cluster theory.

Andy Simmonett has beenworking to add DF/RIcapabilities to libdpd.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

liberd an integrals packagefrom ACESIII. Currently, onlycompiled with using CMake.

This is the only Fortran codefound in Psi4.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libfock handles all thingspertaining to a Fock matrix.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libfunctional handlescomputing of DFT functionalsand their quadratures. The lowlevel code for DFT lives here.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libint the original integralslibrary of Psi. You should notdirectly use this library uselibmints instead.

What libraries are provided by Psi4?Let’s go through the libraries provided by Psi4:

lib/

lib3index/

libchkpt/

libciomr/

libderiv/

libdiis/

libdisp/

libdpd/

liberd/

libfock/

libfunctional/

libint/

libiwl/

libiwl the Integrals WithLabels library. Handles readingAO integrals from disk.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libmints handles computingone- and two-electron integralsin a user-friendly fashion.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

liboptions manages all useroptions from the input file.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libplugin manages C++ sideof the plugin system in Psi4.Most programmers need notworry about this.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libpsio PSI’s I/O manager.All binary files operations gothrough this library.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libqt “qt“ short for theQuantum Trio is a collection ofuseful functions usedthroughout Psi4/

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libsapt solver core solverfor the Symmetry AdaptedPerturbation Theory module.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libscf solver solver for HFtheory and DFT.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libthce the TensorHyper-Contraction Engine.Rob will discuss this later.

What libraries are provided by Psi4?

lib/

libmints/

liboptions/

libplugin/

libpsio/

libqt/

libsapt solver/

libscf solver/

libthce/

libtrans/

libtrans the integraltransformation library. Veryflexible. Can transformationand back-transform to andfrom any file.

Developer Friendly - Plugin System

Compiling a large software package like Psi4 can take 30 minutesor more depending on configuration and computer.

So, we came up with a plugin system that allows developers towork with just their code (not worrying about Psi4) but stillhaving all of Psi4’s capabilities available to them.

Developer Friendly - Plugin System

NOTE: Plugins are only available if you configured your version ofPsi4 with the --with-plugins command line configure option.

1 $ ../configure −−with−plugins

While developing we recommend the following minimum configureflags:

1 $ ../configure −−without−opt −−with−debug −−with−plugins

Creating a new plugin

NOTE: This assumes the psi4 executable is in your active PATH

environment variable.

Tell Psi4 to create your new plugin:

1 $ psi4 −−new−plugin hellopsi4

The syntax for this call is: --new-plugin name {+templatename}

Creating a new plugin

The current list of plugin templates:

• aointegrals

• mointegrals

• scf

• sointegrals

• wavefunction

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

Makefile contains the make

rules for compiling this pluginagainst the Psi4 used to createit.

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

init .py includes Pythoncommands to ensure yourplugin is loaded when Psi4runs.

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

doc.rst contains adocumentation template foryour plugin in restructured textformat.

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

hellopsi4.cc is your newbasic plugin source file.

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

input.dat basic input filewith enough in it to run yourplugin.

Creating a new plugin

1 $ psi4 −−new−plugin hellopsi4

hellopsi4/

Makefile

init .py

doc.rst

hellopsi4.cc

input.dat

pymodule.py

pymodule.py template Pythonwrapper for your plugin.

Executes SCF prior to callingyour code.

This serves as an examplewhen you’re incorporating yourplugin fully into Psi4 proper.

The input file: input.dat

1 sys.path.insert(0, ’./..’)2 import hellopsi43

4 molecule {5 O6 H 1 R7 H 1 R 2 A8

9 R = .910 A = 104.511 }

13 set {14 basis sto−3g15 }16

17 set hellopsi4 {18 print 119 }20

21 energy(’hellopsi4’)22

23 hellopsi4.exampleFN()

What’s in hellopsi4.cc?

Let’s go through the code:

1 #include <libplugin/plugin.h>2 #include <psi4−dec.h>3 #include <libparallel/parallel.h>4 #include <liboptions/liboptions.h>5 #include <libmints/mints.h>6 #include <libpsio/psio.hpp>7

8 INIT PLUGIN9

10 using namespace boost;11

12 namespace psi{ namespace hellopsi4 {

What’s in hellopsi4.cc?

Let’s go through the code:

14 extern ”C”15 int read options(std::string name, Options& options)16 {17 if (name == ”HELLOPSI4”|| options.read globals()) {18 /∗− The amount of information printed to the output file −∗/19 options.add int(”PRINT”, 1);20 }21

22 return true;23 }

What’s in hellopsi4.cc?

Let’s go through the code:

25 extern ”C”26 PsiReturnType hellopsi4(Options& options)27 {28 int print = options.get int(”PRINT”);29

30 /∗ Your code goes here ∗/31 return Success;32 }33

34 }} // End namespaces

What can we assume in this plugin?

30 /∗ Your code goes here ∗/

At this point in the code we can safely assume

• Options from the input file have been validated and currentoptions (specific to our plugin and the globals) are availableto us.

• The molecule and the current geometry are available to us.

• That a standard HF calculation was performed.

Debugging your plugin

Common programs used in debugging include:

• gdb → The GNU Debugger

• lldb → Low Level Virtual Machine Debugger. Standard onMac OS X Mavericks

• idb → Intel Debugger. Available if you have Intel compilers.

Diagnosing memory issues

• valgrind → valgrind.org

Using valgrind

You will find it very useful to use a Python suppression file whenusing valgrind with Psi4.

In the file $HOME/.valgrindrc put the following; replacing$top srcdir with the location of your Psi4 code.

1 −−suppressions=$top srcdir/lib/valgrind−python.supp

Summary

We have taken a whirlwind tour of Psi4 focused on giving you abroad overview of the code and working with it. In the followingtalks more detail will be given into specific libraries and thecapabilities of Psi4.