1 Introduction

SiSi4S is a massively-parallel quantum chemistry code that aims to bring coupled-cluster theories to solid state systems. SiSi4S is based partially on the unpublished version of the CC4S code and is used as a testing ground by some developers.

2 Building

SiSi4S depends on several libraries to build. In principle, SiSi4S can build all the dependencies itself, with the exception of the boost libraries, which are available in most HPC systems.

2.1 Intel tools

2.1.1 Intel compiler

In general, the configure script should make a good job of finding the correct intel compiler and the correct MKL libraries.

This section documents past instances of issues and correct solutions to the building.

Make sure to provide correct mpi wrapper scripts to the configure script, for instance supply MPICXX and CXX variables to the ./configure script:

./configure MPICXX=mpiicc CXX=icc

2.1.2 MKL libraries

Typically, the module systems in HPC clusters will export shell variables with names prefixed by MKL, for instance

  • MKLROOT

  • MKL_HOME

  • MKL_PARTS_HOME

It is possible that the configure script can not discover the BLAS libraries, in which case you can test the following

./configure \
    MPICXX=mpiicc \
    CXX=icc \
    --with-blas="-L${MKL_HOME}/lib/intel64/ -mkl -lmkl_intel_lp64"

2.2 Libint

We use the libint library for some algorithms such as molecular Hartree-Fock.

Our build system is able to compile the library on itself. Notable dependencies of libint are libboost and libgmp.

On systems similar to ubuntu these packages should be available under package identifiers similar to

  • libgmp3-dev

  • libboost1.71-all-dev

Please refer to libint’s website for further information.

2.2.1 Using an already compiled version

If you want to reuse an already compiled verison of libint you can give the path to the configure script such as

./configure --with-libint=/absolute/path/to/your/libint

2.2.2 Disabling libint

If you don’t want to use libint since it takes a long time to build and it requires libboost, you can disable the algorithms that use it with the configure flag

./configure --disable-libint

2.3 TODO CTF

3 Input

3.1 Yaml

For now the main input format of SiSi4S is yaml. A typical input for an algorithm is the following

- name: UccsdAmplitudesFromCoulombIntegrals
  in:
    energyConvergence: 1e-8
    maxIterations: 50
    antisymmetrize: 1
    unrestricted: 1
    mixer: "DiisMixer"
    maxResidua: 4
    HoleEigenEnergies: $HoleEigenEnergies
    ParticleEigenEnergies: $ParticleEigenEnergies
    HHHHCoulombIntegrals: $HHHHCoulombIntegrals
    PPPPCoulombIntegrals: $PPPPCoulombIntegrals
    HHHPCoulombIntegrals: $HHHPCoulombIntegrals
    HHPPCoulombIntegrals: $HHPPCoulombIntegrals
    HPHHCoulombIntegrals: $HPHHCoulombIntegrals
    HPHPCoulombIntegrals: $HPHPCoulombIntegrals
    HPPPCoulombIntegrals: $HPPPCoulombIntegrals
    PPHHCoulombIntegrals: $PPHHCoulombIntegrals
    PPHPCoulombIntegrals: $PPHPCoulombIntegrals
    HPPHCoulombIntegrals: $HPPHCoulombIntegrals
    PHPPCoulombIntegrals: $PHPPCoulombIntegrals
    HHPHCoulombIntegrals: $HHPHCoulombIntegrals
    PPPHCoulombIntegrals: $PPPHCoulombIntegrals
    PHPHCoulombIntegrals: $PHPHCoulombIntegrals
    PHHPCoulombIntegrals: $PHHPCoulombIntegrals
  out:
    UccsdDoublesAmplitudes: $UccsdDoublesAmplitudes
    UccsdSinglesAmplitudes: $UccsdSinglesAmplitudes
    UccsdEnergy: $UccsdEnergy

From here, we can see that every algorithm block consists of an `in` section and an `out` section.

- name: UccsdAmplitudesFromCoulombIntegrals
  in:
    ...
  out:
    ...

Some rules extending yaml semantics have to be considered. Strings that start with a $ sign are internal variables such as tensors. The reason of forcing this is to differentiate between yaml strings and symbols representing the name of an internal tensor.

3.1.1 Disabling steps

If you have a big file and you want to disable a step, in addition to in and out, you can supply a disable section with values true or false, i.e.,

- name: UccsdAmplitudesFromCoulombIntegrals
  disable: true
  in:
    ...
  out:
    ...

will simply ignore UccsdAmplitudesFromCoulombIntegrals.

4 TODO Developer’s corner

4.1 TODO Writing documentation

4.2 TODO Adding new algorithms

5 Technical details

5.1 Binary tensor file format

5.1.2 Dimension information

After the tensor header, dimension headers follow for each dimension, starting with the leftmost index.

Offset

Content

Type

Size

Description

+0

length

integer

4

the length the respective dimension

+4

index name

character

1

index name for later reference

+5

flags

integer

1

8-bit flags of this dimension

+6

zero

bytes

2

reserved for future use

+8

5.1.2.1 Dimension flags

Bit

7-1

0

Flag

reserved for future use

SP

Flag

Description

SP

whether this dimension is sparse

Note that sparsity in any dimension does not require the tensor to be stored in the (index,value) format, although that would be the usual case.

5.1.3 Variable chunks

After the fixed chunks for each tensor dimension come the variable chunks providing additional information on the structure of the tensor data, such as on symmetry relations. Each variable chunk provides the same header information including information on its total size, such that implementations can skip ignored or unknown chunks.

Offset

Content

Type

Size

Description

+0

magic

characters

8

identifying the respective chunk

+8

total size

integer

8

including all fields, must be a multiple of 8

+16

5.1.3.1 Symmetry chunk

Symmetry information for each known symmetry operation on the tensor’s index order. Each symmetry operation consists of a permutation \(\sigma(a,b,\ldots)\) of the indices and a subsequent operation \(s(x)\) on the elements, which leave the tensor invariant. For instance, anti-symmetry when interchanging the first two indices in a tensor of fourth order is specified by

\[\begin{split}T_{ijkl} = s\left(T_{\sigma(i,j,k,l)}\right)\,, \text{ with } s(x) = -x \text{ and } \sigma = \left(\begin{array}{rrrr} 1&2&3&4\\ 2&1&3&4 \end{array}\right)\,.\end{split}\]

Offset

Content

Type

Size

Description

+0

“SYMMETRY”

characters

8

magic

+8

size of symmetry information

integer

8

including all fields, must be a multiple of 8

+16

flags

integer

1

8-bit flags of this symmetry

+17

length \(n\) of the operation code

integer

1

characters in the code of the operation \(s(x)\)

+18

symmetry operation code

characters

\(n\)

code of the symmetry operation, e.g. “-x” for \(s(x)=-x\)

  • \(n\) + 18

index map of \(\sigma\)

characters

\(N\)

the symmetry permutation of the index names given in the dimension information, e.g. “bacd” for a transposition of the first two indices for a tensor with the index names “abcd”

  • \(N\) + \(n\) + 18

padding zeros

bytes

\(\textrm{pad}_8(N+n+18)\)

padding to align the chunks in multiples of 4 bytes

  • \(\textrm{align}_8 (N+n+18)\)

where \(\textrm{align}_a(N)=a\lceil N/a \rceil\) and \(\mathrm{pad}_a(N)=\mathrm{align}_a(N)-N\).

5.1.3.1.1 Symmetry flags

Bit

7-1

0

Flag

reserved for future use

PK

Flag

Description

PK

whether the tensor data in this file is packed exploiting this symmetry to reduce the number of entries

5.1.4 Tensor data

The global index \(I\) of each tensor value is given by

I=a+bN_0 + cN_0N_1 + \ldots\,,

where \(N_0,N_1,\ldots\) is the length of each dimension and \(a,b,\ldots\) is the index in each dimension in the order given in the dimension information.

5.1.4.1 Sequential values

If the IX flag is 0 the tensor values are given in a continuous sequence of ascending global index \(I\).

Note

define symmetry packing for a single transposition symmetry.

If the tensor data is packed according to more than one symmetry, only index-value storage is supported in version 1.0.

Offset

Content

Type

Size

Description

+0

“DENSDATA”

characters

8

identifying the respective chunk

+8

total size

integer

8

including all fields, must be a multiple of 8

+16

\(T(0)\)

tensor element

\(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

tensor value at \(I=0\)

+16 + \(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

\(T(1)\)

tensor element

\(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

tensor value at \(I=1\)

\(\vdots\)

\(\vdots\)

tensor element

\(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

\(\vdots\)

5.1.4.2 Index-value storage

If the IX flag is 1 the tensor values are given in pairs of index and value.

Offset

Content

Type

Size

Description

\(+0\)

number of pairs

integer

8

number of non-zero pairs stored

\(+8\)

\(I_0\)

integer

8

global index of first value

\(+16\)

\(T(I_0)\)

tensor element

\(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

value of first pair

\(+ \frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element} +16\)

\(I_1\)

integer

8

global index of second value

\(+ \frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element} +24\)

\(T(I_1)\)

tensor element

\(\frac{\rm bytes}{\rm number}\frac{\rm numbers}{\rm element}\)

value of second pair

\(\ldots\)

5.2 Fourier Transformed Overlap Densities

The FTOD is one of the possible input files, providing information on the orbitals and the eigenenergies of the reference system. The file provides the Fourier transformed overlap densities \(\chi_q^p({\bf G})\) given by

\[\chi_q^p({\bf G}) = \int{\rm d}{\bf x}\, \sqrt{\frac{4\pi}{{\bf G}^2}} {\rm e}^{{\rm i}{\bf G}\cdot{\bf r}}\, \psi_p^\ast({\bf x})\psi_q({\bf x}),\]

such that the Coulomb integrals \(V_{sr}^{pq}\) can be decomposed into

\[V_{sr}^{pq} =\int\frac{{\rm d}{\bf G}}{(2\pi)^3}\,\chi_s^p({\bf G}){\chi_q^r}^\ast({\bf G})\]

The file is a line based text file of the following structure

There is also a binary version FTODDUMP of this file.

5.2.1 Header

  • The first line is reserved for comments. It is ignored by cc4s

  • The second line provides information on the size of the system. The columns are white-space separated and they specify

    1. the number of occupied orbitals \(n_{\rm o}\)

    2. the number of virtual orbitals \(n_{\rm v}\)

    3. the number of plane waves \(n_{\rm G}\)

    4. the number of spins per orbital, 1 or 2

    5. the number of \({\bf k}\) points per orbital.

  • The third is line is again reserved for comments usually explaining the structure of the data to follow.

5.2.2 Overlap densities

The rest of the file contains lines of at least 6 numbers, again in white-space separated columns:

  1. The real part of the overlap density, \({\rm Re}\left(\chi_q^p({\bf G})\right)\), if the plane wave index \(G\), contained in the third column, is non-zero, the eigenenergy \(\varepsilon_p\), otherwise.

  2. The imaginary part of the overlap density, \({\rm Im}\left(\chi_q^p({\bf G})\right)\), if the plane wave index in non-zero. It is ignored otherwise.

  3. The plane wave index \(G\) ranging from 1 to \(n_{\rm G}\)

  4. The orbital index \(p\), ranging from 1 to \(n_{\rm o}+n_{\rm v}\)

  5. The orbital index \(q\), ranging from 1 to \(n_{\rm o}+n_{\rm v}\)

  6. The spin index, which is currently ignored.

There is no order required by cc4s but it could be beneficial to list all overlap densities before all eigenenergies for future or other implementations. Overlap densities that are not listed in the file are assumed to be zero.

5.3 Fourier Transformed Overlap Densities - Binary

The FTODDUMP is one of the possible input files, providing information on the orbitals and the eigenenergies of the reference system. The file provides the Fourier transformed overlap densities \(\Gamma_{q\bf G}^p\) given by

\[\Gamma_{q\bf G}^p = \int{\rm d}{\bf x}\, \sqrt{\frac{4\pi}{{\bf G}^2}} {\rm e}^{{\rm i}{\bf G}\cdot{\bf r}}\, \psi_p^\ast({\bf x})\psi_q({\bf x}),\]

such that the Coulomb integrals \(V_{sr}^{pq}\) can be decomposed into \(V_{sr}^{pq}=\int\frac{{\rm d}{\bf G}}{(2\pi)^3}\,{\Gamma^\ast}_s^{p\bf G}\Gamma_{r\bf G}^q\). The file is binary.

There is also a text version FTOD of this file.

The file consists of chunks, each starting with a unique character sequence for identification, called magic. The header must come as first chunk. The order of the other chunks is arbitrary. The fields within a chunk are given by their respective offset relative to the start of the chunk.

5.3.1 Header

Offset

Content

Type

Size

+0

“cc4sFTOD” (magic)

character

8

+8

number of occupied orbitals \(n_{\rm o}\)

integer

4

+12

number of virtual orbitals \(n_{\rm v}\)

integer

4

+16

number of plane waves \(n_{\rm G}\)

integer

4

+20

number of spins, 1 or 2

integer

4

+24

number of \({\bf k}\)-points

integer

4

+28

reserved for future use

zero

4

+32

5.3.2 Data Chunks

Each chunk starts with an 8 character magic and an 8 byte integer giving the size of the entire chunk, including the magic and the size field. The size is provided so that implementations can skip chunks unknown to them.

5.3.2.1 Real part of \(\chi\)

Offset

Content

Type

Size

+0

“FTODreal” (magic)

character

8

+8

size of this chunk in bytes

integer

8

+16

\({\rm Re}(\chi_1^1(1))\)

double

8

+24

\({\rm Re}(\chi_1^1(2))\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8n_{\rm G}\)

\({\rm Re}(\chi_1^2(1))\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8 n_{\rm G}(n_{\rm o}+n_{\rm v})^2\)

5.3.2.2 Imaginary part of \(\chi\)

Analogous to the real part chunk but with the magic “FTODimag”.

5.3.2.3 Real part of \(\chi_i^a\)

Offset

Content

Type

Size

+0

“FTIAreal” (magic)

character

8

+8

size of this chunk in bytes

integer

8

+16

\({\rm Re}(\chi_1^1(1))\)

double

8

+24

\({\rm Re}(\chi_1^1(2))\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8n_{\rm G}\)

\({\rm Re}(\chi_1^2(1))\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8n_{\rm G}n_{\rm v}\)

\({\rm Re}(\chi_2^1(1))\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8n_{\rm G}(n_{\rm o} n_{\rm v})\)

5.3.2.4 Imaginary part of \(\chi_i^a\)

Analogous to the real part chunk but with the magic “FTIAimag”.

5.3.2.5 Eigenenergies \(\varepsilon_p\)

Offset

Content

Type

Size

+0

“FTODepsi” (magic)

character

8

+8

size of this chunk in bytes

integer

8

+16

\(\varepsilon_1\)

double

8

+24

\(\varepsilon_2\)

double

8

\(\vdots\)

\(\vdots\)

double

8

\(+16+8(n_{\rm o}+n_{\rm v})\)

6 Algorithms

6.1 MoReader :interface:

This module contains convenience routines in order to read molecular orbitals from the following codes:

  • NWCHEM

  • PSI4

  • TURBOMOLE