# How to run Cc4s calculations?

## Table of Contents

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`

- Eigenenergies (\(\epsilon_{p}\)) :

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 execution plan read, steps: 6 step: 1, Read Reading from binary file CoulombVertex.elements realtime 0.117790191 s -- step: 2, Read Reading from text file EigenEnergies.elements 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: amplitudes: 0x1ad98b8 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 - name: Read in: fileName: "DeltaIntegralsPPHH.yaml" out: destination: DeltaIntegrals - name: Read 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 Reading from binary file DeltaIntegralsHH.elements realtime 0.008716583 s -- step: 9, Read Reading from binary file DeltaIntegralsPPHH.elements realtime 0.034012456 s -- step: 10, Read Reading from text file Mp2PairEnergies.elements 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 - name: Read in: fileName: "GridVectors.yaml" out: destination: GridVectors - name: Read 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 Reading from binary file CoulombVertexSingularVectors.elements realtime 0.015900868 s -- step: 13, Read Reading from text file GridVectors.elements realtime 0.003182427 s -- step: 14, Read Reading from text file CoulombPotential.elements 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.

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.