Skip to content

2_Planning

Jump to bottom Edit New page
Daniel Smith edited this page Nov 7, 2016 · 53 revisions

How to use setup to configure Psi4 and invoke CMake

Warning!

This page is currently out of date. Please help deprecate it by moving useful information into the docs. Please see CMakeLists.txt in the primary directory for up to date information.

The frontend to CMake is the Python setup script located in $top-level-psi4-dir. This script defines many argparse-style arguments (setup --help for details) and also accepts -D arguments to forward directly to the CMake call.

CMake does a good job scanning your computer to locate libraries, header files, and executables needed for compilation. So it's very possible that from $top-level-psi4-dir source directory, you can call ./setup without any arguments, and it will generate some appropriate defaults, pass these to CMake, invoke cmake, configure the build, create a build directory, and complete, leaving you to only invoke make in the new build directory.

Should this happy scenario not come to pass, or if the default build options are not to your taste, use the links within core dependencies and add-on dependencies to plan a set of arguments to setup tailored to your computer. The following topics may also be helpful.

What are the tools and dependencies strictly required for building Psi4

The core Psi4 build requires the software below. Note that CMake and Python can be satisfied through the Conda Psi4dependencies Package. The links below give examples of how to configure that software for Psi4 and any notes and warnings pertaining to it.

What are the add-on capabilities for Psi4 and what are their dependencies

Each of the items below is an independent additional capability that can be built with Psi4. Sub-items below are the respective additional dependencies of the add-on. Select which, if any, you want, and examine the links for appropriate enable/disable arguments to setup. Note that the default for each may be enabled, disabled, or enabled if dependencies already satisfied, so you may need to explicitly disable add-ons in to tailor your build.

### How to configure code to use high angular momentum basis sets

The LibInt integral code handles arbitrary order angular momentum, but compiling that is prohibitive. The default of 5 is generally good. 6 has met all of a research group's needs for years. 4 is handy for quickly testing other parts of the build.

  • Build with Higher Angular Momentum
    setup --max-am-eri 6
  • Relevant setup Options:
    --max-am-eri MAX_ANGULAR_MOMENTUM
                      The maximum angular momentum level (1=p, 2=d, 3=f,
                      etc.) for the libint and libderiv packages. Note: A
                      value of N implies  a maximum first derivative of N-1,
                      and maximum second derivative of N-2. [default: 5]
  • Relevant cmake Options:
    -DLIBINT_OPT_AM=MAX_ANGULAR_MOMENTUM    -Maximum angular momentum level

### How to see what build configuration options are available

Run ./setup --help to get the summary below (ca. June 2015) and more.

>>> cd $top-level-psi4-dir
>>> ./setup --help
usage: setup [-h] [--cc STRING] [--cxx STRING] [--fc STRING]
         [--max-am-eri MAX_ANGULAR_MOMENTUM]
         [--type [{release,debug,profile}]] [--prefix PATH] [--show]
         [--cmake STRING] [--boost-incdir PATH] [--boost-libdir PATH]
         [--python PYTHON] [--mpi] [--sgi-mpt] [--omp]
         [--mkl [{sequential,parallel,cluster}]]
         [--blas [{auto,builtin,none,/full/path/lib.a}]]
         [--lapack [{auto,builtin,none,/full/path/lib.a}]]
         [--extra-math-flags STRING] [--accelerate] [--cray] [--csr]
         [--scalapack] [--scalasca] [--cxx11 [{on,off}]]
         [--plugins [{on,off}]] [--suffix STRING] [--check] [--memcheck]
         [--coverage] [--static] [--unit-tests] [--vectorization]
         [-D STRING] [--host STRING] [--generator STRING] [--timings]
         [--asan | --msan | --tsan | --ubsan] [--erd {on,off}]
         [--jkfactory {on,off}] [--gpu-dfcc {on,off}]
         [--dummy-plugin {on,off}] [--pcmsolver {on,off}]
         [--chemps2 {on,off}] [--chemps2-dir PATH] [--zlib-dir PATH]
         [--gsl-dir PATH] [--hdf5-dir PATH] [--extra-cc-flags STRING]
         [--extra-cxx-flags STRING] [--extra-fc-flags STRING]
         [--custom-cc-flags STRING] [--custom-cxx-flags STRING]
         [--custom-fc-flags STRING]
         [OBJDIR]
         ...

### How to set CMake and Preprocessor options through the setup script

CMake can always be invoked directly to build Psi4 [](see active cmake). But more often you have a working setup configuration and just need to convey a couple CMake or Preprocessor variables.

  • Build with Hint Variable to CMake
    setup -DGSL_ROOT_DIR=$CONDA/envs/boostenv
  • Relevant setup Options:
    -D STRING             forward directly to cmake (example: -D ENABLE_THIS=1
                      -D ENABLE_THAT=1); you can also forward CPP definitions
                      all the way to the program (example: -D CPP="-DDEBUG"); 
                      also handle multi-word arguments
                      (example: -D MORELIBS="-L/path/to/lib /path/to/lib2")
                      (default: [])
  • Relevant cmake Options:
    -DSTRING              -express to cmake

### How to install elsewhere than /usr/local/psi4

The installation directory is the filesystem location for the executable, the driver, basis set data, and other administrative files. Unless using the conda package, which is relocatable, the installation directory must be specified with configuration flag --prefix before compiling.

  • Build with Specific Install Directory
    setup --prefix /nfs/common/software/psi4
  • Relevant setup Options:
    --prefix PATH                 set the install path for make install [default:
                              /usr/local/psi4]
  • Relevant cmake Options:
    -DCMAKE_INSTALL_PREFIX=PATH   -preferred install location

### How to set up a profiling build

Specifying build type setup --type profile prepares a release build type with the addition of extra flags for linking against the profiler gprof.

### How to compile for debugging

Flags to turn optimizations off and debugging on can be set across the project and plugins with configuration flag --type before compiling.

  • ######Build without optimization

    setup --type debug
  • Relevant setup Options:
    --type [{release,debug,profile}]
                              set the CMake build type [default: release]
  • Relevant cmake Options:
    -DCMAKE_BUILD_TYPE=debug      -set debug flags

### How to compile elsewhere than $top-level-psi4-dir/objdir

How to choose the compilation directory, $objdir

  • ######Build in Specific Directory

    setup [any other compilation configuration options here] obj-intel
  • Relevant setup Options:

positional arguments: OBJDIR build directory [default: /Users/johndoe/psi4/objdir] ```

### How to fix error RuntimeError: value for ERI

You will need to rebuild the code. Start with a fresh $objdir and adjust N in setup --max-am-eri according to here

### How to choose the compilation directory, $objdir

  • the default of $top-level-psi4-dir/objdir is a good choice
  • in-source builds (*.cc and *.o in same directory) are disallowed
  • builds outside $top-level-psi4-dir are permitted

###How to save configuration settings for a future compilation

Create a file like do-configure with the setup command and options on one line.

>>> cd $top-level-psi4-dir
>>> vi do-configure
../setup [your compilation configuration options here]
>>> chmod u+x do-configure
>>> cd $objdir
>>> ../do-configure

### How to run Psi4 from the compilation directory

Substituting the source directory $top-level-psi4-dir, compilation directory $objdir, and a suitable scratch directory, issue the following commands directly in your terminal or place them into your "rc" file and open a new terminal.

  • csh/tcsh shell or ~/.tcshrc

    setenv PATH $objdir/bin:$PATH
setenv PSIDATADIR $top-level-psi4-dir/share
setenv PSI_SCRATCH /path/to/existing/writable/local-not-network/directory/for/scratch/files

  • sh/bash shell or ~/.bashrc

    export PATH=$objdir/bin:$PATH
export PSIDATADIR=$top-level-psi4-dir/share
export PSI_SCRATCH=/path/to/existing/writable/local-not-network/directory/for/scratch/files

How to set $PSIDATADIR and why

Run Psi4.

psi4 sample.in sample.out

### How to run installed Psi4

Substituting the installation directory $prefix and a suitable scratch directory, issue the following commands directly in your terminal or place them into your "rc" file and open a new terminal.

  • csh/tcsh shell or ~/.tcshrc

    setenv PATH $prefix/bin:$PATH
setenv PSI_SCRATCH /path/to/existing/writable/local-not-network/directory/for/scratch/files

  • sh/bash shell or ~/.bashrc

    export PATH=$prefix/bin:$PATH
export PSI_SCRATCH=/path/to/existing/writable/local-not-network/directory/for/scratch/files

Run Psi4.

psi4 sample.in sample.out

###How to set $PSIDATADIR and why

$PSIDATADIR is an environment variable containing the location of the non-compiled parts of the Psi4 codebase (e.g., Python driver, basis sets, databases, EFP fragments). When Psi4 is installed, the location of these components is known relative to the executable, so the location is set internally. When Psi4 is run from the compilation directory, the relative location is not known, so the value must be explicitly set:

  • in the shell
    • csh/tcsh: setenv PSIDATADIR $top-level-psi4-dir/share
    • sh/bash: export PSIDATADIR=$top-level-psi4-dir/share
  • or at runtime: psi4 -p $top-level-psi4-dir/share
Add a custom footer
Add a custom sidebar
Clone this wiki locally