How to run Cc4s calculations?

Step 1: Coupled cluster singles and doubles theory calculations
Step 2: Perturbative triples calculations
Step 3: Basis-set incompleteness error correction
Step 4: Finite-size correction
Final energy

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


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.

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.