1
\section{\PSIthree\ Input Files} \label{input}
3
\subsection{Syntax} \label{syntax}
4
\PSIthree\ input files are case-insensitive and free-format, with
5
a grammar designed for maximum flexibility and relative simplicity.
6
Input values are assigned using the structure:
10
where {\tt keyword} is the parameter chosen (e.g., {\tt convergence})
11
and {\tt value} has one of the following data types:
13
\item string: A character sequence surrounded by double-quotes.
14
Example: {\tt basis = "cc-pVDZ"}
15
\item integer: Any positive or negative number (or zero) with no
16
decimal point. Example: {\tt maxiter = 100}
17
\item real: Any floating-point number. Example: {\tt omega = 0.077357}
18
\item boolean: {\tt true}, {\tt false}, {\tt yes}, {\tt no}, {\tt 1},
20
\item array: a parenthetical list of values of the above data types.
21
Example: {\tt docc = (3 0 1 1)}.
23
Note that the input parsing system is general enough to allow
24
multidimensional arrays, with elements of more than one data type. A
25
good example is the z-matrix keyword:
33
For z-matrices, z-matrix variables, and Cartesian coordinates,
34
it is also possible to discard the inner parentheses.
35
The following is equivalent in this case:
44
Keywords must grouped together in blocks, based on the module or
45
modules that require them. The default block is labelled {\tt psi:},
46
and most users will require only a {\tt psi:} block when using
47
\PSIthree. For example, the following is a simple input file for a
48
single-point CCSD energy calculation on H$_2$O:
51
label = "6-31G**/CCSD H2O"
67
In this example, the {\tt psi:} identifier collects all the keywords
68
(of varying types) together. Every \PSIthree\ module will have access
69
to every keyword in the {\tt psi:} block by default. One may use
70
other identifiers (e.g., {\tt ccenergy:}) to separate certain keywords
71
to be used only by selected modules. For example, consider the
72
keyword {\tt convergence}, which is used by several \PSIthree\ modules
73
to determine the convergence criteria for constructing various types
74
of wave functions. If one wanted to use a high convergence cutoff for the
75
\PSIthree\ SCF module but a lower cutoff for the coupled cluster
76
module, one could modify the above input:
84
Note that, since we have only one keyword associated with the {\tt
85
scf:} block, we do not need to enclose it parentheses.
87
Some additional aspects of the \PSIthree\ grammar to keep in mind:
89
\item The ``\%'' character denotes a comment line, i.e. any
90
information following the ``\%'' up to the next linebreak is ignored
92
\item Anything in between double quotes (i.e. strings) is case-sensitive.
93
\item Multiple spaces are treated as a single space.
96
\subsection{Specifying the Type of Computation}
97
The most important keywords in a \PSIthree\ input file are those which
98
tell the program what type of computation are to be performed.
99
They \keyword{jobtype} keyword tells the \PSIdriver\ program whether
100
this is a single-point computation, a geometry optimization, a
101
vibrational frequency calculation, etc. The \keyword{reference}
102
keyword specifies whether an RHF, ROHF, UHF, etc., reference is
103
to be used for the SCF wavefunction. The \keyword{wfn} specifies
104
what theoretical method is to be used, either SCF, determinant-based
105
CI, coupled-cluster, etc. Also of critical importance are the charge
106
and multiplicity of the molecule, the molecular geometry, and the
107
basis set to be used. The latter two topics are discussed below
108
in sections \ref{geom-spec} and \ref{basis-spec}.
109
General keywords determining the general type of computation to be performed
113
\item[LABEL = string]\mbox{}\\
114
This is a character string to be included in the output to help keep track
115
of what computation has been run. It is not otherwise used by the program.
117
\item[JOBTYPE = string]\mbox{}\\
118
This tells the program whether to run a single-point energy calculation
119
(SP), a geometry optimization (OPT), a series of calculations at
120
different displaced geometries (DISP), a frequency calculation (FREQ),
121
frequencies only for symmetric vibrational modes (SYMM\_FREQ),
122
a Diagonal Born-Oppenheimer Correction (DBOC) energy computation,
123
or certain response properties (RESPONSE).
125
\item[WFN = string]\mbox{}\\
126
This specifies the wavefunction type. Possible values are:\\
127
SCF, MP2, MP2R12, CIS, DETCI, DETCAS, CCSD, CCSD\_T, BCCD, BCCD\_T,\\
129
\item[REFERENCE = string]\mbox{}\\
130
This specifies the type of SCF calculation one wants to do. It
131
can be one of RHF (for a closed shell singlet), ROHF (for
132
a restricted open shell calculation), UHF (for an unrestricted
133
open shell calculation), or TWOCON (for a two configuration
134
singlet). The default is RHF.
135
\item[MULTP = integer]\mbox{}\\
136
Specifies the multiplicity of the molecule, i.e., 2S+1. Default
138
\item[CHARGE = integer]\mbox{}\\
139
Specifies the charge of the molecule. Default is 0.
140
\item[DERTYPE = string]\mbox{}\\
141
This specifies the order of the derivative that is to be obtained.
142
The default is NONE (energy only).
143
\item[DOCC = integer vector]\mbox{}\\
144
This gives the number of doubly occupied orbitals in each irreducible
145
representation. There is no default. If this is not given,
146
\PSIcscf\ will attempt to guess at the occupations.
147
\item[SOCC = integer vector]\mbox{} \\
148
This gives the number of singly occupied orbitals in each irreducible
149
representation. There is no default. If this is not given,
150
\PSIcscf\ will attempt to guess at the occupations.
151
\item[FREEZE\_CORE = string]\mbox{} \\
152
\PSIthree\ can automatically freeze core orbitals. Core orbitals are
160
YES or TRUE will freeze the core orbitals, SMALL or LARGE are for elements
161
Na-Ar. The default is NO or FALSE. Always check to make sure that the
162
occupations are correct!
165
\subsection{Geometry Specification} \label{geom-spec}
166
The molecular geometry may be specified using either Cartesian a
167
Z-matrix coordinates. Cartesian coordinates are specified via the
168
keyword \keyword{geometry}:
178
where \keyword{atomname$i$} can take the following values:
180
\item The element symbol: H, He, Li, Be, B, etc.
181
\item The full element name: hydrogen, helium, lithium, etc.
182
\item As a {\em ghost} atom with the symbol, G, or name, ghost. A
183
ghost atom has a formal charge 0.0, and can be useful to specify the
184
location of the off-nucleus basis functions.
185
\item As a {\em dummy} atom with the symbol, X. Dummy atoms can be
186
useful only to specify Z-matrix coordinates of proper symmetry or
187
which contain linear fragments.
189
Hence the following two examples are equivalent to one another:
203
beryllium 6.0 0.0 0.0
206
It is also possible to include an inner set
207
of parentheses around each line containing {\tt atomname1 x1 y1 z1}.
209
The keyword \keyword{units} specifies the units for the coordinates:
211
\item \keyword{units = angstrom} -- angstroms (\AA), default;
212
\item \keyword{units = bohr} -- atomic units (Bohr);
216
Z-matrix coordinates are specified using the keyword \keyword{zmat}:
220
atomname2 ref21 bond_dist2
221
atomname3 ref31 bond_dist3 ref32 bond_angle3
222
atomname4 ref41 bond_dist4 ref42 bond_angle4 ref43 tors_angle4
223
atomname5 ref51 bond_dist5 ref52 bond_angle5 ref53 tors_angle5
225
atomnameN refN1 bond_distN refN2 bond_angleN refN3 tors_angleN
230
\item \keyword{bond\_dist$i$} is the distance (in units specified by
231
keyword \keyword{units}) from nucleus number $i$ to
232
nucleus number \keyword{ref$i$1}. The units
233
\item \keyword{bond\_angle$i$} is the angle formed by nuclei $i$,
234
\keyword{ref$i$1}, and \keyword{ref$i$2};
235
\item \keyword{tors\_angle$i$} is the torsion angle formed by nuclei $i$,
236
\keyword{ref$i$1}, \keyword{ref$i$2}, and \keyword{ref$i$3};
239
%% I'm commenting this part out, since the redundant internal coordinate
240
%% structure implemented by RAK in 08/03 takes care of many dummy-atom
241
%% problems. If user's really want z-matrix coords, we may have to deal
244
%Some care has to be taken when constructing a Z-matrix for a molecule
245
%which contains linear fragments. For example, an appropriate Z-matrix
246
%for a linear conformation of HNCO must include dummy atoms: The first
247
%three atoms (HNC) can be specified as is, but the fourth atom (O)
248
%poses a problem -- the torsional angle cannot be defined with respect
249
%to the linear HNC fragment. The solution is to add 2 dummy atoms to
256
% c 2 1.234 3 90.0 1 180.0
257
% x 4 1.000 2 90.0 3 180.0
258
% o 4 1.114 5 90.0 2 180.0
261
%Alternatively, one could use, for example, only a single dummy atom above the
262
%nitrogen and specify ``bond lengths'' relative to the latter.
264
\subsection{Molecular Symmetry} \label{symm-spec}
265
\PSIthree\ can determine automatically the largest Abelian point group
266
for a valid framework of centers (including ghost atoms, but dummy
267
atoms are ignored). It will then use the symmetry porperties of the
268
system in computing the energy, forces, and other properties.
269
However, in certain instances it is desirable to use less than the
270
full symmetry of the molecule. The keyword \keyword{subgroup} is used
271
to specify a subgroup of the full molecular point group. The allowed
272
values are \keyword{c2v}, \keyword{c2h}, \keyword{d2}, \keyword{c2},
273
\keyword{cs}, \keyword{ci}, and \keyword{c1}. For certain combinations
274
of a group and its subgroup there is no unique way to determine which
275
subgroup is implied. For example, $D_{\rm 2h}$ has 3 non-equivalent
276
$C_{\rm 2v}$ subgroups, e.g. $C_{\rm 2v}(X)$ consists of symmetry
277
operations $\hat{E}$, $\hat{C}_2(x)$, $\hat{\sigma}_{xy}$, and
278
$\hat{\sigma_{xz}}$. To specify such subgroups precisely one has to
279
use the keyword \keyword{unique\_axis}. For example, the following
280
input will specify the $C_{\rm 2v}(X)$ subgroup of $D_{\rm 2h}$ to be
281
the computational point group:
295
%\caption{Standard Cotton Ordering in \PSIthree}
300
Point Group & Cotton Ordering of Irreps \\
303
C$_i$ & A$_g$ A$_u$ \\
306
C$_{2h}$ & A$_g$ B$_g$ A$_u$ B$_u$ \\
307
C$_{2v}$ & A$_1$ A$_2$ B$_1$ B$_2$ \\
308
D$_2$ & A B$_1$ B$_2$ B$_3$ \\
309
D$_{2h}$ & A$_g$ B$_{1g}$ B$_{2g}$ B$_{3g}$ A$_u$ B$_{1u}$ B$_{2u}$ B$_{3u}$ \\
316
\subsection{Specifying Scratch Disk Usage in \PSIthree} \label{scratchfiles}
318
Depending on the calculation, the \PSIthree\ package often requires
319
substantial temporary disk storage for integrals, wave function ampltiudes,
320
etc. By default, \PSIthree\ will write all such datafiles to {\tt /tmp}
321
(except for the checkpoint file, which is written to {\tt ./} by default).
322
However, to allow for various customized arrangements of scratch disks,
323
the \PSIthree\ {\tt files:} block gives the user considerable control
324
over how temporary files are organized, including file names, scratch
325
directories, and the ability to ``stripe'' files over several disks (much
326
like RAID0 systems). This section of keywords is normally placed within
327
the {\tt psi:} section of input, but may be used for specific \PSIthree\
328
modules, just like other keywords.
330
For example, if the user is working with \PSIthree\ on a computer
331
system with only one scratch disk (mounted at, e.g., {\tt /scr}), one
332
could identify the disk in the input file as follows:
344
The {\tt nvolume} keyword indicates the number of scratch
345
directories/disks to be used to stripe files, and each of these is
346
specified by a corresponding {\tt volumen} keyword. (NB: the trailing
347
slash ``/'' is essential in the directoy name.) Thus, in the above
348
example, all temporary storage files generated by the various
349
\PSIthree\ modules would automatically be placed in the {\tt /scr}
352
By default, the scratch files are given the prefix ``{\tt psi}'', and
353
named ``{\tt psi.nnn}'', where {\tt nnn} is a number used by the
354
\PSIthree\ modules. The user can select a different prefix by
355
specifying it in the input file with the {\tt name} keyword:
368
The {\tt name} keyword allows the user to store data associated with
369
multiple calculations in the same scratch area. Alternatively, one
370
may specify the filename prefix on the command-line of the {\tt psi3}
371
driver program (or any \PSIthree\ module) with the {\tt -p} argument:
376
If the user has multiple scratch areas available, \PSIthree\ files may
377
be automatically split (evenly) across them:
391
In this case, each \PSIthree\ datafile will be written in chunks (65
392
kB each) to three separate files, e.g., {\tt /scr1/psi.72}, {\tt
393
/scr2/psi.72}, and {\tt /scr3/psi.72}. The maximum number of volumes
394
allowed for striping files is eight (8), though this may be easily
395
extended in the \PSIthree\ I/O code, if necessary.
397
The format of the {\tt files} section of input also allows the user to
398
place selected files in alternative directories, such as the current
399
working directory. This feature is especially important if some of
400
the data need to be retained between calculations. For example, the
401
following {\tt files:} section will put {\tt file32} (the \PSIthree\
402
checkpoint file) into the working directory, but all scratch files
403
into the temporary areas:
414
file32: ( nvolume = 1 volume1 = "./" )
419
\subsection{The {\tt .psirc} File} \label{psirc}
421
Users of \PSIthree\ often find that they wish to use certain keywords
422
or input sections in every calculation they run, especially those
423
keywords associated with the {\tt files:} section. The {\tt .psirc}
424
file, which is kept in the user's {\tt \$HOME} directory, helps to
425
avoid repetition of keywords whose defaults are essentially user- or
426
system-specific. A typical {\tt .psirc} file would look like:
432
volume1 = "/tmp1/mylogin/"
433
volume2 = "/tmp2/mylogin/"
434
volume3 = "/tmp3/mylogin/"
436
file32: (nvolume=1 volume1 = "./")
441
\subsection{Specifying Basis Sets} \label{basis-spec}
443
\PSIthree\ uses basis sets comprised of Cartesian or spherical harmonic
444
Gaussian functions. A basis set is identified by a string, enclosed
445
in double quotes. Currently, there exist three ways to specify which
446
basis sets to use for which atoms:
448
\item \keyword{basis = string} -- all atoms use basis set type.
449
\item \keyword{basis = (string1 string2 string3 ... stringN)} --
450
\keyword{string {\em i}}
451
specifies the basis set for atom {\em i}. Thus, the number of strings
452
in the \keyword{basis} vector has to be the same as the number of
453
atoms (including ghost atoms but excluding dummy atoms). Another
454
restriction is that symmetry equivalent atoms should have same basis
455
sets, otherwise \PSIinput\ will use the string provided for the
456
so-called unique atom out of the set of symmetry equivalent ones.
466
\keyword{string {\em i}} specifies the basis set for chemical element
467
\keyword{element {\em i}}.
470
\subsubsection{Default Basis Sets}
472
\PSIthree\ default basis sets are located in \pbasisdat\ which may be
473
found by default in {\tt \$psipath/share}. Tables
474
\ref{table:poplebasis}, \ref{table:dunningbasis},
475
\ref{table:wachtersbasis}, and \ref{table:ccbasis} list basis sets
476
pre-defined in \pbasisdat.
478
The predefined basis sets use either spherical harmonics or Cartesian
479
Gaussians, which is determined by the authors of the basis.
480
Currently \PSIthree\ cannot handle basis sets that consist
481
of a mix of Cartesian and spherical harmonics Gaussians.
482
Therefore there may be combinations of basis sets that are forbidden,
483
e.g. {\tt cc-pVTZ} and {\tt 6-31G**}.
484
In such case one can override the predetermined choice
485
of the type of the Gaussians by specifying the \keyword{puream}
486
keyword. It takes two values, {\tt true} or {\tt false},
487
for spherical harmonics and Cartesian Gaussians, respectively.
490
\caption{Pople-type basis sets available in \PSIthree}
491
\label{table:poplebasis}
493
\begin{tabular}{|l|l|l|}
496
Basis Set &Atoms &Aliases\\
500
6-31G & H-Ar, K, Ca, Cu &\\
501
6-31G* & H-Ar, K, Ca, Cu &6-31G(d)\\
502
6-31+G* & H-Ar &6-31+G(d)\\
503
6-31G** & H-Ar, K, Ca, Cu &6-31G(d,p)\\
505
6-311G* & H-Ar &6-311G(d)\\
506
6-311+G* & H-Ne &6-311+G(d)\\
507
6-311G** & H-Ar &6-311G(d,p)\\
508
6-311G(2df,2pd) & H-Ne &\\
509
6-311++G** & H, B-Ar &6-311++G(d,p)\\
510
6-311G(2d,2p) & H-Ar &\\
511
6-311++G(2d,2p) & H-Ar &\\
512
6-311++G(3df,3pd) & H-Ar &\\
520
\caption{Huzinaga-Dunning basis sets available in \PSIthree}
521
\label{table:dunningbasis}
523
\begin{tabular}{|l|l|}
530
(11S7P/6S4P) & Al-Cl \\
531
DZ & H, Li, B-F, Al-Cl \\
532
DZP & H, Li, Be, B-F, Na, Al-Cl \\
533
DZ-DIF & H, B-F, Al-Cl \\
534
DZP-DIF & H, B-F, Al-Cl \\
535
TZ2P & H, B-F, Al-Cl \\
537
TZ2PF & H, B-F, Al-Cl \\
538
TZ-DIF & H, B-F, Al-Cl \\
539
TZ2P-DIF & H, B-F, Al-Cl \\
541
TZ2PF-DIF & H, B-F, Al-Cl \\
549
\caption{Wachters basis sets available in \PSIthree}
550
\label{table:wachtersbasis}
552
\begin{tabular}{|l|l|}
557
WACHTERS & K, Sc-Cu \\
558
WACHTERS-F & Sc-Cu \\
566
\caption{Correlation-consistent basis sets available in \PSIthree}
567
\label{table:ccbasis}
569
\begin{tabular}{|l|l|l|}
572
Basis Set &Atoms &Aliases\\
573
\textbf{ (N = D,T,Q,5,6)} & & \\
575
cc-pVNZ & H-Ar &CC-PVNZ\\
576
cc-pV(N+D)Z & Al-Ar &CC-PV(N+D)Z\\
577
cc-pCVNZ & B-Ne &CC-PCVNZ\\
578
aug-cc-pVNZ & H-He, B-Ne, Al-Ar &AUG-CC-PVNZ\\
579
aug-cc-pV(N+D)Z & Al-Ar &AUG-CC-PCV(N+d)Z\\
580
aug-cc-pCVNZ & B-F (N${<}$6) &AUG-CC-PCVNZ\\
581
d-aug-cc-pVNZ & H &\\
582
pV7Z\footnote{testa} & H, C, N, O, F, S &PV7Z\\
583
cc-pV7Z\footnote{testb} & H, C, N, O, F, S &CC-PV7Z\\
584
aug-pV7Z\footnote{testc} & H, C, N, O, F, S &AUG-PV7Z\\
585
aug-cc-pV7Z\footnote{testd} & H, N, O, F &AUG-CC-PV7Z\\
592
\subsubsection{Custom Basis Sets} \label{custom-basis}
594
If the basis set you desire is not already defined in \PSIthree, a
595
custom set may be used by specifying its exponents and contraction
596
coefficients (either in the input file or another file named {\tt
597
basis.dat}.) A contracted Cartesian Gaussian-type orbital
599
\phi_{\rm CGTO} = x^ly^mz^n\sum_i^N C_i \exp(-\alpha_i[x^2+y^2+z^2])
608
ATOM_NAME: "BASIS_SET_LABEL" = (
618
One must further specify whether Cartesian or spherical harmonics
619
Gaussians are to be used. One can specify that in two ways:
621
\item It can be done on a basis
622
by basis case, such as
625
"BASIS_SET_LABEL1":puream = true
626
"BASIS_SET_LABEL2":puream = false
627
"BASIS_SET_LABEL3":puream = true
631
By default, if \keyword{puream} is not given for a basis,
632
then Cartesian Gaussians will be used.
634
The choice between Cartesian or spherical harmonics Gaussian
635
can be made globally by specifying \keyword{puream} keyword
636
in the standard input section, e.g.
645
Note that currently \PSIthree\ cannot handle basis sets that consist
646
of a mix of Cartesian and spherical harmonics Gaussians.
648
Note that the basis set must be given in a separate {\tt basis:}
649
section of input, outside all other sections (including {\tt psi:}).
650
For example, the \PSIthree\ DZP basis set for carbon could be
655
(S ( 4232.6100 0.002029)
664
(P ( 18.1557 0.018534)
674
Here are a couple of additional points that may be useful when
675
specifying customized basis sets:
677
\item Normally the {\tt basis.dat} file is placed in the same
678
directory as the main input file, but it may also be placed in a
679
global location specified by the keyword {\tt basisfile}:
681
basisfile = "/home/users/tool/chem/h2o/mybasis.in"
683
\item To scale a basis set, a scale factor may be added as the last item
684
in the specification of each contracted Gaussian function. For
685
example, to scale the S functions in a 6-31G** basis for hydrogen,
686
one would use the following
688
hydrogen: "6-31G**" =
689
( (S ( 18.73113696 0.03349460)
690
( 2.82539437 0.23472695)
691
( 0.64012169 0.81375733) 1.2 )
692
(S ( 0.16127776 1.00000000) 1.2 )
693
(P ( 1.10000000 1.00000000))
696
In this example, both contracted S functions have their exponents
697
scaled by a factor of (1.2)$^2$ = 1.44. The output file should show
698
the exponents after scaling.
701
\subsubsection{Automated Conversion of Basis Sets}
703
The \PSIthree\ package is distributed with a Perl-based utility, named {\tt
704
g94\_2\_PSI3}, which will convert basis sets from the Gaussian ('94 or later)
705
format to \PSIthree\ format automatically. This utility is especially useful
706
for basis sets downloaded from the EMSL database at \htmladdnormallink{{\tt
707
http://www.emsl.pnl.gov/forms/basisform.html}}{http://www.emsl.pnl.gov/forms/basisform.html}.
708
To use this utility, save the desired basis set to a file (e.g., {\tt
709
g94\_basis.dat}) in the Gaussian format. Then execute:
711
g94_2_PSI3 < g94_basis.dat > basis.dat
713
You may either incorporate the results from the {\tt basis.dat} file into
714
your input file as described above, or place the results into a global {\tt
715
basis.dat} file. Be sure to surround the basis-set definition with the
716
{\tt basis:()} keyword (as shown in the above examples) or input parsing
719
\subsection{Specification of Ghost Atoms}
721
To specify ghost atoms, use atom symbol \keyword{G} in
722
\keyword{zmat} or \keyword{geometry} keywords:
728
basis = "aug-cc-pVTZ"
730
Basis sets for ghost atoms
731
must be defined explicitly using \keyword{GHOST} as the element name:
733
basis:GHOST:"aug-cc-pVTZ": (
737
This method leads to replication of existing basis set
739
It is usually more convenient to specify ghost atoms as regular atoms
747
basis = "aug-cc-pVTZ"
749
In this example, the second helium atom is a ``ghost'' atom which carries
750
helium's aug-cc-pVTZ basis set.
added
removed
doc/userman/input.tex
