# 5. `CheMPS2::Hamiltonian`

There are several ways to feed matrix elements to CheMPS2. They are explained below in detail. Because CheMPS2 is a spin-adapted code, it can only handle spatial orbitals. It is hence not possible to use different orbitals for \(\uparrow\) and \(\downarrow\) electrons.

1. The `CheMPS2::Hamiltonian` object is able to read in FCIDUMP files. The `fcidump` plugin to psi4 allows to generate such FCIDUMP files.

2. The `savehdf` plugin to psi4 fills a `CheMPS2::Hamiltonian` object, and saves the matrix elements to disk in HDF5 format, taking into account their eightfold permutation symmetry.

3. Users can also generate matrix elements themselves, and feed them to the `CheMPS2::Hamiltonian` object.

## 5.1. psi4 `fcidump` plugin

The `CheMPS2::Hamiltonian` object is able to read in FCIDUMP files:

    CheMPS2::Hamiltonian::Hamiltonian( const string filename, const int psi4groupnumber )

The variable `filename` should contain the path to the FCIDUMP file, and the variable `psi4groupnumber` should be the group number of the abelian point group with real-valued character table as defined in psi4. The conversion table is provided here:

> Group name | c1 | ci | c2 | cs | d2 | c2v | c2h | d2h
> Group number | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7

FCIDUMP files can for example be generated by molpro, or by a plugin to psi4. The plugin has been tested on psi4-0.5 (released February 17, 2016).

To make use of this feature, build psi4 with the plugin option `ENABLE_PLUGINS=ON`, and then run:

    $ cd /mypsi4plugins
    $ psi4 --new-plugin fcidump
    $ cd fcidump

Now, replace the file `fcidump.cc` with `/sourcefolder/chemps2/integrals/psi4plugins/fcidump.cc`. To compile the plugin, run:

    $ make

An example input file to generate a FCIDUMP file:

    molecule N2 {
       N       0.0000   0.0000   0.0000
       N       0.0000   0.0000   2.1180
    units au
    }

    sys.path.insert(0, './..')
    import fcidump

    set basis cc-pVDZ
    set reference rhf
    set scf_type PK
    set e_convergence 1e-12
    set d_convergence 1e-12
    set ints_tolerance 0.0

    set fcidump dumpfilename N2.ccpvdz.fcidump

    energy('fcidump')

This file (`N2.fcidump.in`) should be placed in the folder `/mypsi4plugins/fcidump/`. The FCIDUMP file can then be generated with:

    $ cd /mypsi4plugins/fcidump
    $ psi4 N2.fcidump.in N2.fcidump.out
    $ less N2.CCPVDZ.FCIDUMP

Examples of output generated with this plugin can be found in `/sourcefolder/chemps2/tests/matrixelements/`.

## 5.2. psi4 `savehdf` plugin

The `CheMPS2::Hamiltonian` object is able to read in HDF5 files generated by a plugin to psi4. The plugin has been tested on psi4-0.5 (released February 17, 2016). It stores all unique matrix elements (remember that there is eightfold permutation symmetry) in binary form with HDF5.

To make use of this feature, build psi4 with the plugin option `ENABLE_PLUGINS=ON`, and then run:

    $ cd /mypsi4plugins
    $ psi4 --new-plugin savehdf
    $ cd savehdf

Now, replace the file `savehdf.cc` with `/sourcefolder/chemps2/integrals/psi4plugins/savehdf.cc`. To compile the plugin, the Makefile should be adjusted. Change the line

    $(CXX) $(LDFLAGS) -o $@ $^ $(CXXDEFS)

to

    $(CXX) $(LDFLAGS) -o $@ $^ $(CXXDEFS) -lchemps2

Remember to add the library and include paths to the Makefile as well, if `libchemps2` is not installed in a standard location. For debian/sid, the HDF5 headers are located in the folder `/usr/include/hdf5/serial/`. It might be necessary to add it to the `INCLUDES` variable in the Makefile. To compile the plugin, run:

    $ make

An example input file to use the `savehdf` plugin:

    molecule N2 {
       N       0.0000   0.0000   0.0000
       N       0.0000   0.0000   2.1180
    units au
    }

    sys.path.insert(0, './..')
    import savehdf

    set basis cc-pVDZ
    set reference rhf
    set scf_type PK
    set e_convergence 1e-12
    set d_convergence 1e-12
    set ints_tolerance 0.0

    energy('savehdf')

This file (`N2.savehdf.in`) should be placed in the folder `/mypsi4plugins/savehdf/`. The matrix elements can then be saved to disk in binary form with HDF5 by running:

    $ cd /mypsi4plugins/savehdf
    $ psi4 N2.savehdf.in N2.savehdf.out
    $ ls *.h5

The plugin generates three files:

    /mypsi4plugins/CheMPS2_Ham_parent.h5
    /mypsi4plugins/CheMPS2_Ham_Tmat.h5
    /mypsi4plugins/CheMPS2_Ham_Vmat.h5

which allow to create an instance of the `CheMPS2::Hamiltonian` object:

    CheMPS2::Hamiltonian::Hamiltonian( const bool fileh5, const string main_file, const string file_tmat, const string file_vmat )

The variable `fileh5` should be `true`, and the three strings should contain the paths to the three files listed above, in the same respective order.

## 5.3. Custom matrix elements

It is also possible to create a `CheMPS2::Hamiltonian` object with your own matrix elements. Please consult the `CheMPS2::Hamiltonian` class in the doxygen html output, and more specifically the functions:

    CheMPS2::Hamiltonian::Hamiltonian( const int Norbitals, const int nGroup, const int * OrbIrreps )
    void CheMPS2::Hamiltonian::setEconst( const double val )
    void CheMPS2::Hamiltonian::setTmat( const int index1, const int index2, const double val )
    void CheMPS2::Hamiltonian::setVmat( const int index1, const int index2, const int index3, const int index4, const double val )

The variable `Norbitals` should be the total number of orbitals in the active space. The variable `nGroup` should be the group number of the abelian point group with real-valued character table as defined in psi4. The array `OrbIrreps` of length `Norbitals` contains for each orbital its irreducible representation number as defined in psi4. The conversion table is provided here:

> Group / Irreps | 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

Two important remarks:

1. On creation of the `CheMPS2::Hamiltonian` object, every matrix element is set to zero.

2. Physics notation is used for the two-electron integrals in CheMPS2: \(V_{ij;kl} = ( ik \mid jl )\) or `CheMPS2::Hamiltonian::setVmat( i, j, k, l, (ik|jl) )`.