# Getting Started¶

## Structure of the Input¶

The input is broken up into three main sections: first, the header specifies how many electrons should be included in the active space and which orbitals they occupy in the Hatree Fock (HF) determinant; second, the schedule and settings for the variational part of the calculation; finally, the settings for the perturbative calculation.

### Sample Input¶

#reference determinant
nocc 8
0 1  4 5  8 9  14 15
0 1  4 5  8 9  14 17
end
nroots 2  #eg nroots don't have to be the same as number of reference determinants

#var keywords
schedule
0 9e-4
3 5e-4
end
maxiter 12

#PT keywords
deterministic
epsilon2 1.e-8
sampleN 200


Note

Although we have presented the input separated into three distinct sections, you do not have to write the keywords in any particular order, but is is highly recommended for clarity. For more details about the keywords used or other keywords please see the Keywords page.

### Variational Section¶

The schedule specifies which $$\epsilon_1$$ values will be used at each iteration. In the example shown directly below, an $$\epsilon_1$$ value of $$9*10^{-4}$$ will be used from the $$0^{th}$$ up to the $$3^{rd}$$ iteration, i.e. in iterations 0, 1, and 2.

### Perturbative Section¶

Dice can calculate the second order perturbative contribution to the energy in three ways all of which involve the use of the $$\epsilon_2$$ keyword. This parameter controls how much of the determinant space will be included in the perturbative calculation

1. Deterministic: All determinants connected to the variational space with $$|H_{ai}c_i| > \epsilon_2$$ are included in the following summation where $$\Delta E^{(2)}$$ is the second order perturbative correction to the energy, $$H_{ai}$$ is the Hamiltonian matrix element connecting determinants i and a, $$c_i$$ is the coefficient of the i $$^{th}$$ determinant, and $$E^{(0)}$$ is the eigenvalue of the zeroth-order Hamiltonian.

$\Delta E^{(2)} \approx \sum_a \frac{\big(\sum_i^{\epsilon_2} H_{ai} c_i \big)^2}{E^{(0)}-H_{aa}}$
1. Stochastic: A small number of determinants in the variational space (determined by the SampleN parameter, see Keywords for more details) are stochastically selected and used to evaluate the equation above where $$N_d$$ is the total number of determinants sampled, $$N_d^{diff}$$ is the number of unique determinants sampled, $$\omega_i$$ is the number of times determinant i was selected in this sample, and $$p_i = \frac{|c_i|}{\sum_i |c_i|}$$ or the probability of selecting determinant i. Stochastic evaluation of the energy correction enables the use of much smaller $$\epsilon_2$$ values for large systems, while retaining the sub mHa accuracy of the deterministic variant.

$\Delta E^{(2)} \approx \frac{1}{N_d(N_d-1)} \Bigg \langle \sum_a \frac{1}{E^{(0)}-H_{aa}} \Bigg[ \bigg(\sum_i^{N_d^{diff}} \frac{\omega_i H_{ai} c_i}{p_i}\bigg)^2 + \sum_i^{N_d^{diff}} \bigg(\frac{\omega_i (N_d-1)}{p_i} - \frac{\omega_i^2}{p_i^2}\bigg) c_i^2 H_{ai}^2 \Bigg] \Bigg \rangle$
1. Semistochastic: In this variant of the perturbative calculation, Dice calculates the correction using both equations above. A new keyword called $$\epsilon_{2Large}$$ is needed to distinguish which determinants will be treated stochastically and which will not. Dice calculates the energy correction using the second equation for both $$\epsilon_2$$ and $$\epsilon_{2Large}$$ and using the first equation with $$\epsilon_{2Large}$$. We then subtract the less strict stochastic correction ($$E_2^S[\epsilon_2^d]$$) from the strict stochastic correction ($$\Delta E_2^S[\epsilon_2]$$) to reduce the stochastic noise before adding the deterministic contribution ($$\Delta E_2^D[\epsilon_2^d]$$).

$\Delta E_2[\epsilon_2] = \big( \Delta E_2^S[\epsilon_2] − \Delta E_2^S[\epsilon_2^d] \big) + \Delta E_2^D[\epsilon_2^d]$

## Using Dice as a stand-alone program¶

You can choose to use Dice as a wavefunction solver without interfacing it with other programs. This will require a two-body integral file in the FCIDUMP format, which can be generated using whatever electronic structure package you prefer. If you’d like to use it as an active space solver in a CASSCF calculation see the Interfacing with PySCF page.

Once you have generated your FCIDUMP file, you must create an input file that contains all of the parameters that Dice needs to run a calculation. An example input.dat file is shown below. For more input files see the test directory inside your main Dice directory.

nocc 12
0 2 4 6 8 10 1 3 5 7 9 11
end
nroots 1

schedule
0     1e-10
end
davidsonTol 1e-10
dE 1e-14
DoRDM

epsilon2 1e-8
sampleN 200
noio
prefix /rc_scratch/jasm3285/o2
maxiter 6


Once you have your input.dat and FCIDUMP file you can open a terminal and navigate to the directory with both files and use the following command:

Note

You can run Dice in parallel using OMP, MPI, or a hybrid of both, but we recommend that you use MPI. If you would like to run a hybrid scheme, please contact us to help you set it up.

mpirun -np 2 /path_to/Dice/Dice input.dat > output.dat


This will execute your input.dat file and write all output to the output.dat file in your current working directory. An example of the output is shown below:

**************************************************************
Dice  Copyright (C) 2017  Sandeep Sharma
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

Author:       Sandeep Sharma
Contributors: James E Smith, Adam A Holmes, Bastien Mussard
For detailed documentation on Dice please visit
https://sanshar.github.io/Dice/
**************************************************************

**************************************************************
Input file  :
**************************************************************
nocc 12
0 2 4 6 8 10 1 3 5 7 9 11
nroots 1

schedule
0     1e-10
end
davidsonTol 1e-10
dE 1e-14
DoRDM

epsilon2 1e-8
sampleN 200
noio
prefix /rc_scratch/jasm3285/o2
maxiter 6

**************************************************************
VARIATIONAL STEP
**************************************************************
Iter Root       Eps1   #Var. Det.               Energy   #Davidson     Time(s)
0    0    1.00e-10          33      -149.5916823420         10        0.00
1    0    1.00e-10         108      -149.6068206155         12        0.01
2    0    1.00e-10         120      -149.6069803279         10        0.01
3    0    1.00e-10         120      -149.6069803279          1        0.01
4    0    1.00e-10         120      -149.6069803279          1        0.01

Performing final tight davidson with tol: 1e-10

Exiting variational iterations
Calculating RDM
-83.3274573156373  36.0439587498228
E from 2RDM: -149.606980328729
VARIATIONAL CALCULATION RESULT
------------------------------
Root             Energy     Time(s)
0     -149.6069803287        0.72

Printing most important determinants
Det     weight  Determinant string
State :0
0     6.78189482e-01  2 2 2 2 2   2 0 0
1     6.77706652e-01  2 2 2 2 2   0 2 0
2     1.53392072e-01  2 2 2 2 0   2 2 0
3     1.53270657e-01  2 2 0 2 2   2 2 0
4     5.24640738e-02  2 2 2 b a   2 b a
5     5.24640738e-02  2 2 2 a b   2 a b
We cannot perform PT RDM with stochastic PT. Disabling RDM.

**************************************************************
PERTURBATION THEORY STEP
**************************************************************
Peforming semistochastiPT for state: 0

Iter      EPTcurrent  State         EPTavg      Error     Time(s)
1   -149.60698033      0  -149.60698033         --        0.75
2   -149.60698033      0  -149.60698033         --        0.75
3   -149.60698033      0  -149.60698033         --        0.75
4   -149.60698033      0  -149.60698033         --        0.75
5   -149.60698033      0  -149.60698033   0.00e+00        0.75
Semistochastic PT calculation converged
epsilon2: 1e-08
PTEnergy: -149.606980328729 +/- 0.00e+00
Time(s):  0.754081964492798