# How to run Cc4s calculations?

In this tutorial we explain all steps necessary to perform a Cc4s calculation on the level of CCSD(T) theory for a simple test system. The test system corresponds to a periodic rhomobohedral boron nitride crystal. All required Cc4s input files have been created using the VASP interface.

Cc4s calculations are controlled by a YAML input file, which is called cc4s.in in the present tutorial. This input file consists of a list of calls to algorithms with input arguments and output objects. Here, we will walk you through all employed algorithms used to compute the CCSD(T) correlation energy. However, if you want to skip the detailed explanations below and proceed directly to performing CCSD(T) calculations, you might as well download the complete cc4s.in file here.

The following files are needed to reproduce all calculations of this tutorial.

• A working binary of Cc4s obtained by compiling the code
• A set of input files generated by the VASP interface that are part of the tests included in the Cc4s package
• Eigenenergies ($$\epsilon_{p}$$) : EigenEnergies.yaml, EigenEnergies.elements
• CoulombVertex ($$\Gamma^{pG}_{q}$$) : CoulombVertex.yaml, CoulombVertex.elements
• GridVectors ($$\vec G$$) : GridVectors.yaml, GridVectors.elements
• CoulombPotential ($$V(\vec G)$$) : CoulombPotential.yaml, CoulombPotential.elements
• DeltaIntegrals ($$\delta^{ab}_{ij}$$) : DeltaPPHH.yaml, DeltaPPHH.elements
• DeltaIntegrals ($$\delta_{ij}$$) : DeltaHH.yaml, DeltaHH.elements
• CoulombVertexSingularVetors ($$U_{G}^{F}$$) : CoulombVertexSingularVectors.yaml, CoulombVertexSingularVectors.elements
• Mp2PairEnergies ($$\epsilon_{ij}$$) : Mp2PairEnergies.yaml, Mp2PairEnergies.elements
• State.yaml, Momentum.yaml and AuxiliaryField.yaml

For the following example we assume that all input files listed above and the cc4s.in file are located in the same directory. The cc4s.in YAML input file is described in the following section in detail.

## Step 1: Coupled cluster singles and doubles theory calculations

We start this tutorial by taking the first steps in Cc4s needed to compute the CCSD correlation energy. For this purpose essential data files have to be read from disk using the Read algorithm. This aglorithm can be executed employing the following cc4s.in YAML input which controls Cc4s

- name: Read
in:
fileName: "CoulombVertex.yaml"
out:
destination: CoulombVertex


The above call to the Read algorithm reads the CoulombVertex.yaml file that contains all meta-information associated with the CoulombVertex tensor in a human-readable format. Cc4s will read all numerical data belonging to the corresponding CoulombVertex tensor from the CoulombVertex.elements binary file stored on disk. The output of Read algorithm is the CoulombVertex tensor object, which can be used as input for all subsequent Cc4s algorithms.

In addition, we use Cc4s to read the EigenEnergies.yaml and EigenEnergies.elements files by including the following Read call in cc4s.in

- name: Read
in:
fileName: "EigenEnergies.yaml"
out:
destination: EigenEnergies


In the following step we include two further algorithm calls that are necessary to process the CoulombVertex and EigenEnergies tensors in Cc4s and prepare them for coupled-cluster calculations. To this end the cc4s.in file calls the DefineHolesAndParticles and SliceOperator algorithms as described below

- name: DefineHolesAndParticles
in:
eigenEnergies: EigenEnergies
out:
slicedEigenEnergies: EigenEnergies

- name: SliceOperator
in:
slicedEigenEnergies: EigenEnergies
operator: CoulombVertex
out:
slicedOperator: CoulombVertex


Note that the above algorithms overwrite the original tensors stored in CoulombVertex and EigenEnergies, turning them into objects corresponding to sets of tensors with partitioned orbital indices, respectively. In particular, all state indices have been partitioned to refer to particle or hole states; for example, $$\epsilon_q \rightarrow \{\epsilon_a, \epsilon_i\}$$. Using these outputs, we call the VertexCoulombIntegrals algorithm by including the following paragraph in the cc4s.in file

- name: VertexCoulombIntegrals
in:
slicedCoulombVertex: CoulombVertex
out:
coulombIntegrals: CoulombIntegrals


The VertexCoulombIntegrals algorithm generates the CoulombIntegrals as output, which serve as input to the CoupledCluster algorithm and is called using the following code block in cc4s.in

- name: CoupledCluster
in:
method: Ccsd
integralsSliceSize: 100
slicedEigenEnergies: EigenEnergies
coulombIntegrals: CoulombIntegrals
slicedCoulombVertex: CoulombVertex
maxIterations: 30
energyConvergence: 1.0E-5
amplitudesConvergence: 1.0E-5
mixer:
type: DiisMixer
maxResidua: 5
out:
amplitudes: Amplitudes


If all code blocks given above are included in the cc4s.in file and all other prerequisites are fulfilled, Cc4s can be called by typing the following command in the terminal:

mpirun -np 48 Cc4s -i cc4s.in


In the present example we run the calculations in parallel using 48 compute cores.

If all algorithms work successfully, the following output stream will appear on the terminal

                __ __
__________/ // / _____
/ ___/ ___/ // /_/ ___/
/ /__/ /__/__  __(__  )
\___/\___/  /_/ /____/
Coupled Cluster for Solids

version: heads/develop-0-g5339629, date: Tue Feb 1 16:44:23 2022 +0100
build date: Feb  1 2022 17:42:37
compiler: icc (ICC) 19.1.0.166 20191121
total processes: 48
calculation started on: Mon Feb  7 09:46:22 2022

realtime 0.117790191 s
--
realtime 0.003308821 s
--
step: 3, DefineHolesAndParticles
number of holes     No: 16
number of particles Nv: 80
number of states    Np: 96
realtime 0.001116923 s
--
step: 4, SliceOperator
Slicing CoulombVertex.elements into holes and particles.
realtime 0.002643576 s
--
step: 5, VertexCoulombIntegrals
Using real Coulomb integrals
number of field variables NF: 356
realtime 0.001467920 s
--
step: 6, CoupledCluster
Using method Ccsd. integralsSliceSize: 100
Using mixer DiisMixer. maxResidua: 5
Maximum number of iterations: 30
Unless reaching energy convergence dE: 1e-05
and amplitudes convergence dR: 1e-05
Iter         Energy         dE           dR         time   GF/s/core
1  -2.43605043e+01  -2.4361e+01   4.3924e-01      0.1    4.2
2  -2.47577534e+01  -3.9725e-01   7.4733e-02      0.8    4.9
3  -2.53776918e+01  -6.1994e-01   1.8674e-02      0.7    5.5
4  -2.54455925e+01  -6.7901e-02   6.4132e-03      0.7    5.5
5  -2.54445080e+01   1.0845e-03   2.2120e-03      0.7    5.4
6  -2.54458312e+01  -1.3232e-03   1.0304e-03      0.7    5.4
7  -2.54448941e+01   9.3705e-04   5.0727e-04      0.7    5.4
8  -2.54452894e+01  -3.9521e-04   1.9694e-04      0.7    5.4
9  -2.54454262e+01  -1.3682e-04   7.7180e-05      0.7    5.4
10  -2.54455328e+01  -1.0663e-04   3.0247e-05      0.7    5.5
11  -2.54455929e+01  -6.0110e-05   1.1758e-05      0.7    5.4
12  -2.54456151e+01  -2.2218e-05   5.0053e-06      0.7    5.5
13  -2.54456249e+01  -9.7454e-06   2.2689e-06      0.7    5.4

Ccsd correlation energy:          -25.4456248862
2nd-order correlation energy:     -24.3605043096
realtime 8.742863556 s
--
total realtime: 8.873855540 s
total operations: 2267.4 GFLOPS, speed: 5.3 GFLOPS/s/core


The CCSD correlation energy can either be extracted directly from the standard output stream or the cc4s.out.yaml YAML file, which contains additional information as well as the correlation energy. The corresponding block of cc4s.out.yaml reads

    name: CoupledCluster
out:
convergenceReached: 1
energy:
correlation: -25.445624886202758
direct: -38.822491455744313
exchange: 13.376866569541555
secondOrder: -24.360504309639897
unit: 0.036749322175638754
realtime: 8.742863556


Note that the energies are given in units of eV for the present system. The energy units are defined by input files and always correspond to eV in the case of input files generated by VASP.

## Step 2: Perturbative triples calculations

We now proceed with the CCSD(T) energy calculation and seek to compute the (T) contribution, which has to be added to the CCSD correlation energy contribution estimated in the previous section.

The PerturbativeTriples algorithm computes the (T) correlation energy contribution and is called from the cc4s.in file in the following manner

- name: PerturbativeTriples
in:
slicedEigenEnergies: EigenEnergies
amplitudes: Amplitudes
coulombIntegrals: CoulombIntegrals
out:
{}


Note that the PerturbativeTriples algorithm depends on Amplitudes as input argument which has been computed above using the CoupledCluster algorithm. If we append the above code block to the cc4s.in file described in the previous section and run Cc4s, the following additional standard output stream should appear.

step: 7, PerturbativeTriples
Progress(%)  time(s)   GFLOP/s
1            0         4.269
10           0         5.763
20           0         5.887
30           0         6.017
40           0         6.018
50           0         6.034
60           0         6.035
70           0         6.029
80           0         6.004
90           0         6.011
100          0         5.986
(T) correlation energy:      -0.822530510989498
realtime 2.547204125 s
--


The (T) correlation energy contribution can either be extracted directly from the standard output stream or the cc4s.out.yaml YAML file, which contains additional information as well as the correlation energy contribution. The corresponding block of cc4s.out.yaml reads

    name: PerturbativeTriples
out:
energy:
correlation: -0.82253051098949848
unit: 0.036749322175638782
realtime: 2.547204125


## Step 3: Basis-set incompleteness error correction

We note that in the present case, the CCSD correlation energy is computed using a set of truncated approximate natural orbitals. Increasing this basis set size yields correlation energies that converge only slowly to the complete basis set limit. Cc4s includes an algorithm that can compute a basis-set incompleteness error (BSIE) correction, yielding significantly more rapidly convergent correlation energies with respect to the number virtual orbitals.

The BasisSetCorrection computes a BSIE correction for CCSD theory and requires a set of additional input files that are also provided using the VASP interface. Reading the corresponding input files and calling the BasisSetCorrection algorithm is achieved using the following code block in cc4s.in

- name: Read
in:
fileName: "DeltaIntegralsHH.yaml"
out:
destination: Nij

in:
fileName: "DeltaIntegralsPPHH.yaml"
out:
destination: DeltaIntegrals

in:
fileName: "Mp2PairEnergies.yaml"
out:
destination: Mp2PairEnergies

- name: BasisSetCorrection
in:
slicedEigenEnergies: EigenEnergies
amplitudes: Amplitudes
coulombIntegrals: CoulombIntegrals
mp2PairEnergies: Mp2PairEnergies
deltaIntegralsHH: Nij
deltaIntegralsPPHH: DeltaIntegrals
out:
{}


Appending the code block above to the cc4s.in file described in all previous sections and running Cc4s, yields the following additional standard output stream.

step: 8, Read
realtime 0.008716583 s
--
realtime 0.034012456 s
--
realtime 0.002247945 s
--
step: 11, BasisSetCorrection
Ccsd-Bsie energy correction:      -5.2998024502
realtime 0.079391342 s
--


The BSIE correction can either be extracted directly from the standard output stream or the cc4s.out.yaml file, which contains additional information as well as the correction. The corresponding block of cc4s.out.yaml reads

    name: BasisSetCorrection
out:
energy:
correction: -5.2998024502064709
pplCorrection: 1.2013851788124801
secondOrderCorrection: -6.5011876290189505
uncorrectedCorrelation: -25.445624886202786
unit: 0.036749322175638782
realtime: 0.079391342


## Step 4: Finite-size correction

In the present example the CCSD correlation energy is computed for a finite periodic simulation cell. Increasing the size of the employed periodic simulation cell yields correlation energies per atom that converge only slowly to the thermodynamic limit. Cc4s includes an algorithm that can compute a finite-size error correction, yielding significantly more rapidly convergent correlation energies per atom with respect to the simulation cell size.

The FiniteSizeCorrection algorithm computes a finite-size correction for CCSD theory and requires a set of additional input files that are also provided by the VASP interface. Reading the corresponding input files and calling the FiniteSizeCorrection algorithm is achieved using the following code block in cc4s.in

- name: Read
in:
fileName: "CoulombVertexSingularVectors.yaml"
out:
destination: CoulombVertexSingularVectors

in:
fileName: "GridVectors.yaml"
out:
destination: GridVectors

in:
fileName: "CoulombPotential.yaml"
out:
destination: CoulombPotential

- name: FiniteSizeCorrection
in:
slicedCoulombVertex: CoulombVertex
amplitudes: Amplitudes
coulombVertexSingularVectors: CoulombVertexSingularVectors
coulombPotential: CoulombPotential
gridVectors: GridVectors
out:
corrected: Corrected
uncorrected: Uncorrected
transitionStructureFactor: SF


Appending the code block above to the cc4s.in file described in all previous sections and running Cc4s, yields the following additional standard output stream.

step: 12, Read
realtime 0.015900868 s
--
realtime 0.003182427 s
--
realtime 0.002309552 s
--
step: 15, FiniteSizeCorrection
Finite-size energy correction:    -1.1152868081
realtime 0.363875546 s
--


The finite-size correction can either be extracted directly from the standard output stream or the cc4s.out.yaml file, which contains additional information as well as the correction. The corresponding block of cc4s.out.yaml reads

    name: FiniteSizeCorrection
out:
energy:
corrected: -26.560663044130632
correction: -1.1152868080903175
uncorrected: -25.445376236040314
unit: 0.03674932217686841
transitionStructureFactor: 0x2cb2f18
realtime: 0.363875546


## Final energy

We now discuss how to combine all energy contributions from above to obtain the final estimate of the ground state energy in the thermodynamic and complete basis-set limit. The table below summarizes all computed ground state energy contributions for the present example.

Table 1: Ground state energy summary for present example. All energies in eV.
Contribution Value
Hartree–Fock -116.426066
CCSD correlation -25.445625
(T) correlation -0.822531
CCSD BSIE energy correction -5.299802
CCSD finite-size energy correction -1.115287
CCSD(T) energy + corrections -149.109311

Please note that the Hartree–Fock energy contribution was obtained using a preceeding VASP calculation. We recommend to converge the Hartree–Fock energy contribution to the thermodynamic limit separately using denser $$k$$ -meshes. The final CCSD(T) energy + corrections value can be used to study all accessible physical properties of interest.

Created: 2022-09-19 Mon 15:00