2. Installation

2.1. Preparing an environment

It is good idea to install pysisyphus into a separate python environment, whether it is an Anaconda environment or a virtualenv environment, derived from the system python installation or a pyenv installation (preferred).

# Optional: Create separate Anaconda environment
conda create -n pysis-env python=3.9
# Activate conda environment
conda activate pysis-env

# Optional: Create separate virtual environment
python -m venv pysis-env
# On some linux distributions 'python3' is used instead of 'python', e.g. Ubuntu
# python3 -m venv pysis-env
# Activate  virtual environment. Preferably, an absolute path pointing to the
# 'activate' script should be used.
source pysis-env/bin/activate

2.2. Installation from PyPI with pip

This installs the latest stable release as published on PyPI. If you don't want to do any development work this is the preferred way of installing pysisyphus.

python -m pip install pysisyphus
# Installation of additional optional dependencies is also possible
# python -m pip install pysisyphus[test]

If you run into any problems please make sure that your pip version is recent enough. A pip upgrade is achieved via:

python -m pip install --upgrade pip

2.3. Installation from source

Decide on an $install_dir and clone the repository from github. If you want to change the code after installation (develop) do an editable (-e) installation with pip.

git clone https://github.com/eljost/pysisyphus.git $install_dir
cd $install_dir
# Install with -e if you want an editable installation
python -m pip install [-e] .
# Installation of extras is also possible. 'sphinx' is only needed if you
# want to build the documentation.
# python -m pip install [-e] .[test]

With an editable installation it is also easy to use other branches, besides the master branch, e.g., the dev branch to test out a new feature.

git switch dev

2.4. Setting up .pysisyphusrc

pysisyphus interfaces several quantum chemistry codes and related software (Multiwfn, Jmol). Software available to pysisyphus is registered in $HOME/.pysisyphusrc, so pysisyphus knows which command to execute an/or where to find the binaries.

Depending on the software different choices were made how it is registered. An example .pysisyphusrc is given below, with a short comment for each software.

# Excited state calculators

[gaussian09]
# Cmd to execute. Please ensure that g09 is on your $PATH.
cmd=g09
formchk_cmd=formchk
unfchk_cmd=unfchk

[gaussian16]
# Cmds to execute. Please ensure that the binaries are found in your $PATH.
cmd=g16
formchk=formchk
unfchk=unfchk
rwfdump=rwfdump

[openmolcas]
# Cmd to execute. Please ensure that pymolcas is on your $PATH.
cmd=pymolcas

[orca]
# ORCA needs the full path to its binary, so please provide the full path.
cmd=/scratch/programme/orca_4_2_0_linux_x86-64_openmpi314/orca

#[pyscf]
# pyscf must not have an explicit entry in the .pysisyphusrc. pysisyphus uses
# the python API of pyscf, so it is mandatory that is installed in the same environment
# as pysisyphus.

#[turbomole]
# Turbomole must not have an explicit entry in the .pysisyphusrc. The user has to take
# care that everything is set up correctly, e.g. TM-binaries are on the PATH etc...
# The respective commands are hardcoded into pysisyphus (dscf, ridft, ricc2, ...)

# Ground state calculators

[mopac]
# Similar to Psi4. An example is given below.
cmd=/user/johannes/bin/runmopac.sh

[psi4]
# As the Psi4 installation without conda is, to put it slightly, tricky it was
# decided to allow the installation of Psi4 into a separate conda environment.
# pysisyphus then creates a Psi4 input and sends it to the (bash)-script given below
# that accepts/expects one argument. It is the responsibility of the scrip to activate
# the appropriate conda environment and submit the Psi4 input. An example runpsi4.sh
# script is given below.
cmd=/user/johannes/bin/runpsi4.sh

#[qcengine]
# QCEngine must not have an entry explicit entry in the .pysisyphusrc. It is used
# via its python interface and can be installed as an extra with pip (see above).
# The user is referenced to the QCEngine-documentation for any further questions.

[xtb]
# Cmd to execute. Please ensure that xtb is on your $PATH.
cmd=xtb

[openmolcas]
# Make sure that the MOLCAS variable is set.
cmd=pymolcas

[cfour]
# Parallelism is managed by the user by setting environment variables in the runscript,
# as the name of the environment variable for MPI parallelism depends on how CFOUR_MPI_CORES
# was compiled. The GENBAS file must also be symlinked by the runscript.
# A sample is provided below.
cmd=/home/ghjones/bin/runcfour.sh

# Utilities

[wfoverlap]
# Cmd to execute. Please ensure that wfoverlap is on your $PATH. The binary/source
# can be obtained from https://github.com/sharc-md/sharc/tree/master/bin
cmd=/scratch/wfoverlap_1.0/bin/wfoverlap.x

[mwfn]
# Cmd to execute. Please ensure that Multiwfn is on your $PATH. Otherwise put an
# absolute path here. By default pysisyphus looks up "Multiwfn", so if you would
# put a relative path here you don't have to, as this is already covered by the
# defaults.
cmd=Multiwfn

[jmol]
# Cmd to execute. The same arguments apply for jmol as for Multiwfn. "jmol" is
# already the default.
cmd=jmol

When the specified path/cmd is not absolute, but relative (e.g. for xtb, g16, ...) the corresponding binaries have to be available on the $PATH and all other environment variables have to be set up correctly by the user.

2.5. Example runpsi4.sh

#!/bin/bash

# Afaik this doesn't work in non-interactive shells ...
# See https://github.com/conda/conda/issues/8072
# conda activate psi4
source /scratch/programme/anaconda3/bin/activate psi4
#conda activate psi4
psi4 -o stdout $1

2.6. Example runmopac.sh

#!/bin/bash

module purge
module load mopac

MOPAC2016.exe $1

2.7. Example runcfour.sh

#!/bin/bash

module purge
module load cfour
export OMP_NUM_THREADS=4
export CFOUR_MPI_CORES=1 # The name of this environment variable depends on how you compiled CFOUR
[ ! -f GENBAS ] && ln -s /software/cfour/basis/GENBAS
xcfour > out.log 2>&1

2.8. Verifying Installation

By executing pytest -v --pyargs pysisyphus.tests a series of quick tests can be executed, verifing successful calculator setup. Running these tests requires pyscf and pytest to be present (pip install pyscf pytest).