# Installation and Runtime Configuration

- FAQ
  - Obtaining and Updating PSI4
  - Configuring and Installing PSI4 via Binary
  - Configuring, Building, and Installing PSI4 via Source
  - Non-QC Dependencies
  - QC Dependencies and Extensions
  - Testing
  - Runtime Setup
  - Running PSI4
  - Runtime Errors and Debugging
  - Managing Code
  - Miscellaneous
- Obtaining PSI4
  - How to obtain Psi4: start with find-the-code quiz, end in `{top-level-psi4-dir}`
  - Find-the-code Quiz
  - Binary Installer
  - Conda Binary Package
  - Clone from GitHub Repository
  - Fork from GitHub Repository
  - Tarball from GitHub Repository
  - Psi3 from SourceForge
  - What is the suggested GitHub workflow
- Compiling and Installing from Source
  - Planning: how to configure Psi4 and invoke CMake
  - How to build and install Psi4, the compact version
  - How to build, test, and install Psi4, in detail
  - What are the tools and dependencies strictly required for building Psi4
  - What are the add-on capabilities for Psi4 and what are their dependencies
  - How to configure code to use high angular momentum basis sets
  - How to get high angular momentum integrals from conda
  - How to see what build configuration options are available
  - How to install elsewhere than `/usr/local/psi4`
  - How to compile for debugging
  - How to fix error “`RuntimeError: value for ERI`”
  - How to choose the compilation directory, `{objdir}`
  - How to save configuration settings for a future compilation
  - What is the directory layout of the installed or staged Psi4
  - How to run Psi4 as executable after compilation
  - How to solve `ModuleNotFoundError: No module named 'psi4'`
  - How to configure paths for PsiAPI
  - How to run Psi4 as Python module after compilation
  - How to run Psi4 as executable or Python module from conda installation
  - How to run Psi4 as executable after compilation using driver from source
  - Why not to set `PSIDATADIR`
  - How to configure C++ and C compilers for building Psi4
  - What C and C++ compilers and versions are approved
  - How to obtain C and C++ compilers for Mac without Fink, MacPorts, or Homebrew
  - How to satisfy the GCC >= 4.9 requirement on Linux without updating the OS
  - How to configure a Psi4 build on Cray
  - How to configure Fortran compilers for building Psi4
  - What Fortran compilers are approved
  - How to obtain a Fortran compiler for Mac without Fink, MacPorts, or Homebrew
  - How to configure BLAS/LAPACK for building Psi4
  - How to configure Python for building Psi4
  - What Python is Psi4 running
  - How to fix “`undefined symbol: _Py_FalseStruct`”
  - How to use `gdb` and `lldb` with Psi4
  - How to see the actual compiling commands (or errors) with `cmake`
  - How to highlight git merge conflicts in `vi`
  - How to handle “runtime library may be hidden” when building with Anaconda Python
  - How to set up the scratch directory
  - How do I retain specific Psi4 scratch files
  - How to use Psi4 within a PBS queue
  - How to update and rebuild Psi4
  - How to run a minute’s worth of tests
  - How to run a subset of tests
  - How to see CTest testing errors
  - How to test a Psi4 installation
  - How to refer to Psi4
  - How to get a Psi4 logo file
  - How to use a local Add-On repository in the Psi4 build
- Installing from Binary
  - How to install a Psi4 binary with the Psi4conda installer, download site
  - How to install a Psi4 binary with the Psi4conda installer, command-line
  - How to install a Psi4 binary into an Ana/Miniconda distribution
  - How to update a Psi4 binary
  - How to use conda to compile Psi4 faster and easier
  - What do the conda packages psi4 & psi4-dev and the installer psi4conda contain
  - Quick Installation
  - Detailed Installation of Miniconda
  - Detailed Installation of PSI4
  - Useful Commands
  - Troubleshooting

## Scratch Files and Elementary Restart

One very important part of user configuration at the end of the installation process is to tell PSI4 where to write its temporary (“scratch”) files. Electronic structure packages like PSI4 can create rather large temporary disk files. It is very important to ensure that PSI4 is writing its temporary files to a disk drive physically attached to the computer running the computation. If it is not, it will significantly slow down the program and the network. By default, PSI4 will write temporary files to `/tmp`, but this directory is often not large enough for typical computations. Therefore, you need to (a) make sure there is a sufficiently large directory on a locally attached disk drive (100GB–1TB or more, depending on the size of the molecules to be studied) and (b) tell PSI4 the path to this directory. Scratch file location can be specified through the `PSI_SCRATCH` environment variable or through the `~/.psi4rc` file (see section ~/.psi4rc File). Most of the time, `PSI_SCRATCH` is preferred, and it overrides any existing `~/.psi4rc` setting. You can set up `PSI_SCRATCH` by issuing the following commands in a terminal, or including them in the appropriate `rc` file.

    # csh, tcsh: add to shell or ~/.tcshrc file
    setenv PSI_SCRATCH /path/to/existing/writable/local-not-network/disk/for/scratch/files

    # sh, bash: add to shell or ~/.bashrc (Linux/Windows) or ~/.bash_profile (Mac) file
    export PSI_SCRATCH=/path/to/existing/writable/local-not-network/disk/for/scratch/files

PSI4 has a number of utilities that manage input and output (I/O) of quantities to and from the hard disk. Most quantities, such as molecular integrals, are intermediates that are not of interest to the user and can be deleted after the computation finishes, but pertinent details of computations are also written to a checkpoint file and might be useful in subsequent computations. All files are written to the designated scratch numbered by content and labeled with the process id, then are deleted at the end of the computation, unless otherwise instructed by the user.

A Python callable handle to the PSI4 I/O management routines is available, and is called `psi4_io`. To instruct the I/O manager to send all files to another location, say `/scratch/user`, add the following command to your input file:

    1
    psi4_io.set_default_path('/scratch/user')

For batch jobs running through a queue, it might be more convenient to use an environmental variable (in this case `$MYSCRATCH`) to set the scratch directory; the following code will do that:

    1
    2
    3
    4
    import os
    scratch_dir = os.environ.get('MYSCRATCH')
    if scratch_dir:
        psi4_io.set_default_path(scratch_dir + '/')

Individual files can be sent to specific locations. For example, file 32 is the checkpoint file that the user might want to retain in the working directory (i.e., where PSI4 was launched from) for restart purposes. This is accomplished by the commands below:

    1
    2
    3
    4
    5
    6
    psi4_io.set_specific_path(32, './')
    psi4_io.set_specific_retention(32, True)

    # equivalent to above
    psi4_io.set_specific_path(PSIF_CHKPT, './')
    psi4_io.set_specific_retention(PSIF_CHKPT, True)

A guide to the contents of individual scratch files may be found at PSIOH Intermediate Files. To circumvent difficulties with running multiple jobs in the same scratch, the process ID (PID) of the PSI4 instance is incorporated into the full file name; therefore, it is safe to use the same scratch directory for calculations running simultaneously. This also means that if the user wants PSI4 to use information from a previous file, like molecular orbitals, he needs to provide the name of the file. This can be done through the `restart_file` option

    1
    energy('scf',restart_file='./psi.PID.name.filenumber')

where by default, PID is the process number, name the name of the molecule, and filenumber is listed in content. Only the filenumber is necessary for the driver to appropriately rename the file for the next PSI4 job, and if none is found it defaults to 32, a checkpoint file. If two or more files are to be read, they need to be provided as a Python list

    1
    energy('scf',restart_file=['./file1.filenumber','./file2.filenumber'])

Note that the `restart_file` options is only available for energy procedures as of now.

Executing PSI4 with the `psi4 -m` (for messy) flag will prevent files being deleted at the end of the run:

    1
    psi4 -m

## `~/.psi4rc` File

Caution

It is very easy to forget about the `~/.psi4rc` file you once created, leading to great confusion over why all your jobs are using the wrong memory or are suddenly not density-fit. Also be aware that `~/.psi4rc` contents count as part of your input file (invoked after e.g. `from psi4 import *` and before your Psithon–>Python parsed input commands), so these settings take priority over command-line arguments to the `psi4` executable. Please use the `~/.psi4rc` file conscientiously.

If using the environment variable `PSI_SCRATCH` is inconvenient, or if some `psi4_io` commands must be present in all input files, the `~/.psi4rc` resource file can be used (example psi4/samples/example_psi4rc_file).

All the commands mentioned in section Scratch Files and Elementary Restart can be used in this file.

To set up the scratch path:

    1
    psi4_io.set_default_path('/scratch/user')

To set up the scratch path from a variable `$MYSCRATCH`:

    1
    2
    3
    4
    import os
    scratch_dir = os.environ.get('MYSCRATCH')
    if scratch_dir:
        psi4_io.set_default_path(scratch_dir + '/')

To set up a specific path for the checkpoint file and instruct PSI4 not to delete it:

    1
    2
    3
    4
    5
    6
    psi4_io.set_specific_path(32, './')
    psi4_io.set_specific_retention(32, True)

    # equivalent to above
    psi4_io.set_specific_path(PSIF_CHKPT, './')
    psi4_io.set_specific_retention(PSIF_CHKPT, True)

The Python interpreter will execute the contents of the `~/.psi4rc` file in the current user’s home area (if present) before performing any tasks in the input file. As a consequence, the commands in the input files supersede any instructions in the `~/.psi4rc` file. During execution, the `~/.psi4rc` defaults will be loaded in first, but then the commands in the input file will be executed.

The `~/.psi4rc` file can also be used to define constants that are accessible in input files or to place any Python statements that should be executed with every PSI4 instance.

## Threading

Most new modules in PSI4 are designed to run efficiently on SMP architectures via application of several thread models. The de facto standard for PSI4 involves using threaded BLAS/LAPACK (particularly Intel’s excellent MKL package) for most tensor-like operations, OpenMP for more general operations, and C++ `std::thread` for some special-case operations. Note: Using OpenMP alone is a really bad idea. The developers make little to no effort to explicitly parallelize operations which are already easily threaded by MKL or other threaded BLAS. Less than 20% of the threaded code in PSI4 uses OpenMP, the rest is handled by parallel DGEMM and other library routines. From this point forward, it is assumed that you have compiled PSI4 with OpenMP and MKL (Note that it is possible to use g++ or another compiler and yet still link against MKL).

Control of threading in PSI4 can be accomplished at a variety of levels, ranging from global environment variables to direct control of thread count in the input file, to even directives specific to each model. This hierarchy is explained below. Note that each deeper level trumps all previous levels.

(1) OpenMP/MKL Environment Variables

Deprecated since version 1.1: Environment variables `OMP_NUM_THREADS` and `MKL_NUM_THREADS` do not affect threading in PSI4.

(2) The -n Command Line Flag

To change the number of threads at runtime, the `psi4 -n` flag may be used. An example is:

    psi4 -i input.dat -o output.dat -n 4

which will run on four threads. Note that is is not available for PsiAPI mode of operation.

(3) Setting Thread Numbers in an Input

For more explicit control, the Process::environment class in PSI4 can override the number of threads set by environment variables. This functionality is accessed via the `psi4.set_num_threads()` function, which controls both MKL and OpenMP thread numbers. The number of threads may be changed multiple times in a PSI4 input file. An example input for this feature is:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    # A bit small-ish, but you get the idea
    molecule h2o {
    0 1
    O
    H 1 1.0
    H 1 1.0 2 90.0
    }

    set scf {
    basis cc-pvdz
    scf_type df
    }

    # Run from 1 to 4 threads, for instance, to record timings
    for nthread in range(1,5):
        set_num_threads(nthread)
        energy('scf')

In PsiAPI mode of operation, this syntax, `psi4.set_num_threads(nthread)`, is the primary way to control threading.

(4) Method-Specific Control

Even more control is possible in certain circumstances. For instance, the threaded generation of AO density-fitted integrals involves a memory requirement proportional to the number of threads. This requirement may exceed the total memory of a small-memory node if all threads are involved in the generation of these integrals. For general DF algorithms, the user may specify:

    1
    set MODULE_NAME df_ints_num_threads n

to explicitly control the number of threads used for integral formation. Setting this variable to 0 (the default) uses the number of threads specified by the `set_num_threads()` Psithon method or the default environmental variables.

## PBS job file

To run a PSI4 job on a PBS queueing system, you need to properly set up all necessary variables in the PBS job file. Below is a minimal example of a PBS job file for a threaded job, and a short explanation for each section.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    #!/bin/tcsh
    #PBS -j oe
    #PBS -l pmem=2120mb
    #PBS -N jobname
    #PBS -V

    cd $PBS_O_WORKDIR
    setenv myscratch /scratch/user/psi4.$PBS_JOBID

    foreach i (`sort $PBS_NODEFILE | uniq`)
        echo "Creating scratch directory " $myscratch " on " $i
        ssh $i rm -rf $myscratch
        ssh $i mkdir -p $myscratch
    end

    unsetenv PSIDATADIR
    setenv PSI_SCRATCH $myscratch
    if ! ( $?PSIPATH ) setenv PSIPATH ""
    setenv PSIPATH /path/to/external/modules:${PSIPATH}
    setenv PSIPATH /path/to/python/modules:${PSIPATH}
    /psi/install/directory/bin/psi4 -i input.in -o input.out -n 4

    foreach i (`sort $PBS_NODEFILE | uniq`)
        echo "Removing scratch directory " $myscratch " on " $i
        ssh $i rm -rf $myscratch
    end

The top section features PBS-specific commands. These depend on the specific characteristics of your PBS queuing system but they may include:

    1
    2
    3
    4
    5
    #!/bin/tcsh
    #PBS -j oe
    #PBS -l pmem=2120mb
    #PBS -N jobname
    #PBS -V

The `PBS -j oe` option instructs PBS to write any output or error message from the queuing system in dedicated files. `PBS -l pmem=2120mb` requests 2120 MB of memory for each thread on the node. The total memory requested for the job by PBS should generally be slightly greater than what indicated in the input file (see memory setting).

Then, we move to the working directory using PBS variable `$PBS_O_WORKDIR` and we create scratch directories on every node, using the `$PBS_NODEFILE` which points to a file containing a list of the nodes attributed to the job.

    1
    2
    3
    4
    5
    6
    7
    8
    cd $PBS_O_WORKDIR
    setenv myscratch /scratch/user/psi4.$PBS_JOBID

    foreach i (`sort $PBS_NODEFILE | uniq`)
        echo "Creating scratch directory " $myscratch " on " $i
        ssh $i rm -rf $myscratch
        ssh $i mkdir -p $myscratch
    end

The next section is very important as it sets the environment variables needed by PSI4:

    1
    2
    3
    4
    5
    unsetenv PSIDATADIR
    setenv PSI_SCRATCH $myscratch
    if ! ( $?PSIPATH ) setenv PSIPATH ""
    setenv PSIPATH /path/to/external/modules:${PSIPATH}
    setenv PSIPATH /path/to/python/modules:${PSIPATH}

`PSIDATADIR` does not need to be set. In the present example we unset it to make sure it does not interfere with the internal location-finding. `PSIPATH` is needed only if you are using external modules or plugins in PSI4 and should point to the directories where they can be found. In the present example, we make sure the variable is set with `if ! ( $?PSIPATH ) setenv PSIPATH ""` before adding more paths to it. Finally, `PSI_SCRATCH` should point to a fast, existing local disk for temporary file storage. To use 4 threads for OpenMP parallelization and threaded BLAS (see section Threading), we set `-n4` below. The next step is then to actually run the computation:

    1
    /psi/install/directory/bin/psi4 -i input.in -o input.out -n 4

And then to clean up the scratch directories previously created:

    1
    2
    3
    4
    foreach i (`sort $PBS_NODEFILE | uniq`)
        echo "Removing scratch directory " $myscratch " on " $i
        ssh $i rm -rf $myscratch
    end

Note again that the specific commands for your PBS system may differ. Refer to your system administrator.

## Command Line Options

PSI4 can be invoked with no command line arguments, as it takes as input by default the file “input.dat” and directs output by default to “output.dat”. The set of three commands below are completely equivalent, while the fourth is, perhaps, the most common usage.

    1
    2
    3
    4
    5
    >>> psi4
    >>> psi4 -i input.dat -o output.dat
    >>> psi4 input.dat output.dat

    >>> psi4 descriptive_filename.in descriptive_filename.out

Command-line arguments to PSI4 can be accessed through `psi4 --help`.

`-a````,` `--append```

  Append results to output file. Default: Truncate first

`-h````,` `--help```

  Display the command-line options and usage information.

`-i``<filename>``,` `--input``<filename>`

  Input file name. Default: input.dat

`-k````,` `--skip-preprocessor```

  Skips input preprocessing. Expert mode.

`-l``<name>``,` `--psidatadir``<name>`

  Mainly for use by developers, this overrides the value of `PSIDATADIR` and specifies the path to the Psi data library (ends in `share/psi4`)

`-m````,` `--messy```

  Leave temporary files after the run is completed.

`-n``<threads>``,` `--nthread``<threads>`

  Number of threads to use (overrides `OMP_NUM_THREADS`)

`-o``<filename>``,` `--output``<filename>`

  Output file name. Use `stdout` as <filename> to redirect to the screen. Default: when the input filename is “input.dat”, then the output filename defaults to “output.dat”. Otherwise, the output filename defaults to the the input filename with any any “.in” or “.dat” extension replaced by “.out”

`-p``<prefix>``,` `--prefix``<prefix>`

  Prefix for psi files. Default: psi

`-s``<name>``,` `--scratch``<name>`

  This overrides the value of `PSI_SCRATCH` and provides a path to the location of scratch files

`-v````,` `--verbose```

  Print a lot of information, including the Psithon translation of the input file

`-V````,` `--version```

  Print version information.

      1
      2
      >>> psi4 --version
      0.4.262

## Environment Variables

These environment variables will influence PSI4’s behavior.

`MKL_NUM_THREADS`

  Number of threads to use by operations with Intel threaded BLAS libraries.

`OMP_NESTED`

  Do access nested DGEMM in OpenMP sections in DFMP2 for multi-socket platforms. This is very low-level access to OpenMP functions for experienced programmers. Users should leave this variable unset or set to `False`.

`OMP_NUM_THREADS`

  Number of threads to use by modules with OpenMP threading.

`PATH`

  Path for interfaced executables.

  Note

  Configuring PSI4 through `PSIPATH` is preferred to modifying this environment variable.

  To run Kállay’s MRCC program (see MRCC), the `dmrcc` executable must be in `PATH`. Likewise to run Grimme’s dftd3 program (see dftd3), the `dftd3` executable must be in `PATH`.

`PSI_SCRATCH`

  Directory where scratch files are written. Overrides settings in `~/.psi4rc`. It is very important to ensure that PSI4 is writing its scratch files to a disk drive physically attached to the computer running the computation. If it is not, it will significantly slow down the program and the network.

  Modify `PSI_SCRATCH` through normal Linux shell commands before invoking psi4

      # csh, tcsh: add to shell or ~/.tcshrc file
      setenv PSI_SCRATCH /scratch/user

      # sh, bash: add to shell or ~/.bashrc (Linux/Windows) or ~/.bash_profile (Mac) file
      export PSI_SCRATCH=/scratch/user

`PSIPATH`

  Path in which PSI4 looks for user extensions to the built-in libraries. Specifically, directories containing user basis sets, EFP fragments, databases, plugins, and interfaced executables ( `dmrcc` for MRCC and `dftd3` for DFTD3 ) should be placed in this colon-separated list.

  PSI4 is designed so that user extensions that are findable through `PSIPATH` can be used in input files entirely like their built-in counterparts, without additional tagging as non-standard.

  The typical search path is first the built-in libraries, next each `PSIPATH` directory in order, and finally the execution directory (I won’t swear everything tacks on the execution directory).

  Path in which the Python interpreter looks for modules to import. For PSI4, these are generally plugins or databases.

  Modify `PSIPATH` through normal Linux shell commands before invoking psi4

      # csh, tcsh: add to shell or ~/.tcshrc file
      setenv PSIPATH /home/user/psiadditions:/home/user/gbs

      # sh, bash: add to shell or ~/.bashrc (Linux/Windows) or ~/.bash_profile (Mac) file
      export PSIPATH=/home/user/psiadditions:/home/user/gbs

`PYTHONPATH`

  Path in which the Python interpreter looks for modules to import. For PSI4, these are generally plugins or databases.

  Note

  Configuring PSI4 through `PSIPATH` is preferred to modifying this environment variable.

  Modification of `PYTHONPATH` can be done in three ways, equivalently.

  - Normal Linux shell commands.

        # csh, tcsh: add to shell or ~/.tcshrc file
        setenv PYTHONPATH /home/user/psiadditions:$PYTHONPATH

        # sh, bash: add to shell or ~/.bashrc (Linux/Windows) or ~/.bash_profile (Mac) file
        export PYTHONPATH=/home/user/psiadditions:$PYTHONPATH

  - Place the path in the `~/.psi4rc` file so that it is available for every PSI4 instance.

        1
        sys.path.insert(0, '/home/user/psiadditions')

  - Place the path in the input file, either absolute or relative.

        1
        2
        sys.path.insert(0, '../../psiadditions')
        sys.path.insert(0, '/home/user/psiadditions')

`PSIDATADIR`

  Path in which the PSI4 executable looks for its non-compiled dependencies (i.e., basis sets, databases, quadratures, etc.). This path is always known by the PSI4 program or shared library, so this variable is relevant primarily to developers wanting a non-standard location. Value should be set to directory containing driver, basis, etc. directories, generally ending in `share/psi4`.