# Interface to CheMPS2 by S. Wouters

Code author: Sebastian Wouters

Section author: Lori A. Burns

Module: Keywords, PSI Variables, Samples

Note

As of late June 2016, DMRG keywords in PSI4 have been realigned with those of the chemps2 executable, plus a “dmrg_” prefix. The only exceptions are the orbital space PSI4 keywords RESTRICTED_DOCC (formerly CheMPS2 used FROZEN_DOCC, contrary to its definition) and ACTIVE which are passed along to CheMPS2 keywords `NOCC` and `NACT`. A translation table is available.

## Installation

Binary

- CheMPS2 is available as a conda package for Linux and macOS (and Windows, through the Ubuntu shell).

- If using the PSI4 binary, CheMPS2 has already been installed alongside.

- If using PSI4 built from source, and anaconda or miniconda has already been installed (instructions at Quick Installation), CheMPS2 can be obtained through `conda install chemps2`. Then enable it as a feature with ENABLE_CheMPS2, hint its location with CMAKE_PREFIX_PATH, and rebuild PSI4 to detect CheMPS2 and activate dependent code.

- Previous bullet had details. To build PSI4 from source and use Libint from conda without thinking, consult sec:condapsi4dev.

- To remove a conda installation, `conda remove chemps2`.

Source

- If using PSI4 built from source and you want CheMPS2 built from from source also, enable it as a feature with ENABLE_CheMPS2, and let the build system fetch and build it and activate dependent code.

## Methods

Density matrix renormalization group capabilities of PSI4 through CheMPS2
name | calls method | Energy | Gradient
--- | --- | --- | ---
dmrg-ci | DMRG configuration interaction (CI) | RHF/ROHF | —
dmrg-scf | DMRG complete active space SCF (CASSCF) | RHF/ROHF | —
dmrg-caspt2 | DMRG CAS with 2nd-order perturbation theory (CASPT2) | RHF/ROHF | —

## DMRG Keywords

### DMRG_CASPT2_CALC

> Do calculate the DMRG-CASPT2 energy after the DMRGSCF calculations are done?

> - Type: boolean
> - Default: false

### DMRG_CASPT2_IMAG

> CASPT2 Imaginary shift

> - Type: double
> - Default: 0.0

### DMRG_CASPT2_IPEA

> CASPT2 IPEA shift

> - Type: double
> - Default: 0.0

### DMRG_CASPT2_ORBS

> Whether to calculate the DMRG-CASPT2 energy after the DMRGSCF calculations are done.

> - Type: string
> - Possible Values: PSEUDOCANONICAL, ACTIVE
> - Default: PSEUDOCANONICAL

### DMRG_DIIS

> Whether or not to use DIIS for DMRG.

> - Type: boolean
> - Default: false

### DMRG_DIIS_WRITE

> Whether or not to store the DIIS checkpoint on disk (convenient for restarting).

> - Type: boolean
> - Default: true

### DMRG_EXCITATION

> Which root is targeted: 0 means ground state, 1 first excited state, etc.

> - Type: integer
> - Default: 0

### DMRG_IRREP

> The DMRG wavefunction irrep uses the same conventions as PSI4. How convenient :-). Just to avoid confusion, it’s copied here. It can also be found on http://sebwouters.github.io/CheMPS2/doxygen/classCheMPS2_1_1Irreps.html . Symmetry Conventions Irrep Number & Name Group Number & Name 0 1 2 3 4 5 6 7 0: c1 A 1: ci Ag Au 2: c2 A B 3: cs A’ A’’ 4: d2 A B1 B2 B3 5: c2v A1 A2 B1 B2 6: c2h Ag Bg Au Bu 7: d2h Ag B1g B2g B3g Au B1u B2u B3u

> - Type: integer
> - Default: -1

### DMRG_LOCAL_INIT

> Whether to start the active space localization process from a random unitary or the unit matrix.

> - Type: boolean
> - Default: true

### DMRG_MOLDEN_WRITE

> DMRG-CI or converged DMRG-SCF orbitals in molden format

> - Type: boolean
> - Default: false

### DMRG_MPS_WRITE

> Whether or not to create intermediary MPS checkpoints

> - Type: boolean
> - Default: false

### DMRG_MULTIPLICITY

> The DMRG wavefunction multiplicity in the form (2S+1)

> - Type: integer
> - Default: -1

### DMRG_OPDM_AO_PRINT

> Print out the density matrix in the AO basis

> - Type: boolean
> - Default: false

### DMRG_PRINT_CORR

> Whether or not to print the correlation functions after the DMRG calculation

> - Type: boolean
> - Default: false

### DMRG_SCF_ACTIVE_SPACE

> Which active space to use for DMRG calculations: –> input with SCF rotations (INPUT); –> natural orbitals (NO); –> localized and ordered orbitals (LOC)

> - Type: string
> - Possible Values: INPUT, NO, LOC
> - Default: INPUT

### DMRG_SCF_DIIS_THR

> When the update norm is smaller than this value DIIS starts.

> - Type: double
> - Default: 1e-2

### DMRG_SCF_GRAD_THR

> The density RMS convergence to stop an instruction during successive DMRG instructions

> - Type: double
> - Default: 1.e-6

### DMRG_SCF_MAX_ITER

> Maximum number of DMRG iterations

> - Type: integer
> - Default: 100

### DMRG_SCF_STATE_AVG

> Whether or not to use state-averaging for roots >=2 with DMRG-SCF.

> - Type: boolean
> - Default: true

### DMRG_SWEEP_DVDSON_RTOL

> The residual tolerances for the Davidson diagonalization during DMRG instructions

> - Type: array
> - Default: No Default

### DMRG_SWEEP_ENERGY_CONV

> The energy convergence to stop an instruction during successive DMRG instructions

> - Type: array
> - Default: No Default

### DMRG_SWEEP_MAX_SWEEPS

> The maximum number of sweeps to stop an instruction during successive DMRG instructions

> - Type: array
> - Default: No Default

### DMRG_SWEEP_NOISE_PREFAC

> The noise prefactors for successive DMRG instructions

> - Type: array
> - Default: No Default

### DMRG_SWEEP_STATES

> The number of reduced renormalized basis states to be retained during successive DMRG instructions

> - Type: array
> - Default: No Default

### DMRG_UNITARY_WRITE

> Whether or not to store the unitary on disk (convenient for restarting).

> - Type: boolean
> - Default: true

## How to configure CheMPS2 for building Psi4

Role and Dependencies

- Role — In PSI4, CheMPS2 is a library that provides additional quantum chemical capabilities (DMRG).
- Downstream Dependencies — PSI4 (\(\Leftarrow\) optional) CheMPS2
- Upstream Dependencies — CheMPS2 \(\Leftarrow\) BLAS/LAPACK, HDF5 \(\Leftarrow\) zlib

CMake Variables

- ENABLE_CheMPS2 — CMake variable toggling whether Psi4 builds with CheMPS2
- CMAKE_PREFIX_PATH — CMake list variable to specify where pre-built dependencies can be found. For CheMPS2, set to an installation directory containing `include/chemps2/DMRG.h`
- CheMPS2_DIR — CMake variable to specify where pre-built CheMPS2 can be found. Set to installation directory containing `share/cmake/CheMPS2/CheMPS2Config.cmake`
- CMAKE_DISABLE_FIND_PACKAGE_CheMPS2 — CMake variable to force internal build of CheMPS2 instead of detecting pre-built
- CMAKE_INSIST_FIND_PACKAGE_CheMPS2 — CMake variable to force detecting pre-built CheMPS2 and not falling back on internal build

Examples

1. Build bundled

>     >>> cmake -DENABLE_CheMPS2=ON

2. Build without CheMPS2

>     >>> cmake

3. Build bundled with specific HDF5

>     >>> cmake -DENABLE_CheMPS2=ON -DCMAKE_PREFIX_PATH=/path/to/hdf5

4. Link against pre-built

>     >>> cmake -DENABLE_CheMPS2=ON -DCMAKE_PREFIX_PATH=/path/to/chemps2/root

>     >>> cmake -DENABLE_CheMPS2=ON -DCheMPS2_DIR=/path/to/chemps2/configdir

5. Link against pre-built with specific HDF5

>     >>> cmake -DENABLE_CheMPS2=ON -DCMAKE_PREFIX_PATH="/path/to/chemps2/root;/path/to/hdf5/root"

6. Build bundled despite pre-built being detectable

>     >>> cmake -DENABLE_CheMPS2=ON -DCMAKE_PREFIX_PATH=/path/to/unwanted/chemps2/root/and/wanted/other/dependencies/root -DCMAKE_DISABLE_FIND_PACKAGE_CheMPS2=ON

## How to fix “`plugin needed to handle lto object`” when building CheMPS2

For building with GCC, errors involving unresolved symbols or a message “plugin needed to handle lto object” may indicate a failure of the interprocedural optimization. This can be resolved by passing full locations to gcc toolchain utilities to `setup` or `cmake`: `-DCMAKE_RANLIB=/path/to/gcc-ranlib -DCMAKE_AR=/path/to/gcc-ar` . Details at https://github.com/psi4/psi4/issues/414.